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

# コマンドリファレンス

すべての `snctl` コマンド、引数、フラグの完全なリファレンスです。

`snctl` は、ラックベースのインフラストラクチャインベントリ、電源操作、およびファームウェアの確認とアップグレードを管理します。

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

***

## グローバルフラグ

すべてのコマンドで使用できます。

| フラグ | 説明 |
| - | - |
| `--snctl-dir <path>` | 設定とデータのベースディレクトリ (デフォルト `$HOME/.snctl`)。環境変数: `SNCTL_DIR` |
| `-o, --output <format>` | 出力形式: `text` (デフォルト)、`wide`、または `json` |
| `--log-level <level>` | ログレベル: `debug`、`info`、`warn`、`error`。環境変数: `SNCTL_LOG_LEVEL` |
| `-h, --help` | 任意のコマンドのヘルプを表示 |

<Note>
  **`-o wide` はすべてのコマンドでサポートされているわけではありません。**`power on`、`power off`、`power cycle`、`firmware upgrade`、`group create`、`group add-rack`、`group remove-rack`、`group delete` は `text` または `json` のみを受け付けます。`rack export` では `-o` の用法が異なります — [`rack export`](#rack-export) をご参照ください。
</Note>

***

## コマンド索引

| コマンド | 用途 |
| - | - |
| [`config init`](#config-init) | 初回使用のための snctl の初期化 |
| [`config show`](#config-show) | 現在の設定の表示 |
| [`config update`](#config-update) | サービスアカウントまたはキャッシュ場所の更新 |
| [`diag doctor`](#diag-doctor) | システム依存関係の確認 |
| [`rack add`](#rack-add) | 新しいラックの登録 |
| [`rack add-device`](#rack-add-device) | ラック内デバイスの追加・更新 |
| [`rack delete`](#rack-delete) | インベントリからのラックの削除 |
| [`rack delete-device`](#rack-delete-device) | ラックからのデバイスの削除 |
| [`rack export`](#rack-export) | ラックの JSON または YAML へのエクスポート |
| [`rack import`](#rack-import) | ファイルからのラックとグループのインポート |
| [`rack list`](#rack-list) | 全ラックの一覧表示 |
| [`rack show`](#rack-show) | ラック内の全デバイスの表示 |
| [`node list`](#node-list) | 全ノードの一覧表示 |
| [`node rename`](#node-rename) | ノード名の変更 |
| [`node show`](#node-show) | ノード内の全デバイスの表示 |
| [`group add-rack`](#group-add-rack) | グループへのラックの追加 |
| [`group create`](#group-create) | グループの作成または説明の更新 |
| [`group delete`](#group-delete) | グループの削除 |
| [`group list`](#group-list) | 全グループの一覧表示 |
| [`group remove-rack`](#group-remove-rack) | グループからのラックの削除 |
| [`group show`](#group-show) | グループとその所属ラックの表示 |
| [`secret get`](#secret-get) | デバイス認証情報の取得 |
| [`secret set`](#secret-set) | デバイス認証情報の設定・削除 |
| [`power cycle`](#power-cycle) | ノード全体のパワーサイクル |
| [`power off`](#power-off) | ノード・ホスト・XRDU の電源オフ |
| [`power on`](#power-on) | ノード・ホスト・XRDU の電源オン |
| [`power state`](#power-state) | 電源状態の照会 |
| [`firmware upgrade`](#firmware-upgrade) | ファームウェアイメージの適用 |
| [`firmware version`](#firmware-version) | インストール済みファームウェアバージョンの照会 |
| [`version`](#version) | バージョンとビルド情報の表示 |

***

## 共通の値

複数のコマンドから参照される値です。

### デバイスタイプ

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

`firmware version` はこれらに加えて `bios`、`card`、`all` を受け付けます。`firmware upgrade` は `bios`、`bmc`、`xrdu`、`card`、`all` のみを受け付けます。

### デバイスパス

| デバイスの種類 | パス形式 | 例 |
| - | - | - |
| ラックレベル | `Rack/<rack_id>/<type>/<index>` | `Rack/001/pdu/1` |
| ノードレベル (スロット型) | `Rack/<rack_id>/Node/<n>/<type>/<index>` | `Rack/001/Node/0/xrdu/1` |
| ノードレベル (非スロット型) | `Rack/<rack_id>/Node/<n>/<type>` | `Rack/001/Node/0/bmc` |

PDU は 1 始まり、XRDU は 0 始まり (`0`〜`7`) です。`host` と `bmc` はインデックスを取りません。

### 同時実行フラグ

すべての `power` および `firmware` サブコマンドで使用できます。

| フラグ | 説明 | デフォルト |
| - | - | - |
| `-p, --parallelism-racks <n>` | 同時に処理するラック数の上限 (`0` = 上限なし) | `power on` は `4`、`power off`・`power cycle`・`firmware upgrade` は `1`、`power state`・`firmware version` は `0` |
| `--parallelism-devices <n>` | 全ラック合計で同時処理するノード数のグローバル上限 (`0` = 上限なし) | `0` |

### 環境変数

| 変数 | 効果 |
| - | - |
| `SNCTL_DIR` | 設定とデータのベースディレクトリ |
| `SNCTL_LOG_LEVEL` | デフォルトのログレベル |
| `SNCTL_NON_INTERACTIVE` | `1` に設定すると確認プロンプトを抑制する (`group delete`) |

***

# config

snctl の設定を管理します。

## config init

暗号鍵、空のインベントリ、設定を作成して snctl を初期化します。

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

AES-GCM 暗号鍵、空のラックインベントリ、暗号化されたシークレットファイル、ログディレクトリ、および `config.yaml` を作成します。ラックの登録や認証情報の設定を行う前に、一度だけ実行してください。

<Note>
  初期化済みのディレクトリに対して再実行するとエラーになります。既存の設定を確認するには [`config show`](#config-show) を使用してください。
</Note>

| フラグ | 説明 |
| - | - |
| `--config-dir <path>` | `config.yaml`、インベントリ、シークレットのディレクトリ (デフォルト `$HOME/.snctl`) |
| `--logs-dir <path>` | ログファイルのディレクトリ (デフォルト `$XDG_STATE_HOME/snctl/logs`) |
| `--cache-dir <path>` | ダウンロードしたファームウェアのディレクトリ (デフォルト `$XDG_CACHE_HOME/snctl/firmware`) |
| `--service-account <path>` | GCS サービスアカウントの JSON ファイルへのパス |
| `-y, --defaults` | プロンプトなしですべてのデフォルトを受け入れる |

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

現在の snctl 設定を表示します。

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

`config.yaml`、インベントリファイル、暗号鍵、シークレットファイルへのパスに加え、GCS サービスアカウントやログディレクトリなどの任意設定を表示します。snctl が初期化されていない場合は、その旨を表示して正常終了します。

コマンド固有のフラグはありません。

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

## config update

既存の snctl 設定のフィールドを更新します。

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

初期化済みの設定が必要です。値をクリアするには空文字列を渡します。

| フラグ | 説明 |
| - | - |
| `--service-account <path>` | GCS からファームウェアをダウンロードする際に使用する、Google サービスアカウント JSON ファイルへの絶対パス (空文字列でクリア) |
| `--cache-location <path>` | ファームウェアのダウンロードキャッシュディレクトリへの絶対パス (空文字列で XDG デフォルトにリセット) |

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

snctl のインストールと環境の健全性を診断します。

## diag doctor

システムの依存関係と環境の健全性を確認します。

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

電源操作やファームウェア操作に必要な `ipmitool` などのツールを含め、snctl が必要とするすべてのシステム依存関係がインストールされていることを検証し、その状態を報告します。コマンドが予期せず失敗する場合に実行してください。

コマンド固有のフラグはありません。

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

***

# rack

ラックインベントリを管理します。

## rack add

新しいラックをインベントリに追加します。

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

`--partnumber` はハードウェアモデルを識別し、これによってラックに自動生成されるコンポーネントレイアウトが決まります。

| フラグ | 説明 |
| - | - |
| `--partnumber <value>` | **必須。**`1001934` または `1002331` |

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

## rack add-device

ラック内のデバイスを追加または更新します。

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

`<target>` は [デバイスパス](#デバイスパス) です。フィールドを省略すると現在の値が維持されます (部分更新)。

| フラグ | 説明 |
| - | - |
| `--ip <address>` | デバイスの IP アドレス |
| `--hostname <name>` | デバイスのホスト名 |
| `--user <username>` | ログインユーザー名 |
| `--port <n>` | 接続ポート |
| `--device-type <type>` | デバイスタイプ — [デバイスタイプ](#デバイスタイプ) をご参照ください |
| `--index <n>` | デバイスのインデックス。パスの指定を上書きする (デフォルト `-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

ラックをインベントリから削除します。

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

ラックと、それに関連付けられたすべての SN40L ノードを削除します。

<Warning>
  ローカルのインベントリにのみ影響します。物理ハードウェアの電源を切ったり変更を加えたりすることはありません。誤って削除した場合は、`snctl rack add <rack_id> --partnumber <part>` で再登録してください。
</Warning>

コマンド固有のフラグはありません。

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

## rack delete-device

ラックからデバイスを削除します。

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

コンポーネントをローカルのインベントリからのみ削除します。物理ハードウェアには影響しません。

| フラグ | 説明 |
| - | - |
| `--device-type <type>` | 削除するデバイスタイプ — [デバイスタイプ](#デバイスタイプ) をご参照ください |
| `--index <n>` | デバイスのインデックス。**PDU と XRDU では必須** (デフォルト `-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

ラックを JSON または YAML ファイルにエクスポートします。

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

ラック ID を指定しない場合、すべてのラックがエクスポートされます。

<Note>
  パスワードは常にプレースホルダ値に置き換えられるため、エクスポートファイルは安全に共有できます。
</Note>

| フラグ | 説明 |
| - | - |
| `--file <path>` | 出力ファイルのパス (デフォルト: 標準出力) |
| `-o, --output <format>` | `json` または `yaml`。`--file` の拡張子から推測されます。標準出力への出力時のデフォルトは `json` |

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

JSON または YAML ファイルからラックとグループをインポートします。

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

ファイルは snctl ネイティブのインベントリで、ラックのみ、グループのみ、またはその両方の一部を含むことができます。標準入力から読み込むには `-` を使用します。

| フラグ | 説明 |
| - | - |
| `--dry-run` | インベントリを変更せずに変更内容をプレビューする |
| `--overwrite` | 既存のラックとグループを置き換える。指定しない場合、既存のエントリはスキップされ、その旨が報告される |

**認証情報の扱い**。ソースファイル内の、プレースホルダになっていないデバイスパスワードは、デバイス単位の認証情報として暗号化された認証情報ストアにインポートされます。インベントリ自体にはプレースホルダのみが保存されます。デフォルトの認証情報が未設定のデバイス種別については、その種別で最も番号の小さいラックのパスワードが、その種別のデフォルトにもなります。シークレットが出力されることはありません。`--dry-run` は、何も書き込まずに、インポートされるシークレットの件数を報告します。

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

インベントリ内のすべてのラックを一覧表示します。

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

各ラックの ID、ハードウェアタイプ、コンポーネント数を表示します。コマンド固有のフラグはありません。

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

## rack show

ラック内のすべてのデバイスを表示します。

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

すべてのコンポーネントを、ホスト名、IP アドレス、ポート、ユーザー名とともに表示します。電源コマンドやファームウェアコマンドを実行する前の、ネットワークアドレス設定の確認に使用してください。コマンド固有のフラグはありません。

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

インベントリ内のノードを管理します。

## node list

インベントリ内のすべてのノードを一覧表示します。

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

各ノードの名前、所属ラックの ID、ラックのハードウェアタイプ、スロットインデックスを表示します。コマンド固有のフラグはありません。

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

## node rename

ノードの名前を変更します。

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

新しい名前は、全ノードの中で一意である必要があります。

<Note>
  ローカルのインベントリに対する操作のみです。ハードウェア自体のホスト名は変更されません。
</Note>

コマンド固有のフラグはありません。

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

## node show

ノード内のすべてのデバイスを表示します。

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

すべてのコンポーネントサブデバイス (BMC、ホスト、XRDU) を、ホスト名、IP アドレス、ポート、ユーザー名とともに表示します。コマンド固有のフラグはありません。

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

***

# group

ラックグループを管理します。グループを使用すると、ファームウェアコマンドと電源コマンドを単一の操作で複数のラックに一括展開できます。

## group create

グループを作成するか、その説明を更新します。

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

同名のグループがすでに存在する場合は、その説明が更新されます。

| フラグ | 説明 |
| - | - |
| `-d, --description <text>` | **必須**。グループの説明 |

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

1 つ以上のラックをグループに追加します。

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

グループはあらかじめ存在している必要があります。すでにグループに属しているラックについては警告が表示され、エラーにはならずスキップされます。

| フラグ | 説明 |
| - | - |
| `-r, --rack-id <ids>` | **必須**。追加するラック ID (カンマ区切りで複数指定可) |

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

グループからラックを削除します。

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

ラックはインベントリに登録されたまま残り、他のグループに追加できます。削除されるのは、このグループへの所属のみです。

| フラグ | 説明 |
| - | - |
| `--rack-id <id>` | **必須**。削除するラック ID |

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

## group list

インベントリ内のすべてのグループを一覧表示します。

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

各グループの名前、説明、所属ラック数を表示します。コマンド固有のフラグはありません。

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

## group show

グループとその所属ラックを表示します。

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

グループの説明と、所属ラックをハードウェアタイプとともに表示します。コマンド固有のフラグはありません。

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

## group delete

グループをインベントリから削除します。

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

削除前に確認を求められます。

<Note>
  所属ラックは削除**されません** — グループのレコードのみが削除されます。スクリプト内でプロンプトを抑制するには、`SNCTL_NON_INTERACTIVE=1` を設定してください。
</Note>

コマンド固有のフラグはありません。

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

***

# secret

デバイスシークレットを管理します。認証情報は AES-GCM で暗号化され、`~/.snctl/credentials.json.enc` に保存されます。

## secret set

デバイスシークレットを設定または削除します。

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

値の入力と確認を対話的に求められます。入力内容がターミナルに表示 (エコー) されることはありません。電源コマンドやファームウェアコマンドを実行する前に、環境で使用するすべてのコンポーネントタイプの認証情報を設定してください。

| フラグ | 説明 |
| - | - |
| `--device-type <type>` | コンポーネント種別のデフォルトを設定する — [デバイスタイプ](#デバイスタイプ) をご参照ください |
| `--device <path>` | デバイス単位のオーバーライド用の正規の [デバイスパス](#デバイスパス) |
| `--clear` | 認証情報を設定する代わりに削除する (プロンプトなし) |

デバイス単位の認証情報は、種別レベルのデフォルトよりも優先されます。未設定の認証情報をクリアしてもエラーにはならず正常に完了します。デバイス単位のオーバーライドをクリアすると、そのデバイスは種別レベルの認証情報にフォールバックします。

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

デバイスシークレットを取得します。

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

値はデフォルトで `***` にマスクされます。

| フラグ | 説明 |
| - | - |
| `--device-type <type>` | 照会するデバイス種別 — [デバイスタイプ](#デバイスタイプ) をご参照ください |
| `--device <path>` | 正規の [デバイスパス](#デバイスパス) — オーバーライド、種別デフォルト、レガシーシークレットの順に解決し、値がどの階層に由来するかを表示する |
| `--show-value` | パスワードを平文で表示する |

<Warning>
  `--show-value` は安全な環境でのみ使用してください。出力は決して共有しないでください。
</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

ノードの電源オン、電源オフ、パワーサイクル、状態照会を行います。操作は IPMI または Redfish 経由で実行されます。

<Note>
  すべての電源コマンドでは、`--node` **または** `--group` のいずれか一方の指定が必須です (同時には指定できません)。また、事前に [`secret set`](#secret-set) でデバイス認証情報を設定しておく必要があります。
</Note>

## power state

ノード、ホスト、または XRDU の電源状態を照会します。

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

現在の DC 電源状態 (on/off/unknown) を報告します。読み取り専用のため、いつでも安全に実行できます。

| フラグ | 説明 | デフォルト |
| - | - | - |
| `--node <name\|rack_id>` | ノード名またはラック ID | |
| `--group <name>` | 指定した名前のグループ内のすべてのノードを対象にする | |
| `--type <kind>` | `node`、`host`、または `xrdu` | `node` |
| `--protocol <proto>` | デフォルトのプロトコルを上書きする: `ipmi`、`ssh`、`redfish` (コンポーネントに依存) | |
| `-p, --parallelism-racks <n>` | 同時に処理するラック数の上限 | `0` (上限なし) |
| `--parallelism-devices <n>` | 全ラック合計で同時処理するノード数のグローバル上限 | `0` (上限なし) |

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

ノード、ホスト、または XRDU の電源を入れます。

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

電源オン後、snctl は `snd.service` (SambaNova Daemon) がアクティブになるのを待ってから完了します。

| フラグ | 説明 | デフォルト |
| - | - | - |
| `--node <name\|rack_id>` | ノード名またはラック ID | |
| `--group <name>` | 指定した名前のグループ内のすべてのノードを対象にする | |
| `--type <kind>` | `node`、`host`、または `xrdu` | `node` |
| `--skip-snd-check` | 起動後の `snd.service` の待機をスキップする | |
| `--protocol <proto>` | デフォルトのプロトコルを上書きする | |
| `-p, --parallelism-racks <n>` | 同時に処理するラック数の上限 | `4` |
| `--parallelism-devices <n>` | 全ラック合計で同時処理するノード数のグローバル上限 | `0` (上限なし) |

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

ノード、ホスト、または XRDU の電源を切ります。

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

| フラグ | 説明 | デフォルト |
| - | - | - |
| `--node <name\|rack_id>` | ノード名またはラック ID | |
| `--group <name>` | 指定した名前のグループ内のすべてのノードを対象にする | |
| `--type <kind>` | `node`、`host`、または `xrdu` | `node` |
| `--protocol <proto>` | デフォルトのプロトコルを上書きする | |
| `-p, --parallelism-racks <n>` | 同時に処理するラック数の上限 | `1` |
| `--parallelism-devices <n>` | 全ラック合計で同時処理するノード数のグローバル上限 | `0` (上限なし) |

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

ノード全体のパワーサイクルを実行します。

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

グレースフルに電源をオフにしてから、オンにします。**常にノード全体を対象とし、`--type` フラグはありません**。完了前に `snd.service` を待機します。

| フラグ | 説明 | デフォルト |
| - | - | - |
| `--node <name\|rack_id>` | ノード名またはラック ID | |
| `--group <name>` | 指定した名前のグループ内のすべてのノードを対象にする | |
| `--skip-snd-check` | 起動後の `snd.service` の待機をスキップする | |
| `--protocol <proto>` | デフォルトのプロトコルを上書きする | |
| `-p, --parallelism-racks <n>` | 同時に処理するラック数の上限 | `1` |
| `--parallelism-devices <n>` | 全ラック合計で同時処理するノード数のグローバル上限 | `0` (上限なし) |

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

***

# firmware

ノードのファームウェアの照会と更新を行います。

<Note>
  どちらのコマンドでも、`--rack-id` **または** `--group` のいずれか一方の指定が必須です (同時には指定できません)。また、事前に [`secret set`](#secret-set) でデバイス認証情報を設定しておく必要があります。
</Note>

## firmware version

ラックのコンポーネントにインストールされているファームウェアバージョンを照会します。

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

結果には、現在インストールされているバージョン (`CURR`) がプランオブレコード (Plan of Record; POR) のバージョン (`POR`) と並べて表示されるため、乖離を一目で把握できます。

| フラグ | 説明 | デフォルト |
| - | - | - |
| `-r, --rack-id <id>` | 照会するラック ID | |
| `--group <name>` | 指定した名前のグループ内のすべてのラックを対象にする | |
| `--device-type <type>` | `all`、`bios`、`bmc`、`xrdu`、`card`、`pdu`、`serial_terminal`、`access_switch`、`data_switch` | `all` |
| `--index <indices>` | スロット型デバイスタイプのスロットインデックス (カンマ区切り。例: `0,2,5`) | |
| `--protocol <proto>` | デフォルトのプロトコルを上書きする: `ssh`、`rest`、`redfish` (エンドポイントに依存) | |
| `-p, --parallelism-racks <n>` | 同時に処理するラック数の上限 | `0` (上限なし) |
| `--parallelism-devices <n>` | 全ラック合計で同時処理するノード数のグローバル上限 | `0` (上限なし) |

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

ラックのコンポーネントにファームウェアイメージを適用します。

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

| フラグ | 説明 | デフォルト |
| - | - | - |
| `-r, --rack-id <id>` | 対象のラック ID | |
| `--group <name>` | 指定した名前のグループ内のすべてのラックを対象にする | |
| `--device-type <type>` | **必須。**`all`、`bios`、`bmc`、`xrdu`、または `card` | |
| `--image <path>` | ローカルのファームウェアイメージのパス。複数回指定可 — 下記参照 | |
| `--index <indices>` | `xrdu` と `card` のスロットインデックス (カンマ区切り。例: `0,2`)。省略するとすべてのインスタンスをアップグレードする | |
| `--protocol <proto>` | デフォルトのプロトコルを上書きする (エンドポイントに依存) | |
| `-p, --parallelism-racks <n>` | 同時に処理するラック数の上限 | `1` |
| `--parallelism-devices <n>` | 全ラック合計で同時処理するノード数のグローバル上限 | `0` (上限なし) |

**`--image` の動作**。省略した場合、各コンポーネントの POR バージョンに対応する正しいファイルが GCS から自動的にダウンロードされ、チェックサム検証のうえキャッシュされます。代わりに特定のローカルファイルを書き込むには `--image` を渡します。エアギャップ環境では必須です。

| デバイスタイプ | `--image` の形式 |
| - | - |
| `bios`, `bmc`, `card` | プレフィックスなしのパス: `--image /path/to/file` |
| `xrdu` | コンポーネントプレフィックスを付けて 2 回指定: `--image obmc=/path/to/obmc.tgz --image rduc=/path/to/rduc.tgz` |

**`--index` の制約。**`xrdu` と `card` でのみ使用できます。`bios`、`bmc`、`all` では拒否されます。BIOS と BMC はスロットを持たないノードレベルのコンポーネントであり、`all` は両方の種別が混在するため、インデックスを指定するとアップグレードの一部だけが絞り込まれてしまうためです。

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

バージョンとビルド情報を表示します。

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

リリースバージョン、git コミットハッシュ、ビルドタイムスタンプ、Go ランタイムバージョン、OS/アーキテクチャを表示します。サポートリクエストを提出する際は `-o json` を使用してください。

コマンド固有のフラグはありません。

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