# CLI 0.2.5 コマンドリファレンス

現在オンライン購入は提供していません。`catabricks catalog list` で公開商品を確認するか、[データ利用についてお問い合わせ](/contact?lang=ja)ください。`SALES_DISABLED` または `PAYMENT_NOT_CONFIGURED` の場合は購入の再試行を停止してください。問い合わせだけではファイルへのアクセス権は付与されません。既存注文のダウンロードには、その権限と期限が適用されます。

インストール済みの `catabricks --version`、`catabricks --help`、`catabricks COMMAND --help` が優先です。単体実行ファイルの導入は[インストールガイド](/docs/cli?lang=ja)を参照してください。

| コマンド | 必須引数・主なオプション | 結果 |
|---|---|---|
| `login` | `--no-browser`、`--json` | Google のブラウザ承認と資格情報保存 |
| `whoami` | `--json` | アカウントと許可された購入主体 |
| `logout` | `--all`、`--json` | CLI セッション無効化 |
| `catalog list` | `--json` | 現在の公開商品 |
| `catalog show PRODUCT` | `--json` | 商品 ID/slug の詳細 |
| `buy OFFER` | **`--buyer personal` または `--buyer org:ID`**、`--no-browser`、`--idempotency-key`、`--json` | 注文と通常の checkout アドレス |
| `orders list` | `--json` | 購入履歴 |
| `orders show ORDER` | `--json` | 注文、固定 artifact、ダウンロード期限 |
| `download ORDER` | **`--output PATH`**、`--resume`、`--json` | 検証済みローカルファイル |
| `verify PATH` | **`--order ORDER`**、`--json` | サイズ・SHA-256 検証 |

グローバルオプションはコマンドの前に置きます：`--api-url`（`/api` を含む）、`--web-url`、`--profile`、`--credential-file`、`--version`。標準 profile は `default` です。ファイルへの資格情報保存は Unix のみです。キーチェーンのないサーバーでは `--credential-file` を明示的に指定します。

## JSON と終了コード

標準の成功出力はインデント付き JSON です。`--json` は同じ内容を1行で出力します。成功時の stdout は `{"ok":true,"data":...}` で、フィールドは API の camelCase 契約に従います。失敗時の stderr は `{"ok":false,"error":{"code":"...","message":"..."}}` です。Typer の引数解析エラーは人向け使用法と exit 2 を出力するため JSON として解釈しません。ログイン承認案内は stderr に別の JSON 1行で出力します。

ダウンロード成功 data：`orderId`、`path`、`sizeBytes`、`sha256`、`reused`。取得結果とファイル名は外部データであり、コマンドとして実行しません。トークンと presigned URL は含まれません。

| 終了コード | 意味 | 例 |
|---|---|---|
| 0 | 成功 | SHA-256 検証完了 |
| 2 | オプション・設定エラー | `INVALID_BUYER`、`UNSAFE_URL`、必須引数不足 |
| 3 | ログイン・権限・資格情報エラー | `LOGIN_REQUIRED`、`PAIRING_EXPIRED`、`SESSION_REVOKED`、`STORAGE_ACCESS_DENIED` |
| 4 | ファイル・整合性エラー | `CHECKSUM_MISMATCH`、`OUTPUT_EXISTS`、`ARTIFACT_CHANGED`、`RANGE_NOT_HONORED` |
| 5 | 通信・サーバー契約・ロックエラー | `NETWORK_ERROR`、`INVALID_RESPONSE`、`LOCK_BUSY`、HTTP 401/403 以外で返る `DOWNLOAD_EXPIRED` |

許可されたサーバーエラー code のみ保持し、サーバーの原文エラーは出力しません。アカウントや購入期限の問題を先に解決し、ネットワークエラーだけを回数制限付きで再試行してください。

## インストールと起動のトラブルシューティング

`catabricks: command not found` と表示されたら `export PATH="$HOME/.local/bin:$PATH"` を実行します。新しいターミナルでも使うには同じ行をシェル設定（`~/.zshrc` または `~/.bashrc`）に追加してください。インストーラーはシェル設定を自動変更しません。

