Spice.ai OSS CLI command reference
spice​
Usage​
spice [command] [--help]
Full Command Reference​
| Command | Description |
|---|---|
| acceleration | Manage dataset acceleration features |
| add | Add Spicepod - adds a Spicepod to the project |
| agy | Run the Antigravity CLI with the Spice runtime as its model backend |
| catalog | Add or configure catalog entries in spicepod.yaml |
| catalogs | List catalogs loaded by the Spice runtime |
| chat | Chat with an LLM |
| claude | Run Claude Code with the Spice runtime as its model backend |
| codex | Run Codex CLI with the Spice runtime as its model backend |
| completions | Generate shell completions for the Spice CLI |
| cloud | Manage Spice Cloud resources |
| cluster | Cluster operations for the Spice runtime |
| connect | Deprecated alias for adding a Spicepod dependency |
| copilot | Run GitHub Copilot CLI with the Spice runtime as its model backend |
| cursor | Run Cursor CLI with the Spice runtime as its model backend |
| dataset | Add or configure dataset entries in spicepod.yaml |
| datasets | Lists datasets loaded by the Spice runtime |
| embedding | Add or configure embedding entries in spicepod.yaml |
| extension | Add or configure entries under extensions: in spicepod.yaml |
| feedback | Open the Spice.ai community Slack to share feedback |
| function | Add or configure function entries in spicepod.yaml |
| grok | Run Grok Build with the Spice runtime as its model backend |
| help | Help about any command |
| init | Initialize Spice app - creates a new spicepod.yaml |
| install | Install or reinstall the Spice.ai runtime |
| login | Login to Spice.ai or configure credentials for data sources |
| management | Configure the management: section of spicepod.yaml |
| metadata | Add or configure key/value entries under metadata: in spicepod.yaml |
| model | Add or configure model entries in spicepod.yaml |
| models | Lists models loaded by the Spice runtime |
| nsql | Text-to-SQL REPL - translate natural language to SQL |
| opencode | Run OpenCode with the Spice runtime as its model backend |
| orca | Run Orca with every coding agent it starts on the Spice runtime |
| pi | Run pi with the Spice runtime as its model backend |
| pods | Lists Spicepods loaded by the Spice runtime |
| query | Submit an async query or start an interactive async query REPL |
| refresh | Refresh a dataset loaded by the Spice runtime |
| reranker | Add or configure reranker entries in spicepod.yaml |
| run | Run Spice - starts the Spice runtime, installing if necessary |
| runtime | Configure the runtime: section of spicepod.yaml |
| search | Search datasets with embeddings |
| secret | Add or configure secret entries in spicepod.yaml |
| snapshots | Configure the snapshots: section of spicepod.yaml |
| sql | Start an interactive SQL query session against the Spice runtime |
| spiced | Spice runtime binary — direct invocation reference |
| status | Spice runtime status |
| tool | Add or configure tool entries in spicepod.yaml |
| trace | Return traces for operations that occurred in Spice |
| upgrade | Upgrades the Spice CLI and runtime to the latest or specified version |
| validate | Validate a spicepod.yaml without starting the runtime |
| version | Spice CLI version |
| view | Add or configure view entries in spicepod.yaml |
| worker | Add or configure worker entries in spicepod.yaml |
| workers | Lists workers loaded by the Spice runtime |
Spicepod manifest editors​
catalog, dataset, embedding, function, model, reranker, secret, tool, view, and worker all edit the matching list section of spicepod.yaml and share the same two subcommands and body flags:
spice <component> add <name> [body flags] # add a new entry; fails if it already exists
spice <component> configure <name> [body flags] # add or update an entry in place
runtime, management, and snapshots edit singleton sections, so they expose only configure. extension edits the extensions: map (add and configure), and metadata edits the metadata: map (add, configure, and set <KEY> <VALUE>).
See spice dataset for the shared body-flag reference. The other list editors accept the same flags, plus the type-specific ones: --sql / --sql-ref for views, --cron for workers, and --body / --body-ref for functions. Run spice <command> --help for the per-command help.
Command Flags​
The following flags are global — they are accepted by every command:
| Flag | Description |
|---|---|
-h, --help | Print the help message. |
-v, --verbose | Increase log verbosity. -v for debug, -vv for trace. |
--machine | Machine-readable mode for LLMs and automation: prefer JSON output where supported, and always emit structured JSON errors. Alias: --programmatic. |
--api-key <key> | API key used to authenticate with the runtime or the Spice.ai Cloud Platform. Also read from the SPICE_API_KEY environment variable. |
--cloud | Target the Spice.ai Cloud Platform instead of a local runtime. Requires --api-key. |
--cloud-region <region> | Spice.ai Cloud Platform runtime endpoint region, used with --cloud. Defaults to us-east-1. |
--http-endpoint <endpoint> | HTTP endpoint of the Spice runtime to talk to. Defaults to http://127.0.0.1:8090. |
--tls-root-certificate-file <file> | Path to a PEM root certificate used to verify the runtime's TLS server certificate. It applies to spice sql over Flight and to commands that call the runtime's HTTP API, such as spice status, spice datasets, and spice refresh. spice query does not use it, and neither does the task-history lookup that spice nsql analyze runs after each request. Downloads from the Spicepod registry by spice add and spice connect use the system root certificates. |
When the runtime's certificate fails verification, the commands that use this flag over HTTP report the reason instead of saying the runtime is unavailable, for example TLS certificate verification failed for https://127.0.0.1:8090: unknown issuer. Pass --tls-root-certificate-file with the CA certificate that issued the runtime's certificate. A file that cannot be read or holds no certificate fails with Could not load the TLS root certificate file '<path>': <reason>. With --machine, the two errors have the codes tls_verification_failed and tls_root_certificate.
In v2.4.0 and earlier, only spice sql used this flag. Commands that call the runtime over HTTP, such as spice status and spice datasets, ignored it and failed with The Spice runtime is unavailable at <endpoint>. Is it running?.
