Global feature flags
Experimental runtime features can be overridden for a single process with top-level flags:config.toml. Use coral features enable <FEATURE> or
coral features disable <FEATURE> to persist a preference.
Global workspace selection
Coral does not create a workspace for you. A fresh install has none, so create one before running a command that works on workspace state:--workspace <NAME>, the global flag, wins over everything else.CORAL_WORKSPACE, when it holds a non-empty value. An empty value is treated as unset, so an exported-but-blank variable falls through instead of travelling to the server as a workspace named"".- The only workspace you have, when you have exactly one.
When Coral cannot pick for you
Without an explicit selection, Coral resolves the workspace only when you have exactly one. Zero and several are different problems, so they are reported as different errors, and neither is settled by substituting a name. You have none. The error names every way to obtain one:CORAL_WORKSPACE in
your shell when you want the same workspace for repeated commands.
default is an ordinary workspace name
default has no reserved status. Coral does not provision a workspace with
that name, does not fall back to it, and does not protect it from removal.
default, default-team, and work are all ordinary names that resolve only
when a workspace you can reach actually has that name — so a command naming
default on an install that never created one fails like any other unknown
name.
coral sql
Run one SQL query and exit.
Options
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:
DESCRIBE expects a table. To inspect table functions, including their
descriptions and guides, query coral.table_functions.
DESCRIBE SELECT ... still describes the result schema of the query itself.
coral search
Find relevant Coral tables, table functions, columns, filters, and values Coral
has observed during earlier queries. The query must include at least one term
with three or more characters.
sql_reference or sql_call_example. When the observed_values_search feature
is enabled, search also reads observed-value memory; those results identify the
value and the surface and column where Coral saw it. Use those clues with
coral sql to fetch current rows.
Observed-value collection, retrieval, and maintenance are disabled by default.
Enable them persistently using Coral runtime features.
Options
JSON response
With--json, the response separates results, provider_statuses, and
truncation. Each result is one table or table function. It includes its
kind, SQL reference, contributing providers, and available description or
guide. Table results can include fields and required. Function results can
include arguments, required, and returns. Matching observed values are
grouped by field in matching_values on the same result.
The catalog_metadata and observed_values provider statuses report whether
each local search found matches, completed with no matches, returned partial
coverage, or failed. An empty observed-value result only describes Coral’s
local observations; it does not prove that the value is absent from a connected
source. truncation reports when more matches were available than returned.
coral search-index
Manage Coral’s local search indexes.
coral search-index rebuild
Rebuild one or all local search indexes. Coral skips a catalog rebuild when its
projection is already current unless you pass --force. The observed-value
projection is always rebuilt when selected.
Rebuild operates only on Coral’s local search state. It does not query connected
sources or discover new values.
A rebuild performs the same workspace runtime and catalog preparation as
coral search. It can read stored credentials, initialize source providers,
and inspect file metadata in local or object storage, but it does not execute a
data query. Observed-value index maintenance reads Coral’s local search state.
Options
coral search-index drain
Drain pending observed-value writes into the local search projection so those
values can be returned by search.
Drain operates only on values Coral has already observed. It does not query
connected sources.
Options
coral search-index clear
Clear Coral’s local search data for one workspace.
Clear deletes local search data, so Coral requires both --yes and an explicit
--workspace NAME.
--source accepts the installed source name, which is also its SQL schema
name. It clears the selected scope for that source.
Options
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.
installed or still available.
coral source list
List sources currently installed.
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.
Options
coral source add <NAME>
Add a bundled source, update its credentials, or import a custom source spec.
Options
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. When an OAuth
method declares Dynamic Client Registration, Coral registers the OAuth client
during this interactive setup before printing the authorization URL. 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.
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 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 remove <NAME>
Remove an installed source.
coral workspace
Manage local workspaces. Workspaces isolate installed source metadata and
workspace-scoped artifacts such as source manifests, local credential material,
feedback reports, 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.
These commands manage the workspaces on the Coral install running on this
machine. They are not an administration tool for a shared deployment: a
deployment that has [auth] configured has its own accounts, memberships, and
roles, which are not managed from this CLI — see
Shared server access control for how
membership is administered.
coral workspace list
List the workspaces available to you and your role in each.
Workspace and Role table. When you have none — which is the
state of a fresh install — it prints No workspaces available. instead.
coral workspace create <NAME>
Create an empty workspace. This is the only way a workspace comes into
existence: nothing provisions one at install, on first run, or on demand. The
workspace belongs to whoever created it; on a deployment that authenticates no
one, that is the local user.
default is accepted here like any other name, and means nothing more than the
five letters. A name is trimmed of surrounding whitespace and must be non-empty,
must not be . or .., and must not contain / or \. Creating a name that
already exists fails rather than adopting the existing workspace.
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; trace pruning happens after the removal is committed, so a
failure there is logged as a warning and does not bring the workspace back.
default. If
you remove the last one, the install is back to having none, and
workspace-scoped commands fail with the guidance above until you create another.
coral functions
Manage workspace functions. A function is a SQL artifact with SQL comment frontmatter that defines a reusable, typed query and publishes it as a SQL table function.
User-installed functions are added to the current workspace with coral functions add. Functions commonly publish under functions.*.
coral functions add --file <PATH>
Validate, then install or replace, a user-installed function from a SQL artifact.
Options
Coral validates the function before storing it in the current workspace. Validation checks the frontmatter shape, installed-source references, SQL publish target collisions, and whether the SQL plans against the current workspace sources. Result columns are inferred from the planned SQL. If runtime validation fails, the function is not installed.
Example function:
schema and name frontmatter fields expose the function through SQL as schema.name(...). The optional guide appears in catalog and search metadata for agents and users choosing how to query the function. Coral infers each required argument and its type from $argument uses in the SQL body. If the surrounding SQL does not provide enough type evidence, add an explicit cast such as cast($limit as BIGINT).
coral functions list
List configured functions.
invalid status and an actionable reason below the table.
If a function publishes a SQL table function and declares required inputs, call it with named arguments:
coral functions remove <NAME>
Remove the user-installed function named <NAME>.
coral onboard
Run the guided source setup flow.
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 enable <FEATURE>
Persistently enables an experimental runtime feature. The default for each
feature is listed in Configuration.
coral features disable <FEATURE>
Persistently disables an experimental runtime feature.
coral server
Start a long-running native gRPC server. Coral prints the selected endpoint and
a CORAL_ENDPOINT hint for clients, then runs until you press Ctrl-C or send
SIGTERM on Unix. When [server.mcp_http] is enabled, it also prints the MCP
Streamable HTTP listener’s per-workspace URL template.
[server].bind_addr. Without a [server] section,
Coral uses an ephemeral port on 127.0.0.1. See
Configuration. To run the server as a
container, see Self-host Coral with Docker.
Which workspace MCP HTTP serves
coral server selects no workspace at all, and ignores --workspace and
CORAL_WORKSPACE: every gRPC request names the workspace it targets, and the
MCP Streamable HTTP listener it can start alongside gRPC serves every
workspace at its own URL — /mcp/workspace/{workspace} on the listener, and
<public_url>/workspace/{workspace} when [auth] is configured (the prefix
comes from server.mcp_http.public_url). Which workspace an MCP session
reaches is decided by the URL the client connects to — never by
configuration, and never on the caller’s behalf.
Whether a URL serves is answered per handshake, not at startup: a workspace
created while the server runs is immediately reachable at its URL, a deleted
one immediately answers not-found to new sessions, and a fresh install with no
workspaces starts fine and serves its first workspace the moment
coral workspace create makes one. Creating more workspaces never changes how
the server starts — it just adds URLs.
Without [auth] the listener is unauthenticated and refuses non-loopback
binds unless server.mcp_http.allow_unauthenticated_non_loopback explicitly
opts in (see Configuration): requests
act as the built-in local user, with full access to every workspace’s URL.
With [auth] the listener is authenticated and a session is admitted only
when the URL’s workspace is among the calling token’s own memberships. See
Configuration and
Shared server access control.
coral mcp-stdio
Expose the local Coral runtime as an MCP stdio server.
--workspace NAME, then CORAL_WORKSPACE, then your only workspace if you have
exactly one. Because a client launches it non-interactively, the zero-workspace
and several-workspaces errors surface as the server failing to start rather than
as a prompt — so put --workspace in the client’s args as soon as you have more
than one workspace. See
Global workspace selection.
By default, this server exposes:
add_function accepts schema, name, description, and one read-only SQL query. Values such as $owner in the query become required named arguments. It never overwrites an existing function, and Coral validates the function before saving it.
describe accepts schema and a bare surface name. Add catalog for a
three-part table. Coral resolves whether the surface is a table or table
function. An exact result returns the surface kind and metadata without
repeating the requested target. A missing result returns kind: missing.
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.
When observed_values_search is disabled, the search tool and
coral://guide advertise catalog discovery only. Enable observed-value search
for one MCP server process with
coral --enable-observed-values-search mcp-stdio.
Discovery helpers include the coral system schema, so search,
list_catalog, describe, 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.