CLI reference

Global feature flags

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

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.

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.

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:

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 available in your current Coral build.

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.

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.

coral source info datadog

Options

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

coral source info datadog --verbose

`coral source add <NAME>`

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

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.

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.

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.

coral source test github
coral source test local_messages

`coral source remove <NAME>`

Remove an installed source.

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.

coral workspace list

`coral workspace create <NAME>`

Create an empty workspace.

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.

coral workspace remove work

The default workspace cannot be removed.

`coral onboard`

Run the guided source setup flow.

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.

`coral features list`

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

coral features list

`coral features enable <FEATURE>`

Persistently enables an experimental runtime feature. The default for each feature is listed in Configuration.

coral features enable feedback

`coral features disable <FEATURE>`

Persistently disables an experimental runtime feature.

coral features disable feedback

`coral ui`

Open the local Coral UI in your browser.

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:

coral ui --port 1458

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

coral ui --no-open

`coral mcp-stdio`

Expose the local Coral runtime as an MCP stdio server.

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.

`coral completion <SHELL>`

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

coral completion zsh > ~/.zsh/completions/_coral

To enable completions in the current shell without installing them:

source <(coral completion bash)

Get started

Guides

Reference

Project

Global feature flags

Global workspace selection

`coral sql`

Options

`coral source`

`coral source discover`

`coral source list`

`coral source info <NAME>`

Options

`coral source add <NAME>`

Options

`coral source lint <FILE>`

`coral source test <NAME>`

`coral source remove <NAME>`

`coral workspace`

`coral workspace list`

`coral workspace create <NAME>`

`coral workspace remove <NAME>`

`coral onboard`

`coral features`

`coral features list`

`coral features enable <FEATURE>`

`coral features disable <FEATURE>`

`coral ui`

Options

`coral mcp-stdio`

`coral completion <SHELL>`

​Global feature flags

​Global workspace selection

​coral sql

​Options

​coral source

​coral source discover

​coral source list

​coral source info <NAME>

​Options

​coral source add <NAME>

​Options

​coral source lint <FILE>

​coral source test <NAME>

​coral source remove <NAME>

​coral workspace

​coral workspace list

​coral workspace create <NAME>

​coral workspace remove <NAME>

​coral onboard

​coral features

​coral features list

​coral features enable <FEATURE>

​coral features disable <FEATURE>

​coral ui

​Options

​coral mcp-stdio

​coral completion <SHELL>

Global feature flags

Global workspace selection

`coral sql`

Options

`coral source`

`coral source discover`

`coral source list`

`coral source info <NAME>`

Options

`coral source add <NAME>`

Options

`coral source lint <FILE>`

`coral source test <NAME>`

`coral source remove <NAME>`

`coral workspace`

`coral workspace list`

`coral workspace create <NAME>`

`coral workspace remove <NAME>`

`coral onboard`

`coral features`

`coral features list`

`coral features enable <FEATURE>`

`coral features disable <FEATURE>`

`coral ui`

Options

`coral mcp-stdio`

`coral completion <SHELL>`