> ## Documentation Index
> Fetch the complete documentation index at: https://withcoral.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

> Reference for Coral CLI commands and options.

## Global feature flags

Experimental runtime features can be overridden for a single process with
top-level flags:

```shellscript theme={"theme":{"light":"github-light","dark":"github-dark"}}
coral --enable-<FEATURE> <COMMAND>
coral --disable-<FEATURE> <COMMAND>
coral --enable-feedback mcp-stdio
coral --disable-feedback mcp-stdio
```

These flags do not edit `config.toml`. Use `coral features enable <FEATURE>` or
`coral features disable <FEATURE>` to persist a preference.

## Global workspace selection

Commands that operate on local source state target the `default` workspace
unless you select another workspace.

```shellscript theme={"theme":{"light":"github-light","dark":"github-dark"}}
coral --workspace work source list
coral source add github --workspace work
coral mcp-stdio --workspace work
CORAL_WORKSPACE=work coral sql "select * from coral.tables"
```

The `--workspace <NAME>` flag overrides `CORAL_WORKSPACE` for that process.
Coral does not persist a separate active-workspace setting; set
`CORAL_WORKSPACE` in your shell when you want a default for repeated commands.

## `coral sql`

Run one SQL query and exit.

```shellscript theme={"theme":{"light":"github-light","dark":"github-dark"}}
coral sql "<SQL>"
```

### Options

| Option     | Type              | Default | Description   |
| ---------- | ----------------- | ------- | ------------- |
| `--format` | `table` \| `json` | `table` | Output format |

JSON output is an array of row objects. Selected nullable columns are included with explicit `null` values when the row value is null.

Use `DESCRIBE <schema>.<table>` to inspect a table's result columns:

```shellscript theme={"theme":{"light":"github-light","dark":"github-dark"}}
coral sql "DESCRIBE datadog.hosts"
```

`DESCRIBE` expects a table. To inspect table functions, query
`coral.table_functions`.

`DESCRIBE SELECT ...` still describes the result schema of the query itself.

## `coral source`

Manage configured sources, either the bundled ones, or your custom source specs.

### `coral source discover`

List the [bundled sources](/docs/reference/bundled-sources) available in your current Coral build.

```shellscript theme={"theme":{"light":"github-light","dark":"github-dark"}}
coral source discover
```

The output includes each source name, the bundled version currently shipped in the binary, and whether it is already `installed` or still `available`.

### `coral source list`

List sources currently installed.

```shellscript theme={"theme":{"light":"github-light","dark":"github-dark"}}
coral source list
```

The output includes the source's secret storage route: `keychain` or
`file (plaintext)`.

### `coral source info <NAME>`

Show metadata for a source: whether it is installed, its origin, version, description, and inputs. Works for bundled sources and imported sources installed via `coral source add --file`.

```shellscript theme={"theme":{"light":"github-light","dark":"github-dark"}}
coral source info datadog
```

#### Options

| Option            | Type | Default | Description                                  |
| ----------------- | ---- | ------- | -------------------------------------------- |
| `-v`, `--verbose` | flag | `false` | Show additional details, such as input hints |

```shellscript theme={"theme":{"light":"github-light","dark":"github-dark"}}
coral source info datadog --verbose
```

### `coral source add <NAME>`

Add a bundled source, update its credentials, or import a custom source spec.

```shellscript theme={"theme":{"light":"github-light","dark":"github-dark"}}
GITHUB_TOKEN=ghp_... coral source add github
coral source add --file ./local-messages.yaml
```

#### Options

| Option          | Type | Default                  | Description                                                       |
| --------------- | ---- | ------------------------ | ----------------------------------------------------------------- |
| `--file <PATH>` | path | required unless `<NAME>` | Source spec YAML file to import                                   |
| `--interactive` | flag | `false`                  | Prompt for source inputs instead of reading environment variables |

By default, Coral reads each declared input from an environment variable of the
same name. If a required input is missing, the command exits with an error
listing the missing keys.

Pass `--interactive` to be prompted for variables and secrets instead. If a
missing secret declares credential methods, Coral shows those choices in the
source spec's authored order. `source_config` methods use the normal source
input path and prompt for the secret value here; OAuth methods open or print an
authorization URL or device verification URL, wait for provider completion, and
store the resulting access token without printing token material. If the
provider returns refresh metadata, Coral keeps it internally so short-lived
OAuth access tokens can be refreshed without re-running `coral source add`.
If the browser runs somewhere that cannot reach Coral's loopback listener, such
as a host browser authorizing a Coral process in a VM or SSH session, paste the
final localhost redirect URL into the terminal prompt and Coral submits it to
the local callback listener.
Environment variables still win, so a secret value already present in the
environment bypasses the retrieval choice.

```shellscript theme={"theme":{"light":"github-light","dark":"github-dark"}}
coral source add --interactive github
```

If the source is already installed, running this command again replaces its stored credentials with the new values you provide. After installation, it prints the discovered tables and runs any optional top-level `test_queries` declared in the source spec to validate the connection. Any post-install validation issue is reported as a warning here so the source remains installed and re-runnable.

Sources use OS credential storage by default when Coral can write, read, and
delete a keychain probe item. If the keychain is unavailable in `auto` mode,
Coral stores the source secrets in plaintext file storage and shows
`file (plaintext)` in source output. Sources with no stored secret material show
`none`.

### `coral source lint <FILE>`

Validate a source spec YAML file without installing it. Checks YAML syntax, JSON schema conformance, and semantic rules such as duplicate columns or references to unknown filters.

```shellscript theme={"theme":{"light":"github-light","dark":"github-dark"}}
coral source lint ./my-source.yaml
```

