# コマンドラインインターフェース

`keenauth` のコマンドラインインターフェース (CLI) は、ターミナルまたはスクリプトから管理 API を呼び出します。各コマンドは Go SDK の型付きメソッドを 1 つラップしているため、CLI と API は同じように動作します。インストールパッケージはまだありません。

## 認証と接続先

CLI は認証情報を環境変数からのみ読み取ります。API キーはフラグとしては受け付けないため、シェルの履歴に残ることはありません。

| 変数 | 必須 | 説明 |
|---|---|---|
| `KEENAUTH_API_KEY` | はい | 管理 API キー。未設定の場合、コマンドは終了コード 3 で終了します。 |
| `KEENAUTH_BASE_URL` | はい。ただし `--base-url` を指定した場合を除く | 環境の管理 API ベース URL。 |

API キーの代わりに、ダッシュボードのアカウントでサインインすることもできます: `keenauth login`、その後 `keenauth env use <environment_id>`。セッションは `KEENAUTH_API_KEY` が設定されていない場合にのみ使用され、環境のアドレスはコントロールプレーンから取得されます（[keenauth login でのサインイン](/docs/cli/login) を参照）。

`--base-url` フラグは 1 つのコマンドについて `KEENAUTH_BASE_URL` を上書きします。CLI は API キーを決して表示しません。サーバーのレスポンスにキーが含まれている場合は、`[redacted]` に置き換えられます。

## コマンド

コマンドは `keenauth <group> <action> [arguments] [flags]` の形式に従います。全一覧は `keenauth --help` または `keenauth <group> --help` で確認できます。

| グループ | アクション |
|---|---|
| `users` | `list`, `search`, `get`, `create`, `update`, `delete`, `block`, `unblock`, `cancel-deletion`, `authenticators list`, `authenticators delete`, `authenticators reset`, `authenticators reactivate`, `send-password-reset`, `send-verification-email`, `emails send-verification`, `start-recovery`, `logs list` |
| `applications` | `list`, `create`, `get`, `update`, `delete`, `get-api-grant`, `put-api-grant`, `delete-api-grant`, `credentials list`, `credentials create`, `credentials delete` |
| `apis` | `list`, `create`, `get`, `update`, `delete` |
| `connections` | `list`, `create`, `get`, `update`, `delete`, `activate`, `deactivate` |
| `identity-settings` | `get`, `update` |
| `environment-settings` | `get`, `update` |
| `config` | `export`（`-o` がない場合は YAML を出力）、`plan -f <file>`（ターミナルでは読みやすい差分を表示）、`plans get`、`apply <plan_id>`（確認を求めます。`--secrets-from-env` は環境変数からシークレットを読み取ります、`--confirm-deletion <kind>/<key>`）、`promote --from <env> --to <env>`（エクスポート、計画、差分表示を行い、確認後に適用します。[keenauth config promote による設定の昇格](/docs/cli/config-promote) を参照） |
| `api-keys` | `list`, `get`, `create`, `rotate`, `revoke` |
| `logs` | `list`, `get`, `tail`（新しいレコードを追跡します。`--type`, `--user`, `--org`。[keenauth logs tail によるログの追跡](/docs/cli/tail) を参照） |
| `support-access-grants` | `list`, `get`, `create`, `delete`（[keenauth support-access-grants によるサポートアクセスの付与](/docs/cli/support-access-grants) を参照） |
| `directories` | `simulate <directory_id> --scenario <name>`（開発環境およびステージング環境で SCIM シミュレーターのシナリオを実行します。[keenauth directories simulate による SCIM プロビジョニングのテスト](/docs/cli/directories-simulate) を参照） |
| `audit` | `verify`（ダウンロードした監査エクスポートをオフラインで検証します。[keenauth audit verify による監査エクスポートの検証](/docs/cli/audit-verify) を参照） |
| `branding` | `get`, `update`, `applications get`, `applications put`, `organizations get`, `organizations put`, `css put`, `page-template put`, `publish`, `rollback`, `versions list`, `texts get`, `texts put`, `texts delete` |
| `signing-keys` | `list`, `rotate`, `policy get`, `policy update` |
| `events` | `tail`（Event API 経由で顧客イベントを追跡します。[keenauth events tail によるイベントの追跡](/docs/cli/events-tail) を参照）、`get <event ID>`（1 件のイベントを、サーバーが送信したとおりに表示） |
| `mock` | `serve` はオフラインテスト用にローカルの OIDC モックサーバーを起動します。API キーは不要です（[ローカルモックサーバー](/docs/cli/mock-server) を参照） |
| `test` | `login --user <+test address>` は、固定コードを使ってテストユーザーを `development` 環境にサインインさせ、トークンを表示します。API キーは不要です（[keenauth test login によるテストユーザーのサインイン](/docs/cli/test-login) を参照） |
| `webhooks` | `listen --forward-to <local URL>` は `development` または `staging` 環境のイベントを、一時的なシークレットで署名したうえでお使いのマシンに転送します（[keenauth webhooks listen によるWebhookのローカルテスト](/docs/cli/webhooks-listen) を参照） |
| `login`, `logout`, `whoami`, `env` | `login`（`--web`, `--insecure-storage`）、`logout`、`whoami`、`env use <environment_id>`、`env list`: API キーではなく、ダッシュボードのアカウントでサインインします（[keenauth login でのサインイン](/docs/cli/login) を参照） |

一覧系のコマンドは `--limit`、`--after`、`--before` および `--order` を受け付けます。さらに結果がある場合、次のカーソルは `more results: --after <cursor>` の形式で標準エラー出力に表示されます。

## 出力形式

