> ## Documentation Index
> Fetch the complete documentation index at: https://sambanova-systems.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Command reference

Complete reference for every `snctl` command, argument, and flag.

`snctl` manages rack-based infrastructure inventory, power operations, and firmware checks and upgrades.

```text theme={}
snctl [GLOBAL_FLAGS] <command> [subcommand] [FLAGS] [ARGUMENTS]
```

***

## Global flags

Available on every command.

| Flag                    | Description                                                                   |
| ----------------------- | ----------------------------------------------------------------------------- |
| `--snctl-dir <path>`    | Base directory for config and data (default `$HOME/.snctl`). Env: `SNCTL_DIR` |
| `-o, --output <format>` | Output format: `text` (default), `wide`, or `json`                            |
| `--log-level <level>`   | Log level: `debug`, `info`, `warn`, `error`. Env: `SNCTL_LOG_LEVEL`           |
| `-h, --help`            | Help for any command                                                          |

<Note>
  **`-o wide` is not universally supported.** `power on`, `power off`, `power cycle`, `firmware upgrade`, `group create`, `group add-rack`, `group remove-rack`, and `group delete` accept `text` or `json` only. `rack export` uses `-o` differently — see [`rack export`](#rack-export).
</Note>

***

## Command index

| Command                                     | Purpose                                  |
| ------------------------------------------- | ---------------------------------------- |
| [`config init`](#config-init)               | Initialize snctl for first-time use      |
| [`config show`](#config-show)               | Display the current configuration        |
| [`config update`](#config-update)           | Update service account or cache location |
| [`diag doctor`](#diag-doctor)               | Check system dependencies                |
| [`rack add`](#rack-add)                     | Register a new rack                      |
| [`rack add-device`](#rack-add-device)       | Add or update a device in a rack         |
| [`rack delete`](#rack-delete)               | Remove a rack from the inventory         |
| [`rack delete-device`](#rack-delete-device) | Remove a device from a rack              |
| [`rack export`](#rack-export)               | Export racks to JSON or YAML             |
| [`rack import`](#rack-import)               | Import racks and groups from a file      |
| [`rack list`](#rack-list)                   | List all racks                           |
| [`rack show`](#rack-show)                   | Show all devices in a rack               |
| [`node list`](#node-list)                   | List all nodes                           |
| [`node rename`](#node-rename)               | Rename a node                            |
| [`node show`](#node-show)                   | Show all devices in a node               |
| [`group add-rack`](#group-add-rack)         | Add racks to a group                     |
| [`group create`](#group-create)             | Create a group or update its description |
| [`group delete`](#group-delete)             | Delete a group                           |
| [`group list`](#group-list)                 | List all groups                          |
| [`group remove-rack`](#group-remove-rack)   | Remove a rack from a group               |
| [`group show`](#group-show)                 | Show a group and its members             |
| [`secret get`](#secret-get)                 | Retrieve a device credential             |
| [`secret set`](#secret-set)                 | Set or clear a device credential         |
| [`power cycle`](#power-cycle)               | Power-cycle an entire node               |
| [`power off`](#power-off)                   | Power off a node, host, or XRDUs         |
| [`power on`](#power-on)                     | Power on a node, host, or XRDUs          |
| [`power state`](#power-state)               | Query power state                        |
| [`firmware upgrade`](#firmware-upgrade)     | Push a firmware image                    |
| [`firmware version`](#firmware-version)     | Query installed firmware versions        |
| [`version`](#version)                       | Print version and build information      |

***

## Shared values

Values referenced by multiple commands.

### Device types

`access_switch`, `bmc`, `data_switch`, `host`, `pdu`, `serial_terminal`, `xrdu`

`firmware version` additionally accepts `bios`, `card`, and `all`. `firmware upgrade` accepts `bios`, `bmc`, `xrdu`, `card`, and `all` only.

### Device paths

| Device kind             | Path format                              | Example                  |
| ----------------------- | ---------------------------------------- | ------------------------ |
| Rack-level              | `Rack/<rack_id>/<type>/<index>`          | `Rack/001/pdu/1`         |
| Node-level, slotted     | `Rack/<rack_id>/Node/<n>/<type>/<index>` | `Rack/001/Node/0/xrdu/1` |
| Node-level, non-slotted | `Rack/<rack_id>/Node/<n>/<type>`         | `Rack/001/Node/0/bmc`    |

PDUs are 1-indexed; XRDUs are 0-indexed (`0`–`7`). `host` and `bmc` take no index.

### Concurrency flags

Accepted by all `power` and `firmware` subcommands.

| Flag                          | Description                                                  | Default                                                                                                               |
| ----------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `-p, --parallelism-racks <n>` | Max racks in-flight simultaneously (`0` = uncapped)          | `4` for `power on`; `1` for `power off`, `power cycle`, `firmware upgrade`; `0` for `power state`, `firmware version` |
| `--parallelism-devices <n>`   | Global max nodes in-flight across all racks (`0` = uncapped) | `0`                                                                                                                   |

### Environment variables

| Variable                | Effect                                                       |
| ----------------------- | ------------------------------------------------------------ |
| `SNCTL_DIR`             | Base directory for config and data                           |
| `SNCTL_LOG_LEVEL`       | Default log level                                            |
| `SNCTL_NON_INTERACTIVE` | Set to `1` to suppress confirmation prompts (`group delete`) |

***

# config

Manage snctl configuration.

## config init

Initialize snctl with an encryption key, empty inventory, and configuration.

```text theme={}
snctl config init [flags]
```

Creates an AES-GCM encryption key, empty rack inventory, encrypted secrets file, logs directory, and `config.yaml`. Run once before registering racks or setting credentials.

<Note>
  Re-running against an already-initialized directory returns an error. Use [`config show`](#config-show) to inspect an existing configuration.
</Note>

| Flag                       | Description                                                                  |
| -------------------------- | ---------------------------------------------------------------------------- |
| `--config-dir <path>`      | Directory for `config.yaml`, inventory, and secrets (default `$HOME/.snctl`) |
| `--logs-dir <path>`        | Directory for log files (default `$XDG_STATE_HOME/snctl/logs`)               |
| `--cache-dir <path>`       | Directory for downloaded firmware (default `$XDG_CACHE_HOME/snctl/firmware`) |
| `--service-account <path>` | Path to a GCS service account JSON file                                      |
| `-y, --defaults`           | Accept all defaults without prompting                                        |

```bash theme={}
# Interactive first-time setup
snctl config init

# Unattended, accepting every default
snctl config init --defaults

# Unattended with explicit paths
snctl config init --defaults --config-dir ~/.snctl_idc --logs-dir /var/log/snctl
```

## config show

Display the current snctl configuration.

```text theme={}
snctl config show [flags]
```

Shows paths to `config.yaml`, the inventory file, encryption key, and secrets file, plus optional settings such as the GCS service account and logs directory. If snctl has not been initialized, prints a notice and exits cleanly.

No command-specific flags.

```bash theme={}
snctl config show
snctl config show -o json
```

## config update

Update fields of an existing snctl configuration.

```text theme={}
snctl config update [flags]
```

Requires an initialized configuration. Pass an empty string to clear a value.

| Flag                       | Description                                                                                                     |
| -------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `--service-account <path>` | Absolute path to a Google service-account JSON file, used to download firmware from GCS (empty string to clear) |
| `--cache-location <path>`  | Absolute path to the firmware download cache directory (empty string to reset to the XDG default)               |

```bash theme={}
snctl config update --service-account /etc/snctl/sambanova-sa.json
snctl config update --service-account ""
snctl config update --cache-location /data/snctl-cache
snctl config update --cache-location ""
```

***

# diag

Diagnose snctl installation and environment health.

## diag doctor

Check system dependencies and environment health.

```text theme={}
snctl diag doctor [flags]
```

Verifies that all system dependencies required by snctl are installed — including tools such as `ipmitool` needed for power and firmware operations — and reports their status. Run this if commands fail unexpectedly.

No command-specific flags.

```bash theme={}
snctl diag doctor
snctl diag doctor -o json
```

***

# rack

Manage rack inventory.

## rack add

Add a new rack to the inventory.

```text theme={}
snctl rack add <rack_id> [flags]
```

`--partnumber` identifies the hardware model, which determines the component layout automatically populated for the rack.

| Flag                   | Description                          |
| ---------------------- | ------------------------------------ |
| `--partnumber <value>` | **Required.** `1001934` or `1002331` |

```bash theme={}
snctl rack add 001 --partnumber 1002331
```

## rack add-device

Add or update a device in a rack.

```text theme={}
snctl rack add-device <target> [flags]
```

`<target>` is a [device path](#device-paths). Omitting a field preserves its current value (partial update).

| Flag                   | Description                                     |
| ---------------------- | ----------------------------------------------- |
| `--ip <address>`       | Device IP address                               |
| `--hostname <name>`    | Device hostname                                 |
| `--user <username>`    | Login username                                  |
| `--port <n>`           | Connection port                                 |
| `--device-type <type>` | Device type — see [Device types](#device-types) |
| `--index <n>`          | Device index, overrides the path (default `-1`) |

```bash theme={}
# Configure BMC IP and username for node 0 in rack 001
snctl rack add-device Rack/001/Node/0/bmc --ip 192.168.1.10 --user admin

# Configure the host connection
snctl rack add-device Rack/001/Node/0/host --ip 192.168.1.11 --user snadmin

# Update only the IP of an already-configured BMC
snctl rack add-device Rack/001/Node/0/bmc --ip 192.168.1.50
```

## rack delete

Remove a rack from the inventory.

```text theme={}
snctl rack delete <rack_id> [flags]
```

Removes the rack and all its associated SN40L nodes.

<Warning>
  Affects the local inventory only — it does not power off or modify the physical hardware. Re-register with `snctl rack add <rack_id> --partnumber <part>` if removed in error.
</Warning>

No command-specific flags.

```bash theme={}
snctl rack delete 001
```

## rack delete-device

Remove a device from a rack.

```text theme={}
snctl rack delete-device <rack_id|node_name> [flags]
```

Removes the component from the local inventory only; the physical hardware is not affected.

| Flag                   | Description                                                |
| ---------------------- | ---------------------------------------------------------- |
| `--device-type <type>` | Device type to remove — see [Device types](#device-types)  |
| `--index <n>`          | Device index. **Required for PDU and XRDU** (default `-1`) |

```bash theme={}
snctl rack delete-device 001 --device-type bmc
snctl rack delete-device 001 --device-type pdu --index 1
snctl rack delete-device 001 --device-type xrdu --index 0
snctl rack delete-device node-001 --device-type bmc
```

## rack export

Export racks to a JSON or YAML file.

```text theme={}
snctl rack export [rack_id...] [flags]
```

With no rack IDs, all racks are exported.

<Note>
  Passwords are always replaced with placeholder values, so the export file is safe to share.
</Note>

| Flag                    | Description                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------ |
| `--file <path>`         | Output file path (default: stdout)                                                   |
| `-o, --output <format>` | `json` or `yaml`. Inferred from the `--file` extension; defaults to `json` on stdout |

```bash theme={}
snctl rack export
snctl rack export 001 002 --file racks.yaml
snctl rack export --output yaml
snctl rack export 001 --file rack-001.json
```

## rack import

Import racks and groups from a JSON or YAML file.

```text theme={}
snctl rack import <file> [flags]
```

The file is a native snctl inventory and may contain a subset of racks, groups, or both. Use `-` to read from stdin.

| Flag          | Description                                                                              |
| ------------- | ---------------------------------------------------------------------------------------- |
| `--dry-run`   | Preview changes without modifying the inventory                                          |
| `--overwrite` | Replace existing racks and groups. Without it, existing entries are skipped and reported |

**Credential handling.** Any device password in the source file that is not already a placeholder is imported into the encrypted credential store as a per-device credential; the inventory itself only stores the placeholder. For each device kind with no existing default credential, the lowest-numbered rack's password for that kind also becomes the kind's default. Secrets are never printed. `--dry-run` reports how many secrets would be imported without writing anything.

```bash theme={}
snctl rack import racks.json --dry-run
snctl rack import racks.json
snctl rack import racks.json --overwrite
cat racks.yaml | snctl rack import -
```

## rack list

List all racks in the inventory.

```text theme={}
snctl rack list [flags]
```

Shows each rack's ID, hardware type, and component counts. No command-specific flags.

```bash theme={}
snctl rack list
snctl rack list -o wide     # adds human-readable hardware type
snctl rack list -o json
```

## rack show

Show all devices in a rack.

```text theme={}
snctl rack show <rack_id> [flags]
```

Displays every component with its hostname, IP address, port, and username. Use this to verify network addressing before running power or firmware commands. No command-specific flags.

```bash theme={}
snctl rack show 001
snctl rack show 001 -o wide     # adds node names
snctl rack show 001 -o json     # always includes node_name
```

***

# node

Manage nodes in the inventory.

## node list

List all nodes in the inventory.

```text theme={}
snctl node list [flags]
```

Shows each node's name, parent rack ID, rack hardware type, and slot index. No command-specific flags.

```bash theme={}
snctl node list
snctl node list -o wide
snctl node list -o json
```

## node rename

Rename a node.

```text theme={}
snctl node rename <node_name> <new_name> [flags]
```

The new name must be unique across all nodes.

<Note>
  Local inventory operation only — it does not change any hostname on the hardware itself.
</Note>

No command-specific flags.

```bash theme={}
snctl node rename node-001 rack-01-node-a
```

## node show

Show all devices in a node.

```text theme={}
snctl node show <node_name> [flags]
```

Displays all component sub-devices (BMC, host, XRDUs) with hostname, IP address, port, and username. No command-specific flags.

```bash theme={}
snctl node show node-001
snctl node show node-001 -o wide
snctl node show node-001 -o json
```

***

# group

Manage rack groups. Groups fan out firmware and power commands across multiple racks in a single operation.

## group create

Create a group or update its description.

```text theme={}
snctl group create <group_name> [flags]
```

If a group with that name already exists, its description is updated.

| Flag                       | Description                     |
| -------------------------- | ------------------------------- |
| `-d, --description <text>` | **Required.** Group description |

```bash theme={}
snctl group create production-racks --description "Production cluster, building A"
snctl group create production-racks --description "Production cluster, buildings A and B"
```

## group add-rack

Add one or more racks to a group.

```text theme={}
snctl group add-rack <group_name> [flags]
```

The group must already exist. Racks already in the group emit a warning and are skipped without error.

| Flag                  | Description                                      |
| --------------------- | ------------------------------------------------ |
| `-r, --rack-id <ids>` | **Required.** Rack ID(s) to add, comma-separated |

```bash theme={}
snctl group add-rack production-racks --rack-id 001
snctl group add-rack production-racks --rack-id 001,002,003
```

## group remove-rack

Remove a rack from a group.

```text theme={}
snctl group remove-rack <group_name> [flags]
```

The rack remains registered in the inventory and can be added to other groups; only its membership in this group is removed.

| Flag             | Description                     |
| ---------------- | ------------------------------- |
| `--rack-id <id>` | **Required.** Rack ID to remove |

```bash theme={}
snctl group remove-rack production-racks --rack-id 003
```

## group list

List all groups in the inventory.

```text theme={}
snctl group list [flags]
```

Shows each group's name, description, and number of member racks. No command-specific flags.

```bash theme={}
snctl group list
snctl group list -o wide     # includes member rack IDs
snctl group list -o json
```

## group show

Show a group and its member racks.

```text theme={}
snctl group show <group_name> [flags]
```

Displays the group's description and its member racks with their hardware types. No command-specific flags.

```bash theme={}
snctl group show production-racks
snctl group show production-racks -o wide
snctl group show production-racks -o json
```

## group delete

Delete a group from the inventory.

```text theme={}
snctl group delete <group_name> [flags]
```

Prompts for confirmation before deleting.

<Note>
  Member racks are **not** removed — only the group record is deleted. Set `SNCTL_NON_INTERACTIVE=1` to suppress the prompt in scripts.
</Note>

No command-specific flags.

```bash theme={}
snctl group delete staging-racks
SNCTL_NON_INTERACTIVE=1 snctl group delete staging-racks
```

***

# secret

Manage device secrets. Credentials are stored AES-GCM encrypted in `~/.snctl/credentials.json.enc`.

## secret set

Set or clear a device secret.

```text theme={}
snctl secret set [flags]
```

You are prompted to enter and confirm the value interactively; nothing is echoed to the terminal. Set credentials for all component types used in your deployment before running power or firmware commands.

| Flag                   | Description                                                              |
| ---------------------- | ------------------------------------------------------------------------ |
| `--device-type <type>` | Set the default for a component kind — see [Device types](#device-types) |
| `--device <path>`      | Canonical [device path](#device-paths) for a per-device override         |
| `--clear`              | Remove the credential instead of setting one (no prompt)                 |

Per-device credentials take precedence over the kind-level default. Clearing a credential that isn't set succeeds without error; after clearing a per-device override, the device falls back to the kind-level credential.

```bash theme={}
# Kind-level defaults
snctl secret set --device-type bmc
snctl secret set --device-type host
snctl secret set --device-type xrdu

# Per-device override
snctl secret set --device Rack/001/Node/0/bmc

# Clearing
snctl secret set --device-type bmc --clear
snctl secret set --device Rack/001/Node/0/bmc --clear
```

## secret get

Get a device secret.

```text theme={}
snctl secret get [flags]
```

The value is masked as `***` by default.

| Flag                   | Description                                                                                                                                 |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `--device-type <type>` | Device kind to query — see [Device types](#device-types)                                                                                    |
| `--device <path>`      | Canonical [device path](#device-paths) — resolves override, then kind default, then legacy secret, and names which tier the value came from |
| `--show-value`         | Reveal the plaintext password                                                                                                               |

<Warning>
  Only use `--show-value` in a secure environment. Never share the output.
</Warning>

```bash theme={}
snctl secret get --device-type bmc
snctl secret get --device-type bmc --show-value
snctl secret get --device Rack/001/Node/0/bmc
snctl secret get --device-type bmc -o json
```

***

# power

Power on, off, cycle, and query nodes. Operations run over IPMI or Redfish.

<Note>
  All power commands require `--node` **or** `--group` (mutually exclusive), and device credentials must be configured with [`secret set`](#secret-set) first.
</Note>

## power state

Query the power state of a node, host, or XRDU(s).

```text theme={}
snctl power state [flags]
```

Reports the current DC power state (on/off/unknown). Read-only and safe to run at any time.

| Flag                          | Description                                                               | Default        |
| ----------------------------- | ------------------------------------------------------------------------- | -------------- |
| `--node <name\|rack_id>`      | Node name or rack ID                                                      |                |
| `--group <name>`              | Target all nodes in a named group                                         |                |
| `--type <kind>`               | `node`, `host`, or `xrdu`                                                 | `node`         |
| `--protocol <proto>`          | Override default protocol: `ipmi`, `ssh`, `redfish` (component-dependent) |                |
| `-p, --parallelism-racks <n>` | Max racks in-flight                                                       | `0` (uncapped) |
| `--parallelism-devices <n>`   | Global max nodes in-flight                                                | `0` (uncapped) |

```bash theme={}
snctl power state --node node-001
snctl power state --node node-001 --type host
snctl power state --node node-001 --type xrdu
snctl power state --group production-racks -o json
snctl power state --node node-001 -o wide     # shows which protocol served each component
```

## power on

Turn on a node, host, or XRDU(s).

```text theme={}
snctl power on [flags]
```

After power-on, snctl waits for `snd.service` (SambaNova Daemon) to become active before returning.

| Flag                          | Description                               | Default        |
| ----------------------------- | ----------------------------------------- | -------------- |
| `--node <name\|rack_id>`      | Node name or rack ID                      |                |
| `--group <name>`              | Target all nodes in a named group         |                |
| `--type <kind>`               | `node`, `host`, or `xrdu`                 | `node`         |
| `--skip-snd-check`            | Skip waiting for `snd.service` after boot |                |
| `--protocol <proto>`          | Override default protocol                 |                |
| `-p, --parallelism-racks <n>` | Max racks in-flight                       | `4`            |
| `--parallelism-devices <n>`   | Global max nodes in-flight                | `0` (uncapped) |

```bash theme={}
snctl power on --node node-001
snctl power on --node node-001 --type host      # leaves XRDUs unpowered
snctl power on --group production-racks
snctl power on --node node-001 --skip-snd-check
```

## power off

Turn off a node, host, or XRDU(s).

```text theme={}
snctl power off [flags]
```

| Flag                          | Description                       | Default        |
| ----------------------------- | --------------------------------- | -------------- |
| `--node <name\|rack_id>`      | Node name or rack ID              |                |
| `--group <name>`              | Target all nodes in a named group |                |
| `--type <kind>`               | `node`, `host`, or `xrdu`         | `node`         |
| `--protocol <proto>`          | Override default protocol         |                |
| `-p, --parallelism-racks <n>` | Max racks in-flight               | `1`            |
| `--parallelism-devices <n>`   | Global max nodes in-flight        | `0` (uncapped) |

```bash theme={}
snctl power off --node node-001
snctl power off --node node-001 --type host     # XRDUs remain powered
snctl power off --group production-racks --parallelism-racks 2
```

## power cycle

Power-cycle the entire node.

```text theme={}
snctl power cycle [flags]
```

Graceful off, then on. **Always targets the whole node — there is no `--type` flag.** Waits for `snd.service` before returning.

| Flag                          | Description                               | Default        |
| ----------------------------- | ----------------------------------------- | -------------- |
| `--node <name\|rack_id>`      | Node name or rack ID                      |                |
| `--group <name>`              | Target all nodes in a named group         |                |
| `--skip-snd-check`            | Skip waiting for `snd.service` after boot |                |
| `--protocol <proto>`          | Override default protocol                 |                |
| `-p, --parallelism-racks <n>` | Max racks in-flight                       | `1`            |
| `--parallelism-devices <n>`   | Global max nodes in-flight                | `0` (uncapped) |

```bash theme={}
snctl power cycle --node node-001
snctl power cycle --group production-racks
snctl power cycle --node node-001 --skip-snd-check
```

***

# firmware

Query and update node firmware.

<Note>
  Both commands require `--rack-id` **or** `--group` (mutually exclusive), and device credentials must be configured with [`secret set`](#secret-set) first.
</Note>

## firmware version

Query installed firmware versions on a rack's components.

```text theme={}
snctl firmware version [flags]
```

Results show the current installed version (`CURR`) alongside the plan-of-record version (`POR`) so you can identify drift at a glance.

| Flag                          | Description                                                                                    | Default        |
| ----------------------------- | ---------------------------------------------------------------------------------------------- | -------------- |
| `-r, --rack-id <id>`          | Rack ID to query                                                                               |                |
| `--group <name>`              | Target all racks in a named group                                                              |                |
| `--device-type <type>`        | `all`, `bios`, `bmc`, `xrdu`, `card`, `pdu`, `serial_terminal`, `access_switch`, `data_switch` | `all`          |
| `--index <indices>`           | Comma-separated slot indices for slotted device types (e.g. `0,2,5`)                           |                |
| `--protocol <proto>`          | Override default protocol: `ssh`, `rest`, `redfish` (endpoint-dependent)                       |                |
| `-p, --parallelism-racks <n>` | Max racks in-flight                                                                            | `0` (uncapped) |
| `--parallelism-devices <n>`   | Global max nodes in-flight                                                                     | `0` (uncapped) |

```bash theme={}
snctl firmware version --rack-id 001
snctl firmware version --rack-id 001 --device-type bmc
snctl firmware version --rack-id 001 --device-type xrdu --index 0,2
snctl firmware version --group production-racks
snctl firmware version --rack-id 001 -o json
snctl firmware version --rack-id 001 -o wide     # adds Protocol, Model, Source
```

## firmware upgrade

Push a firmware image to a rack's components.

```text theme={}
snctl firmware upgrade [flags]
```

| Flag                          | Description                                                                                     | Default        |
| ----------------------------- | ----------------------------------------------------------------------------------------------- | -------------- |
| `-r, --rack-id <id>`          | Rack ID to target                                                                               |                |
| `--group <name>`              | Target all racks in a named group                                                               |                |
| `--device-type <type>`        | **Required.** `all`, `bios`, `bmc`, `xrdu`, or `card`                                           |                |
| `--image <path>`              | Local firmware image path. Repeatable — see below                                               |                |
| `--index <indices>`           | Comma-separated slot indices for `xrdu` and `card` (e.g. `0,2`). Omit to upgrade every instance |                |
| `--protocol <proto>`          | Override default protocol (endpoint-dependent)                                                  |                |
| `-p, --parallelism-racks <n>` | Max racks in-flight                                                                             | `1`            |
| `--parallelism-devices <n>`   | Global max nodes in-flight                                                                      | `0` (uncapped) |

**`--image` behaviour.** If omitted, the correct file for each component's POR version is downloaded automatically from GCS, checksum-verified, and cached. Pass `--image` to flash specific local files instead — required for airgapped environments.

| Device type           | `--image` format                                                                                      |
| --------------------- | ----------------------------------------------------------------------------------------------------- |
| `bios`, `bmc`, `card` | A bare path: `--image /path/to/file`                                                                  |
| `xrdu`                | Passed twice with component prefixes: `--image obmc=/path/to/obmc.tgz --image rduc=/path/to/rduc.tgz` |

**`--index` restrictions.** Accepted for `xrdu` and `card` only. Rejected for `bios`, `bmc`, and `all` — BIOS and BMC are node-level components with no slots, and `all` mixes both kinds, where an index would narrow only part of the upgrade.

```bash theme={}
# Auto-download the POR image
snctl firmware upgrade --rack-id 001 --device-type bios

# Manually downloaded image
snctl firmware upgrade --rack-id 001 --device-type bmc --image /opt/firmware/bmc-1.08.bin

# XRDU: both components required
snctl firmware upgrade --rack-id 001 --device-type xrdu \
  --image obmc=/opt/firmware/obmc-5.1.4.tgz --image rduc=/opt/firmware/rduc-5.1.4.tgz

# Only XRDU slots 0 and 2
snctl firmware upgrade --rack-id 001 --device-type xrdu --index 0,2

# Across a group, 2 racks in parallel
snctl firmware upgrade --group production-racks --device-type bmc --parallelism-racks 2

# Thor Card (NIC)
snctl firmware upgrade --rack-id 001 --device-type card
```

***

# version

Print version and build information.

```text theme={}
snctl version [flags]
```

Prints the release version, git commit hash, build timestamp, Go runtime version, and OS/architecture. Use `-o json` when filing a support request.

No command-specific flags.

```bash theme={}
snctl version
snctl version -o json
```