Complete reference for every snctl command, argument, and flag. snctl manages rack-based infrastructure inventory, power operations, and firmware checks and upgrades.

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

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

Command index

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

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.

Re-running against an already-initialized directory returns an error. Use config show to inspect an existing configuration.

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

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

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.

snctl config show
snctl config show -o json

config update

Update fields of an existing snctl configuration.

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)

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.

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.

snctl diag doctor
snctl diag doctor -o json

rack

Manage rack inventory.

rack add

Add a new rack to the inventory.

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`

snctl rack add 001 --partnumber 1002331

rack add-device

Add or update a device in a rack.

snctl rack add-device <target> [flags]

<target> is a device path. 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
`--index <n>`	Device index, overrides the path (default `-1`)

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

snctl rack delete <rack_id> [flags]

Removes the rack and all its associated SN40L nodes.

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.

No command-specific flags.

snctl rack delete 001

rack delete-device

Remove a device from a rack.

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
`--index <n>`	Device index. Required for PDU and XRDU (default `-1`)

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.

snctl rack export [rack_id...] [flags]

With no rack IDs, all racks are exported.

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

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

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.

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.

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.

snctl rack list [flags]

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

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.

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.

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.

snctl node list [flags]

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

snctl node list
snctl node list -o wide
snctl node list -o json

node rename

Rename a node.

snctl node rename <node_name> <new_name> [flags]

The new name must be unique across all nodes.

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

No command-specific flags.

snctl node rename node-001 rack-01-node-a

node show

Show all devices in a node.

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.

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.

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

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.

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

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.

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

snctl group remove-rack production-racks --rack-id 003

group list

List all groups in the inventory.

snctl group list [flags]

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

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.

snctl group show <group_name> [flags]

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

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.

snctl group delete <group_name> [flags]

Prompts for confirmation before deleting.

Member racks are not removed — only the group record is deleted. Set SNCTL_NON_INTERACTIVE=1 to suppress the prompt in scripts.

No command-specific flags.

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.

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 <path>`	Canonical device path 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.

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

snctl secret get [flags]

The value is masked as *** by default.

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

Only use --show-value in a secure environment. Never share the output.

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.

All power commands require --node or --group (mutually exclusive), and device credentials must be configured with secret set first.

power state

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

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)

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

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)

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

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)

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.

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)

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.

Both commands require --rack-id or --group (mutually exclusive), and device credentials must be configured with secret set first.

firmware version

Query installed firmware versions on a rack’s components.

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)

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.

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.

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

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.

snctl version
snctl version -o json

​Global flags

​Command index

​Shared values

​Device types

​Device paths

​Concurrency flags

​Environment variables

​config

​config init

​config show

​config update

​diag

​diag doctor

​rack

​rack add

​rack add-device

​rack delete

​rack delete-device

​rack export

​rack import

​rack list

​rack show

​node

​node list

​node rename

​node show

​group

​group create

​group add-rack

​group remove-rack

​group list

​group show

​group delete

​secret

​secret set

​secret get

​power

​power state

​power on

​power off

​power cycle

​firmware

​firmware version

​firmware upgrade

​version

Global flags

Command index

Shared values

Device types

Device paths

Concurrency flags

Environment variables

config

config init

config show

config update

diag

diag doctor

rack

rack add

rack add-device

rack delete

rack delete-device

rack export

rack import

rack list

rack show

node

node list

node rename

node show

group

group create

group add-rack

group remove-rack

group list

group show

group delete

secret

secret set

secret get

power

power state

power on

power off

power cycle

firmware

firmware version

firmware upgrade

version