diff --git a/website/versioned_docs/version-2.0.x/cli/reference/catalogs.md b/website/versioned_docs/version-2.0.x/cli/reference/catalogs.md index 994815eee..ae20f4580 100644 --- a/website/versioned_docs/version-2.0.x/cli/reference/catalogs.md +++ b/website/versioned_docs/version-2.0.x/cli/reference/catalogs.md @@ -20,6 +20,7 @@ List [catalogs](../../components/catalogs) currently loaded by the Spice runtime #### Flags - `--tls-root-certificate-file` The path to the root certificate file used to verify the Spice.ai runtime server certificate +- `-o`, `--output ` Output format: `table` (default) or `json`. ### Example diff --git a/website/versioned_docs/version-2.0.x/cli/reference/chat.md b/website/versioned_docs/version-2.0.x/cli/reference/chat.md index 443381a8d..8f6111445 100644 --- a/website/versioned_docs/version-2.0.x/cli/reference/chat.md +++ b/website/versioned_docs/version-2.0.x/cli/reference/chat.md @@ -33,6 +33,7 @@ spice chat [flags] [] - `--temperature ` Model temperature used for chat request. - `--endpoint ` Specifies the remote Spice instance HTTP endpoint (e.g., `http://localhost:8090`). - `--headers ` Custom HTTP headers in format `Key:Value` (can be specified multiple times). +- `--output `, `-o` Output format: `table` (default) or `json`. ## Examples diff --git a/website/versioned_docs/version-2.0.x/cli/reference/datasets.md b/website/versioned_docs/version-2.0.x/cli/reference/datasets.md index c0f155401..5a20b7949 100644 --- a/website/versioned_docs/version-2.0.x/cli/reference/datasets.md +++ b/website/versioned_docs/version-2.0.x/cli/reference/datasets.md @@ -16,6 +16,7 @@ spice datasets [flags] #### Flags - `--tls-root-certificate-file` The path to the root certificate file used to verify the Spice.ai runtime server certificate +- `-o`, `--output ` Output format: `table` (default) or `json`. - `-h`, `--help` help for datasets ### Examples: diff --git a/website/versioned_docs/version-2.0.x/cli/reference/index.md b/website/versioned_docs/version-2.0.x/cli/reference/index.md index 80029d51f..4f8a51730 100644 --- a/website/versioned_docs/version-2.0.x/cli/reference/index.md +++ b/website/versioned_docs/version-2.0.x/cli/reference/index.md @@ -43,13 +43,22 @@ spice [command] [--help] | [spiced](reference/spiced) | Spice runtime binary — direct invocation reference | | [status](reference/status) | Spice runtime status | | [trace](reference/trace) | Return traces for operations that occurred in Spice | -| [upgrade](reference/upgrade) | Upgrades the Spice CLI and runtime to the latest release | +| [upgrade](reference/upgrade) | Upgrades the Spice CLI and runtime to the latest or specified version | | [validate](reference/validate) | Validate a spicepod.yaml without starting the runtime | | [version](reference/version) | Spice CLI version | | workers | Lists workers loaded by the Spice runtime | ### Command Flags -All commands have a help flag **--help** or **-h** to print its usage documentation: +The following flags are global — they are accepted by every command: -- **--help** | **-h** : Print the help message +| 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 ` | 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 ` | Spice.ai Cloud Platform runtime endpoint region, used with `--cloud`. Defaults to `us-east-1`. | +| `--http-endpoint ` | HTTP endpoint of the Spice runtime to talk to. Defaults to `http://127.0.0.1:8090`. | +| `--tls-root-certificate-file ` | Path to a PEM root certificate used to verify the runtime's TLS server certificate. | diff --git a/website/versioned_docs/version-2.0.x/cli/reference/models.md b/website/versioned_docs/version-2.0.x/cli/reference/models.md index 04ee092d5..2cb3a84e8 100644 --- a/website/versioned_docs/version-2.0.x/cli/reference/models.md +++ b/website/versioned_docs/version-2.0.x/cli/reference/models.md @@ -16,6 +16,7 @@ spice models [flags] #### Flags - `--tls-root-certificate-file` The path to the root certificate file used to verify the Spice.ai runtime server certificate +- `-o`, `--output ` Output format: `table` (default) or `json`. - `-h`, `--help` help for models ### Examples diff --git a/website/versioned_docs/version-2.0.x/cli/reference/pods.md b/website/versioned_docs/version-2.0.x/cli/reference/pods.md index 80de82f2f..d6edef4af 100644 --- a/website/versioned_docs/version-2.0.x/cli/reference/pods.md +++ b/website/versioned_docs/version-2.0.x/cli/reference/pods.md @@ -15,6 +15,7 @@ spice pods [flags] #### Flags - `--tls-root-certificate-file` The path to the root certificate file used to verify the Spice.ai runtime server certificate +- `-o`, `--output ` Output format: `table` (default) or `json`. - `-h`, `--help` help for pods ### Examples diff --git a/website/versioned_docs/version-2.0.x/cli/reference/refresh.md b/website/versioned_docs/version-2.0.x/cli/reference/refresh.md index cedad6ec6..7f3643099 100644 --- a/website/versioned_docs/version-2.0.x/cli/reference/refresh.md +++ b/website/versioned_docs/version-2.0.x/cli/reference/refresh.md @@ -20,6 +20,8 @@ spice refresh [dataset] [flags] - `--tls-root-certificate-file` The path to the root certificate file used to verify the Spice.ai runtime server certificate - `--refresh-sql` SQL used to refresh the dataset, see [Refresh SQL docs](../../features/data-acceleration/data-refresh#refresh-sql). - `--refresh-mode` Refresh mode to use, see [Refresh Modes docs](../../features/data-acceleration/data-refresh#refresh-modes). +- `--refresh-jitter-max` Maximum [jitter](../../features/data-acceleration/data-refresh#refresh-jitter) applied to the refresh, as a [duration](../../reference/duration) (e.g. `1m`). +- `-o`, `--output ` Output format: `table` (default) or `json`. - `-h`, `--help` Print this help message ### Examples diff --git a/website/versioned_docs/version-2.0.x/cli/reference/sql.md b/website/versioned_docs/version-2.0.x/cli/reference/sql.md index e7ea95799..04be277f5 100644 --- a/website/versioned_docs/version-2.0.x/cli/reference/sql.md +++ b/website/versioned_docs/version-2.0.x/cli/reference/sql.md @@ -23,6 +23,7 @@ spice sql [flags] - `--client-tls-key-file ` The path to the client private key file for mTLS authentication. Must be used together with `--client-tls-certificate-file`. - `--headers ` Custom HTTP headers in format `Key:Value` (can be specified multiple times). - `-x`, `--expanded` Start the REPL in expanded view, rendering each column on its own line per record. Useful for wide tables. Can be toggled at runtime with the `.expanded` meta-command. +- `-o`, `--output ` Output format: `table` (default) or `json`. - `-h`, `--help` Print this help message. #### REPL Meta-commands diff --git a/website/versioned_docs/version-2.0.x/cli/reference/status.md b/website/versioned_docs/version-2.0.x/cli/reference/status.md index 03c0e5243..05bb19235 100644 --- a/website/versioned_docs/version-2.0.x/cli/reference/status.md +++ b/website/versioned_docs/version-2.0.x/cli/reference/status.md @@ -15,6 +15,7 @@ spice status [flags] #### Flags - `--tls-root-certificate-file` The path to the root certificate file used to verify the Spice.ai runtime server certificate +- `-o`, `--output ` Output format: `table` (default) or `json`. - `-h`, `--help` help for status ### Examples diff --git a/website/versioned_docs/version-2.0.x/cli/reference/trace.md b/website/versioned_docs/version-2.0.x/cli/reference/trace.md index 48b4f366e..c05f40cd5 100644 --- a/website/versioned_docs/version-2.0.x/cli/reference/trace.md +++ b/website/versioned_docs/version-2.0.x/cli/reference/trace.md @@ -42,6 +42,8 @@ These tasks are from the `task` column in the Spice SQL `runtime.task_history` t - `--api-key` Specify the API key for authentication. - `--include-output`: Include, as an additional column, the captured output to each span (i.e. the `captured_output` column from `runtime.task_history`). Note: If captured outputs are not being stored, this will return an empty row. - `--include-input`: Include, as an additional column, the input to each span (i.e. the `input` column from `runtime.task_history`). +- `--truncate []` Truncate the `input` and `captured_output` columns to the given number of characters. Defaults to `80` characters when the flag is passed without a value; when omitted, the columns are not truncated. +- `-o`, `--output ` Output format: `table` (default) or `json`. The latest trace for the task will be used if neither `--trace-id` nor `--id` is specified. diff --git a/website/versioned_docs/version-2.0.x/cli/reference/upgrade.md b/website/versioned_docs/version-2.0.x/cli/reference/upgrade.md index acda429e3..a8ede79f0 100644 --- a/website/versioned_docs/version-2.0.x/cli/reference/upgrade.md +++ b/website/versioned_docs/version-2.0.x/cli/reference/upgrade.md @@ -4,16 +4,19 @@ sidebar_label: "upgrade" pagination_prev: null pagination_next: null --- -Upgrades the Spice CLI & Runtime to the latest release +Upgrades the Spice CLI and runtime to the latest or specified version ### Usage ```shell -spice upgrade [flags] +spice upgrade [target_version] [flags] ``` +`target_version` - an optional release version to install, including the leading `v` (e.g. `v1.8.3`). A version without the leading `v` is rejected. When omitted, the latest release is used. + #### Flags +- `-f`, `--force` Reinstall the CLI and runtime even when the target version is already installed - `-h`, `--help` help for upgrade ### Examples @@ -21,3 +24,17 @@ spice upgrade [flags] ```shell spice upgrade ``` + +### Additional Examples + +Upgrade to a specific version: + +```shell +spice upgrade v1.8.3 +``` + +Reinstall the currently installed version: + +```shell +spice upgrade --force +``` diff --git a/website/versioned_docs/version-2.0.x/cli/reference/version.md b/website/versioned_docs/version-2.0.x/cli/reference/version.md index f58408d57..e59b06485 100644 --- a/website/versioned_docs/version-2.0.x/cli/reference/version.md +++ b/website/versioned_docs/version-2.0.x/cli/reference/version.md @@ -14,6 +14,8 @@ spice version [flags] #### Flags +- `--cli-only` Show only the CLI version, skipping the runtime version lookup +- `-o`, `--output ` Output format: `table` (default) or `json`. - `-h`, `--help` help for version ### Sample output diff --git a/website/versioned_docs/version-2.1.x/cli/reference/catalogs.md b/website/versioned_docs/version-2.1.x/cli/reference/catalogs.md index 994815eee..ae20f4580 100644 --- a/website/versioned_docs/version-2.1.x/cli/reference/catalogs.md +++ b/website/versioned_docs/version-2.1.x/cli/reference/catalogs.md @@ -20,6 +20,7 @@ List [catalogs](../../components/catalogs) currently loaded by the Spice runtime #### Flags - `--tls-root-certificate-file` The path to the root certificate file used to verify the Spice.ai runtime server certificate +- `-o`, `--output ` Output format: `table` (default) or `json`. ### Example diff --git a/website/versioned_docs/version-2.1.x/cli/reference/chat.md b/website/versioned_docs/version-2.1.x/cli/reference/chat.md index 443381a8d..8f6111445 100644 --- a/website/versioned_docs/version-2.1.x/cli/reference/chat.md +++ b/website/versioned_docs/version-2.1.x/cli/reference/chat.md @@ -33,6 +33,7 @@ spice chat [flags] [] - `--temperature ` Model temperature used for chat request. - `--endpoint ` Specifies the remote Spice instance HTTP endpoint (e.g., `http://localhost:8090`). - `--headers ` Custom HTTP headers in format `Key:Value` (can be specified multiple times). +- `--output `, `-o` Output format: `table` (default) or `json`. ## Examples diff --git a/website/versioned_docs/version-2.1.x/cli/reference/datasets.md b/website/versioned_docs/version-2.1.x/cli/reference/datasets.md index c0f155401..5a20b7949 100644 --- a/website/versioned_docs/version-2.1.x/cli/reference/datasets.md +++ b/website/versioned_docs/version-2.1.x/cli/reference/datasets.md @@ -16,6 +16,7 @@ spice datasets [flags] #### Flags - `--tls-root-certificate-file` The path to the root certificate file used to verify the Spice.ai runtime server certificate +- `-o`, `--output ` Output format: `table` (default) or `json`. - `-h`, `--help` help for datasets ### Examples: diff --git a/website/versioned_docs/version-2.1.x/cli/reference/index.md b/website/versioned_docs/version-2.1.x/cli/reference/index.md index 80029d51f..4f8a51730 100644 --- a/website/versioned_docs/version-2.1.x/cli/reference/index.md +++ b/website/versioned_docs/version-2.1.x/cli/reference/index.md @@ -43,13 +43,22 @@ spice [command] [--help] | [spiced](reference/spiced) | Spice runtime binary — direct invocation reference | | [status](reference/status) | Spice runtime status | | [trace](reference/trace) | Return traces for operations that occurred in Spice | -| [upgrade](reference/upgrade) | Upgrades the Spice CLI and runtime to the latest release | +| [upgrade](reference/upgrade) | Upgrades the Spice CLI and runtime to the latest or specified version | | [validate](reference/validate) | Validate a spicepod.yaml without starting the runtime | | [version](reference/version) | Spice CLI version | | workers | Lists workers loaded by the Spice runtime | ### Command Flags -All commands have a help flag **--help** or **-h** to print its usage documentation: +The following flags are global — they are accepted by every command: -- **--help** | **-h** : Print the help message +| 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 ` | 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 ` | Spice.ai Cloud Platform runtime endpoint region, used with `--cloud`. Defaults to `us-east-1`. | +| `--http-endpoint ` | HTTP endpoint of the Spice runtime to talk to. Defaults to `http://127.0.0.1:8090`. | +| `--tls-root-certificate-file ` | Path to a PEM root certificate used to verify the runtime's TLS server certificate. | diff --git a/website/versioned_docs/version-2.1.x/cli/reference/models.md b/website/versioned_docs/version-2.1.x/cli/reference/models.md index 04ee092d5..2cb3a84e8 100644 --- a/website/versioned_docs/version-2.1.x/cli/reference/models.md +++ b/website/versioned_docs/version-2.1.x/cli/reference/models.md @@ -16,6 +16,7 @@ spice models [flags] #### Flags - `--tls-root-certificate-file` The path to the root certificate file used to verify the Spice.ai runtime server certificate +- `-o`, `--output ` Output format: `table` (default) or `json`. - `-h`, `--help` help for models ### Examples diff --git a/website/versioned_docs/version-2.1.x/cli/reference/pods.md b/website/versioned_docs/version-2.1.x/cli/reference/pods.md index 80de82f2f..d6edef4af 100644 --- a/website/versioned_docs/version-2.1.x/cli/reference/pods.md +++ b/website/versioned_docs/version-2.1.x/cli/reference/pods.md @@ -15,6 +15,7 @@ spice pods [flags] #### Flags - `--tls-root-certificate-file` The path to the root certificate file used to verify the Spice.ai runtime server certificate +- `-o`, `--output ` Output format: `table` (default) or `json`. - `-h`, `--help` help for pods ### Examples diff --git a/website/versioned_docs/version-2.1.x/cli/reference/refresh.md b/website/versioned_docs/version-2.1.x/cli/reference/refresh.md index cedad6ec6..7f3643099 100644 --- a/website/versioned_docs/version-2.1.x/cli/reference/refresh.md +++ b/website/versioned_docs/version-2.1.x/cli/reference/refresh.md @@ -20,6 +20,8 @@ spice refresh [dataset] [flags] - `--tls-root-certificate-file` The path to the root certificate file used to verify the Spice.ai runtime server certificate - `--refresh-sql` SQL used to refresh the dataset, see [Refresh SQL docs](../../features/data-acceleration/data-refresh#refresh-sql). - `--refresh-mode` Refresh mode to use, see [Refresh Modes docs](../../features/data-acceleration/data-refresh#refresh-modes). +- `--refresh-jitter-max` Maximum [jitter](../../features/data-acceleration/data-refresh#refresh-jitter) applied to the refresh, as a [duration](../../reference/duration) (e.g. `1m`). +- `-o`, `--output ` Output format: `table` (default) or `json`. - `-h`, `--help` Print this help message ### Examples diff --git a/website/versioned_docs/version-2.1.x/cli/reference/sql.md b/website/versioned_docs/version-2.1.x/cli/reference/sql.md index e7ea95799..04be277f5 100644 --- a/website/versioned_docs/version-2.1.x/cli/reference/sql.md +++ b/website/versioned_docs/version-2.1.x/cli/reference/sql.md @@ -23,6 +23,7 @@ spice sql [flags] - `--client-tls-key-file ` The path to the client private key file for mTLS authentication. Must be used together with `--client-tls-certificate-file`. - `--headers ` Custom HTTP headers in format `Key:Value` (can be specified multiple times). - `-x`, `--expanded` Start the REPL in expanded view, rendering each column on its own line per record. Useful for wide tables. Can be toggled at runtime with the `.expanded` meta-command. +- `-o`, `--output ` Output format: `table` (default) or `json`. - `-h`, `--help` Print this help message. #### REPL Meta-commands diff --git a/website/versioned_docs/version-2.1.x/cli/reference/status.md b/website/versioned_docs/version-2.1.x/cli/reference/status.md index 03c0e5243..05bb19235 100644 --- a/website/versioned_docs/version-2.1.x/cli/reference/status.md +++ b/website/versioned_docs/version-2.1.x/cli/reference/status.md @@ -15,6 +15,7 @@ spice status [flags] #### Flags - `--tls-root-certificate-file` The path to the root certificate file used to verify the Spice.ai runtime server certificate +- `-o`, `--output ` Output format: `table` (default) or `json`. - `-h`, `--help` help for status ### Examples diff --git a/website/versioned_docs/version-2.1.x/cli/reference/trace.md b/website/versioned_docs/version-2.1.x/cli/reference/trace.md index 48b4f366e..4b52d0e69 100644 --- a/website/versioned_docs/version-2.1.x/cli/reference/trace.md +++ b/website/versioned_docs/version-2.1.x/cli/reference/trace.md @@ -33,6 +33,8 @@ spice trace [task] [flags] - `search` - `scheduled_worker` +Tools proxied from MCP servers and custom tools are recorded dynamically as `tool_use::` or `tool_use::/` (for example, `tool_use::github/search_code`). Any such `tool_use::`-prefixed task name can be traced, not just the built-in tools listed above. + These tasks are from the `task` column in the Spice SQL `runtime.task_history` table. #### Flags @@ -42,6 +44,8 @@ These tasks are from the `task` column in the Spice SQL `runtime.task_history` t - `--api-key` Specify the API key for authentication. - `--include-output`: Include, as an additional column, the captured output to each span (i.e. the `captured_output` column from `runtime.task_history`). Note: If captured outputs are not being stored, this will return an empty row. - `--include-input`: Include, as an additional column, the input to each span (i.e. the `input` column from `runtime.task_history`). +- `--truncate []` Truncate the `input` and `captured_output` columns to the given number of characters. Defaults to `80` characters when the flag is passed without a value; when omitted, the columns are not truncated. +- `-o`, `--output ` Output format: `table` (default) or `json`. The latest trace for the task will be used if neither `--trace-id` nor `--id` is specified. diff --git a/website/versioned_docs/version-2.1.x/cli/reference/upgrade.md b/website/versioned_docs/version-2.1.x/cli/reference/upgrade.md index acda429e3..a8ede79f0 100644 --- a/website/versioned_docs/version-2.1.x/cli/reference/upgrade.md +++ b/website/versioned_docs/version-2.1.x/cli/reference/upgrade.md @@ -4,16 +4,19 @@ sidebar_label: "upgrade" pagination_prev: null pagination_next: null --- -Upgrades the Spice CLI & Runtime to the latest release +Upgrades the Spice CLI and runtime to the latest or specified version ### Usage ```shell -spice upgrade [flags] +spice upgrade [target_version] [flags] ``` +`target_version` - an optional release version to install, including the leading `v` (e.g. `v1.8.3`). A version without the leading `v` is rejected. When omitted, the latest release is used. + #### Flags +- `-f`, `--force` Reinstall the CLI and runtime even when the target version is already installed - `-h`, `--help` help for upgrade ### Examples @@ -21,3 +24,17 @@ spice upgrade [flags] ```shell spice upgrade ``` + +### Additional Examples + +Upgrade to a specific version: + +```shell +spice upgrade v1.8.3 +``` + +Reinstall the currently installed version: + +```shell +spice upgrade --force +``` diff --git a/website/versioned_docs/version-2.1.x/cli/reference/version.md b/website/versioned_docs/version-2.1.x/cli/reference/version.md index f58408d57..e59b06485 100644 --- a/website/versioned_docs/version-2.1.x/cli/reference/version.md +++ b/website/versioned_docs/version-2.1.x/cli/reference/version.md @@ -14,6 +14,8 @@ spice version [flags] #### Flags +- `--cli-only` Show only the CLI version, skipping the runtime version lookup +- `-o`, `--output ` Output format: `table` (default) or `json`. - `-h`, `--help` help for version ### Sample output