`--output`（`-o`）で `table`、`json` または `yaml` を選択します。フラグを指定しない場合、CLI はターミナルではテーブルを、それ以外では JSON を出力します。JSON と YAML は API レスポンスをそのまま含み、翻訳されることはないため、スクリプトで安心して利用できます。結果は標準出力に、エラー、ヒント、`etag` の行は標準エラー出力に出力されます。

## リクエストボディ

ボディを送信するコマンドは、フラットなフィールドごとにフラグを 1 つ受け付けます。フラグ名は JSON のキーをダッシュ区切りにしたものです（`phone_number` は `--phone-number` になります）。ネストされたオブジェクトは `--data` で指定します:

- `--data @file.json` はファイルからボディを読み込みます。
- `--data -` は標準入力からボディを読み込みます。

フラグはファイルのフィールドを上書きします。ボディは 4 MiB までに制限されています。

```sh
keenauth users create --email ada@example.com
keenauth apis create --data @api.json
echo '{"name":"Orders"}' | keenauth apis update api_123 --data - --if-match '"v3"'
```

## 楽観的同時実行制御: `--if-match` と etag

アプリケーション、API、接続の更新および削除コマンドは `--if-match` を必要とします。`users update` もこれを受け付けます。値は変更したいバージョンの `ETag` です。リソースがその間に変更されていた場合、サーバーはリクエストを拒否します。`identity-settings update` も同様に必要とします。`environment-settings update` も同様に必要とします。ブランディングのドラフトへの書き込み（`branding update`, `branding applications put`, `branding organizations put`, `branding css put`, `branding page-template put`）もこれを必要とします。

各 `get` コマンド（`users`, `applications`, `apis`, `connections`, `identity-settings`, `environment-settings`）は、レスポンスの `ETag` を標準エラー出力に表示するため、標準出力は汚れません:

```sh
$ keenauth apis get api_123
{ ... }
etag: "v3"
$ keenauth apis update api_123 --name Orders --if-match '"v3"'
```

`etag` 行は JSON または YAML の出力には追加されません。

## 破壊的コマンドと `--yes`

削除またはブロックを行うコマンドは、ターミナル上で確認（`[y/N]`）を求めます。確認を拒否すると終了コード 1 で終了し、`aborted` を表示します。標準入力がターミナルでない場合、`--yes`（`-y`）を指定しない限りコマンドは実行を拒否し、リクエストを送信する前に終了コード 2 で終了します。

## 終了コード

| コード | 意味 |
|---|---|
| `0` | 成功。 |
| `1` | サーバーまたは運用上のエラー、確認の拒否、またはネットワークの障害。 |
| `2` | 使用方法のエラー: 不明なコマンドまたはフラグ、引数の欠落、無効なボディ、または非対話型ターミナルで `--yes` が欠けている場合。 |
| `3` | 認証エラー: キーが未設定、またはサーバーが 401 または 403 を返した場合。 |
| `4` | プランにその機能が含まれていません（`403` は `plan_feature_unavailable` の場合）。 |

サーバーエラーの場合、CLI は `error`、`code`、`status`、`detail`、`request_id` と、検証エラーごとに `field` の行を標準エラー出力に表示します。サポートに問い合わせる際は `request_id` を添えてください。

## 言語

ヘルプ、プロンプト、エラー、テーブルの見出しなどの人が読むテキストは、トルコ語 (`tr`)、英語 (`en`)、フランス語 (`fr`)、ドイツ語 (`de`)、韓国語 (`ko`)、日本語 (`ja`)、イタリア語 (`it`)、スペイン語 (`es`) で利用できます。言語は、次の変数のうち最初に設定されたものから選ばれます: `KEENAUTH_LANG`, `LC_ALL`, `LC_MESSAGES`, `LANG`（例えば `tr_TR.UTF-8` は `tr` を選択します）。空の値またはサポートされていない値の場合は英語が選ばれ、ある言語にメッセージがない場合は英語にフォールバックします。

機械が読み取る出力は翻訳されません。JSON と YAML のフィールド名と値、問題の `code`、および `code`, `status`, `request_id` のラベルは、すべての言語で同じままです。サーバーからのメッセージは、サーバーが送ったとおりに表示されます。

```sh
KEENAUTH_LANG=de keenauth users list --help
```

## アプリケーションのクレデンシャル

`keenauth applications credentials list|create|delete` はアプリケーションのクライアントシークレットと登録済みの公開鍵を管理します。これらのコマンドは `--if-match` を使用しません。

```sh
keenauth applications credentials create app_123 --type client-secret --expires-at 2027-01-01T00:00:00Z
keenauth applications credentials create app_123 --type public-key --jwk-file key.pub.jwk
keenauth applications credentials delete app_123 cred_456 --yes
```

クライアントシークレットは一度だけ標準出力に表示され、標準エラー出力には一度限りの警告が出ます。`--jwk-file` は単一の公開 JWK（最大 16 KiB）を受け付けます。秘密鍵のメンバーを含むファイルは、リクエストを送信する前に拒否されます。

## API キー

`keenauth api-keys list|get|create|rotate|revoke` は環境の管理 API キーを管理します。これらのコマンドは `--if-match` を使用しません。

```sh
keenauth api-keys create --name ci --type restricted --permissions users:read,users:write --expires-at 2027-10-01T00:00:00Z
keenauth api-keys rotate key_123 --overlap-hours 24
keenauth api-keys revoke key_123 --reason leaked --yes
```

`create` と `rotate` の生のキーは一度だけ標準出力に表示され、標準エラー出力には一度限りの警告が出ます。再度取得することはできません。`list` と `get` はメタデータのみを表示します。