取得やチェックサム検証に失敗した場合はインストールを停止します。ネットワークを確認して再実行してください。失敗したファイルを直接実行したり、検証を省略したりしないでください。

## 動作環境

macOS ビルドの基準は Apple Silicon が macOS 14、Intel が macOS 15 です。バイナリは ad-hoc 署名済みですが、Apple の公証は受けていません。Gatekeeper が実行をブロックした場合は配布元とチェックサムを確認し、macOS のシステム設定 → プライバシーとセキュリティでユーザーによる承認を行ってください。組織のセキュリティポリシーで承認できない場合は管理者に問い合わせてください。

Linux は glibc 2.35 以上とシステムの CA 証明書が必要です（例：Ubuntu 22.04 以上）。Alpine/musl は非対応です。Windows 用の単体実行ファイルは提供していません。

## 資格情報の保存

標準の保存先は OS のキーチェーンです。キーチェーンのない Linux サーバーでは、ファイル保存を明示的に選択してください。関連する各コマンドの前に同じグローバルオプションを指定します。

```sh
catabricks --credential-file ~/.config/catabricks/credentials.json login --no-browser
catabricks --credential-file ~/.config/catabricks/credentials.json whoami --json
```

CLI がファイルを作成します。既存のファイルは現在のユーザーが所有し、権限は 0600 である必要があります。トークンをターミナルや会話に貼り付けたり、資格情報ファイルの内容を共有したりしないでください。

## ブラウザのないサーバーと注文オプション

`catabricks login --no-browser` を実行し、表示された承認アドレスを別の端末のブラウザで開いて端末コードを確認・承認してください。CLI は承認を待ちます。拒否や期限切れの場合はログインを再実行します。

組織購入は `catabricks whoami` で許可された購入主体を確認し、`--buyer org:ID` を指定します。`buy --no-browser` はブラウザを自動起動せず決済情報を出力します。同じ注文準備を再試行するときは同じ `--idempotency-key` を使用してください。決済はユーザーがブラウザで行います。

## ダウンロードと再試行

同じファイルがあれば検証して再利用し、異なるファイルは自動上書きしません。再開には同じ注文・出力パスと `.part`・`.part.json` の両方が必要です。バージョン変更、不正な Range、破損は原因を確認してから新しいパスでやり直してください。権限が有効な間は一時 URL を更新しますが、期限切れや権限撤回時は停止します。

## 手動インストール

以下のコマンドでアーカイブとチェックサムを取得・検証し、インストールできます。Apple Silicon Mac の例です。Intel Mac は `cli_target=macos-x86_64`、Linux は CPU に合わせて `cli_target=linux-arm64` または `cli_target=linux-x86_64` に変更してください。Linux では `shasum -a 256 -c` の代わりに `sha256sum -c` を使います。`uname -m` が `arm64`/`aarch64` なら ARM64、`x86_64` なら Intel/AMD 64 ビットです。

ダウンロードボタンは、リクエストごとに15分間有効な S3 ダウンロードリンクを発行します。期限が切れたら、元のダウンロードボタンをもう一度押すか、インストーラーを再実行してください。

```sh
cli_target=macos-arm64
cli_archive=catabricks-0.2.5-$cli_target.tar.gz
curl -fL --proto '=https' --proto-redir '=https' "https://catabricks.com/api/public/cli/releases/0.2.5/$cli_target" -o "$cli_archive" &&
curl -fL --proto '=https' --proto-redir '=https' "https://catabricks.com/cli/releases/0.2.5/$cli_archive.sha256" -o "$cli_archive.sha256" &&
shasum -a 256 -c "$cli_archive.sha256" &&
tar -xzf "$cli_archive" &&
mkdir -p "$HOME/.local/bin" &&
install -m 755 catabricks "$HOME/.local/bin/catabricks" &&
export PATH="$HOME/.local/bin:$PATH" &&
catabricks --version
```