docs(cli): complete the deferred versioned pass for the CLI reference (2.0.x, 2.1.x)

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 <format>` Output format: `table` (default) or `json`.
 
 ### Example
 

website/versioned_docs/version-2.0.x/cli/reference/chat.md

@@ -33,6 +33,7 @@ spice chat [flags] [<message>]
 - `--temperature <float>` Model temperature used for chat request.
 - `--endpoint <endpoint>` Specifies the remote Spice instance HTTP endpoint (e.g., `http://localhost:8090`).
 - `--headers <KEY:VALUE>` Custom HTTP headers in format `Key:Value` (can be specified multiple times).
+- `--output <format>`, `-o` Output format: `table` (default) or `json`.
 
 ## Examples
 

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 <format>` Output format: `table` (default) or `json`.
 - `-h`, `--help`   help for datasets
 
 ### Examples:

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 <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.                                              |

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 <format>` Output format: `table` (default) or `json`.
 - `-h`, `--help`   help for models
 
 ### Examples

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 <format>` Output format: `table` (default) or `json`.
 - `-h`, `--help`   help for pods
 
 ### Examples

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 <format>` Output format: `table` (default) or `json`.
 - `-h`, `--help`   Print this help message
 
 ### Examples

website/versioned_docs/version-2.0.x/cli/reference/sql.md

@@ -23,6 +23,7 @@ spice sql [flags]
 - `--client-tls-key-file <file>` The path to the client private key file for mTLS authentication. Must be used together with `--client-tls-certificate-file`.
 - `--headers <KEY:VALUE>` 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 <format>` Output format: `table` (default) or `json`.
 - `-h`, `--help` Print this help message.
 
 #### REPL Meta-commands

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 <format>` Output format: `table` (default) or `json`.
 - `-h`, `--help`   help for status
 
 ### Examples

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 [<length>]`  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 <format>` Output format: `table` (default) or `json`.
 
 The latest trace for the task will be used if neither `--trace-id` nor `--id` is specified.
 

website/versioned_docs/version-2.0.x/cli/reference/upgrade.md

@@ -4,20 +4,37 @@ 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
 
 ```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
+```

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 <format>` Output format: `table` (default) or `json`.
 - `-h`, `--help`   help for version
 
 ### Sample output

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 <format>` Output format: `table` (default) or `json`.
 
 ### Example
 

website/versioned_docs/version-2.1.x/cli/reference/chat.md

@@ -33,6 +33,7 @@ spice chat [flags] [<message>]
 - `--temperature <float>` Model temperature used for chat request.
 - `--endpoint <endpoint>` Specifies the remote Spice instance HTTP endpoint (e.g., `http://localhost:8090`).
 - `--headers <KEY:VALUE>` Custom HTTP headers in format `Key:Value` (can be specified multiple times).
+- `--output <format>`, `-o` Output format: `table` (default) or `json`.
 
 ## Examples
 

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 <format>` Output format: `table` (default) or `json`.
 - `-h`, `--help`   help for datasets
 
 ### Examples:

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 <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.                                              |

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 <format>` Output format: `table` (default) or `json`.
 - `-h`, `--help`   help for models
 
 ### Examples

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 <format>` Output format: `table` (default) or `json`.
 - `-h`, `--help`   help for pods
 
 ### Examples

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 <format>` Output format: `table` (default) or `json`.
 - `-h`, `--help`   Print this help message
 
 ### Examples

website/versioned_docs/version-2.1.x/cli/reference/sql.md

@@ -23,6 +23,7 @@ spice sql [flags]
 - `--client-tls-key-file <file>` The path to the client private key file for mTLS authentication. Must be used together with `--client-tls-certificate-file`.
 - `--headers <KEY:VALUE>` 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 <format>` Output format: `table` (default) or `json`.
 - `-h`, `--help` Print this help message.
 
 #### REPL Meta-commands

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 <format>` Output format: `table` (default) or `json`.
 - `-h`, `--help`   help for status
 
 ### Examples

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::<tool>` or `tool_use::<server>/<tool>` (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 [<length>]`  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 <format>` Output format: `table` (default) or `json`.
 
 The latest trace for the task will be used if neither `--trace-id` nor `--id` is specified.
 

website/versioned_docs/version-2.1.x/cli/reference/upgrade.md

@@ -4,20 +4,37 @@ 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
 
 ```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
+```

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 <format>` Output format: `table` (default) or `json`.
 - `-h`, `--help`   help for version
 
 ### Sample output