### `coral source test <NAME>`

Validate that an installed source can initialize, expose tables, and run any optional top-level `test_queries` declared in its source spec. The command errors when one or more declared query tests fail.

```shellscript theme={"theme":{"light":"github-light","dark":"github-dark"}}
coral source test github
coral source test local_messages
```

### `coral source remove <NAME>`

Remove an installed source.

```shellscript theme={"theme":{"light":"github-light","dark":"github-dark"}}
coral source remove github
```

## `coral workspace`

Manage local workspaces. Workspaces isolate installed source metadata and
workspace-scoped artifacts such as source manifests, local credential material,
feedback reports, episode logs, and workspace-attributed local trace history.

Imported source specs and source credential material are attached to the source
installation in that workspace. Reusable global source specs and reusable
credential references are separate concepts and are not represented by
`coral workspace` today.

### `coral workspace list`

List configured workspaces.

```shellscript theme={"theme":{"light":"github-light","dark":"github-dark"}}
coral workspace list
```

### `coral workspace create <NAME>`

Create an empty workspace.

```shellscript theme={"theme":{"light":"github-light","dark":"github-dark"}}
coral workspace create work
```

### `coral workspace remove <NAME>`

Remove a workspace and its workspace-scoped source/artifact directory. When
trace history is enabled, this also prunes local trace records attributed to
that workspace. If trace cleanup fails, workspace removal fails and leaves the
workspace configured.

```shellscript theme={"theme":{"light":"github-light","dark":"github-dark"}}
coral workspace remove work
```

The `default` workspace cannot be removed.

## `coral onboard`

Run the guided source setup flow.

```shellscript theme={"theme":{"light":"github-light","dark":"github-dark"}}
coral onboard
```

When a secret input declares credential methods, onboarding asks which method
to use before consuming a matching environment variable. Choosing a
`source_config` method still uses the normal environment-variable or prompt
path.

## `coral features`

Coral ships with experimental runtime features that can be enabled on demand.
These features are defined in [`config.toml`](/docs/reference/configuration).

### `coral features list`

List all runtime features recognized by the current Coral binary, including their configured and effective status.

```shellscript theme={"theme":{"light":"github-light","dark":"github-dark"}}
coral features list
```

### `coral features enable <FEATURE>`

Persistently enables an experimental runtime feature. The default for each
feature is listed in [Configuration](/docs/reference/configuration#runtime-features).

```shellscript theme={"theme":{"light":"github-light","dark":"github-dark"}}
coral features enable feedback
```

### `coral features disable <FEATURE>`

Persistently disables an experimental runtime feature.

```shellscript theme={"theme":{"light":"github-light","dark":"github-dark"}}
coral features disable feedback
```

## `coral ui`

Open the local Coral UI in your browser.

```shellscript theme={"theme":{"light":"github-light","dark":"github-dark"}}
coral ui
```

### Options

| Option      | Type | Default | Description                                       |
| ----------- | ---- | ------- | ------------------------------------------------- |
| `--port`    | port | `1457`  | Loopback port for the local browser-facing server |
| `--no-open` | flag | `false` | Start the server without opening a browser        |

The UI opens at `http://127.0.0.1:1457` by default, which only accepts connections from your machine. The command keeps running until you press `Ctrl-C`.

The host is fixed to `127.0.0.1`. Use `--port` to bind a different loopback port:

```shellscript theme={"theme":{"light":"github-light","dark":"github-dark"}}
coral ui --port 1458
```

Use `--no-open` to start the same loopback server without launching a browser:

```shellscript theme={"theme":{"light":"github-light","dark":"github-dark"}}
coral ui --no-open
```

## `coral mcp-stdio`

Expose the local Coral runtime as an MCP stdio server.

```shellscript theme={"theme":{"light":"github-light","dark":"github-dark"}}
coral mcp-stdio
coral mcp-stdio --workspace work
```

This command is intended to be launched by an MCP-capable client rather than used directly in an interactive shell.

By default, this server exposes:

| Type     | Name             | Description                                                                                          |
| -------- | ---------------- | ---------------------------------------------------------------------------------------------------- |
| Tool     | `sql`            | Execute read-only SQL against the Coral database                                                     |
| Tool     | `list_catalog`   | List database tables and table functions with pagination                                             |
| Tool     | `search_catalog` | Search database catalog metadata with a Rust regex                                                   |
| Tool     | `describe_table` | Show compact metadata for one database table                                                         |
| Tool     | `list_columns`   | List columns for one database table with pagination                                                  |
| Resource | `coral://guide`  | Database workflow guide for agents                                                                   |
| Resource | `coral://tables` | JSON summaries of query-visible database tables, including Coral catalog tables and required filters |

When the `feedback` feature is enabled, the server also exposes a non-read-only `feedback` tool for blocked-agent reports. Feedback reports are stored locally and anonymous copies may be uploaded to Coral.

Catalog helpers include the `coral` system schema, so `list_catalog`,
`search_catalog`, `describe_table`, `list_columns`, and `coral://tables` can discover
`coral.tables`, `coral.columns`, `coral.filters`, `coral.table_functions`, and
`coral.inputs`.

For client setup, see [Use Coral over MCP](/docs/guides/use-coral-over-mcp).

## `coral completion <SHELL>`

Generate a shell completion script and write it to standard output. Supported shells are `bash`, `zsh`, `fish`, `elvish`, and `powershell`.

```shellscript theme={"theme":{"light":"github-light","dark":"github-dark"}}
coral completion zsh > ~/.zsh/completions/_coral
```

To enable completions in the current shell without installing them:

```shellscript theme={"theme":{"light":"github-light","dark":"github-dark"}}
source <(coral completion bash)
```