CLI コマンド

keelson CLI の主なコマンドと、スクリプトやエージェントから使うときに知っておくべき挙動をまとめています。通常は AI エージェントが Skill を通じて実行するので、すべてを覚える必要はありません。各コマンドの使い方は keelson <コマンド> --help でも確認できます。

インストールはクイックスタート、更新は keelson upgrade で行います。

以下のコマンド例では、<...> は指定する値、[...] は省略できる引数やフラグを表します。<duration> には 30s や 5m のような期間、<n> には整数を指定します。

共通フラグ

複数のコマンドで使えるフラグです。対応状況はコマンドによって異なり、login / logout / install-agent / dev ... などでは使えるフラグが限られます。app curl は --json と --quiet を受け付けません。

フラグ	内容
--app <slug>	対象アプリ。省略時はカレントディレクトリの keelson.yaml から解決。access show / access set / apps tokens create / apps tokens rotate / feedback は省略できない
--workspace <slug|name|id>	対象ワークスペースを slug、名前、ID のいずれかで指定する。同名のワークスペースがある場合は slug か ID を使う
--json	結果を JSON で出力。スクリプトやエージェントから使うときに
--quiet	説明や進捗を抑える。出力内容はコマンドによって異なる
--timeout <duration>	API 呼び出しのタイムアウト。通常は既定 15 秒。例外は下記を参照
--retry <n>	一時的な失敗の再試行回数。通常は既定 0 回。例外は下記を参照
--no-browser	ブラウザを自動で開かず、ログイン・承認用 URL を表示する。login / apps delete / db apply / snapshots restore で使える

ワークスペースは、--workspace → keelson.yaml の workspace → 保存済みの既定ワークスペース、の順に選ばれます。ここまでで対象が決まらない場合、所属先が 1 つならそれが選ばれ、複数なら --workspace での指定が必要です。apps list は例外で、省略時は全ワークスペースを対象にします。

--quiet を付けると、secrets set はシークレット名ごとに 1 行、deploys list はデプロイ ID ごとに 1 行を出力します。deploy --check は成功時に何も出力しません。

タイムアウトと再試行回数には、次の例外があります。

• apps duplicate のタイムアウトは既定 120 秒です。
• app curl のアプリへのリクエストはタイムアウトが既定 130 秒で、GET / HEAD の一時的な失敗は最大 2 回再試行します。--retry 0 で再試行を無効にできます。
• deploy --new のアプリ作成処理は、--retry 0 でも一時的な失敗に対して最大 3 回再試行します。この処理の再試行回数は 3 回未満に設定できません。--retry に 3 より大きい値を指定すると、その回数まで再試行します。

preview / app curl は、ブラウザでの承認が必要な場合も --no-browser を受け付けません。非対話実行ではブラウザを自動で開かず、承認用 URL を出力します。preview --json でも同様です。

--json でコマンドが失敗すると、標準出力に error オブジェクトが返ります。code はエラーコード、message は説明、hint は対処方法です。retryable が false の場合は自動再試行せず、hint に従って対処してください。

--tenant や keelson tenants list などの旧名も受け付けます。コマンドの別名を参照してください。

セットアップ

コマンド	内容
keelson login [--no-browser]	ブラウザでログインし、この端末を紐付ける
keelson logout [--all-devices]	この端末の保存済みログイン情報を削除し、サーバー側のセッションを失効させる。--all-devices ですべての端末をログアウト。KEELSON_TOKEN で渡したトークンは失効しない
keelson whoami	ログイン中のユーザーと、現在選ばれているワークスペース。ワークスペースの slug を確実に取るには workspaces list --json を使う
keelson workspaces list [--query <text>] [--exact]	所属ワークスペースの一覧・検索。--json の slug が --workspace に渡す値
keelson doctor [--fix-path]	PATH・ログイン・Skill の状態を確認。--fix-path はシェルの設定ファイルに PATH を追記
keelson install-agent <claude-code|codex|cursor> [--global]	AI エージェントに Skill を入れる。引数なし + --yes で入れてある Skill をすべて更新
keelson upgrade	CLI を最新版に更新
keelson version	バージョン表示
keelson telemetry status|off|on	CLI の利用状況データの状態確認、停止、有効化
keelson feedback --app <slug> [--deploy <id>] < feedback.json	CLI や Skill の使い勝手を標準入力の JSON で送る。形式はフィードバックを参照

keelson install-agent の代わりに、公開リポジトリからスキルをインストールすることもできます。Claude Code では /plugin marketplace add keelsonhq/skills に続けて /plugin install keelson@keelson-skills を実行します。ほかのエージェントでは npx skills add keelsonhq/skills を使います。インストール方法はどれか 1 つだけを使ってください。組み合わせると、同じスキルが 2 つ入ったり、互いに上書きしたりすることがあります。これらの方法でインストールされるのはスキルだけなので、CLI のインストールとログインも必要です。

Claude Code プラグインとして入れたスキルは keelson login では自動更新されず、Claude Code のプラグイン更新で追随します。プラグインは keelson doctor の検査対象外の場所にあるため、Claude Code が「not configured」と表示され、install-agent を案内されても従う必要はありません。

デプロイ

コマンド	内容
keelson deploy	カレントディレクトリのアプリをデプロイ。完了まで待つかどうかは下の表を参照
keelson deploy --new [--region <region>] [--secrets-from-env-file <path>]	アプリを作成して初回デプロイ。env ファイルの値をシークレットとして登録し、そのファイルはアーカイブから除外
keelson deploy --check [--json]	アップロードせず、設定の検証とアーカイブ内容(除外ファイル、秘匿値らしきファイル)を表示。ローカル検証なので、プランの上限に当たるかどうかまでは分からない
keelson deploy --ndjson --yes	スクリプト向け。進捗を 1 行に 1 つの JSON オブジェクトとして出力する
keelson status [deploy_id] [--wait] [--max-wait <duration>]	指定したデプロイの状態を表示する。ID を省略するとアプリの最新デプロイが対象になる
keelson diagnose [deploy_id]	ID を指定するとデプロイを診断する。省略すると稼働中アプリを診断する。起動失敗時は保存済みのアプリの起動ログも表示する
keelson deploys list [--limit <n>] [--offset <n>]	デプロイ履歴
keelson deploys download <deploy_id> [-o <path>]	そのデプロイに使ったソースアーカイブをダウンロード(保持期間内のみ)
keelson rollback [deploy_id] [--yes]	前の成功デプロイ、または指定した成功デプロイに戻す

deploy が完了を待つかどうか

実行のしかた	挙動
対話端末で keelson deploy	完了まで待つ(既定 30 分。--watch-timeout で変更)
パイプや CI など非対話で keelson deploy --yes	受け付けた時点で返る。待つなら --yes --watch
--json	受け付けた時点で返る。--watch と併用不可
--ndjson	完了まで待つ(--no-watch と併用不可)
--no-watch	対話端末でも受け付けた時点で返る

通常の出力モードでは、非対話実行に --yes が必要です。省略すると confirmation_input_unavailable エラーになります。--json / --ndjson / --quiet を指定した場合は、確認を求めずに実行します。

待ち時間の上限を超えても監視をやめるだけで、サーバー側のデプロイは止まりません。status --wait で続きを確認できます。

status で完了を確認する

status --wait の待機上限は既定 50 秒です。--max-wait <duration> で変更できます。上限に達すると、その時点で取得できた最後の状態を返します。デプロイが未完了でも、状態の取得に成功すれば終了コードは 0 です。

スクリプトでは、終了コードだけでデプロイの成否を判断せず、--json の terminal と status を確認してください。terminal: false なら未完了です。成功の確認には terminal: true かつ status: "completed" が必要です。

最新デプロイが失敗していても、前の成功リビジョンが動いている場合があります。現在配信しているアプリの状態は keelson app info で確認してください。

rollback の注意点

戻せる対象は、コンテナイメージを持つ成功デプロイです。静的サイトは、以前のソースを再デプロイして戻します。ロールバックではビルドを省略しますが、db.migrate は再実行されます。

rollback は受け付けた時点で戻ります。返されたデプロイ ID を keelson status <deploy_id> --wait --json に渡し、terminal と status を確認してください。--json または非対話実行では --yes が必要です。

NDJSON の読み方

NDJSON では、stage と status などを持つ進捗行が流れます。例えばヘルスチェック中は stage が health_check、status が progress になります。進捗行の status だけでデプロイ全体の成否を判定しないでください。

• 監視まで進んだ場合、最後に result を持つ行が出ます。値は success または failed です。
• 監視開始前に失敗した場合は、error を持つ行が出て、result 行は出ません。設定の不備などではエラー行だけですが、シークレットの登録やアーカイブのアップロード後に失敗すると、それ以前の進捗行も出ています。
• プロセスの終了コードも確認してください。0 以外は CLI の処理が失敗したことを示します。監視のタイムアウトでも失敗扱いになりますが、サーバー側のデプロイは続いている場合があります。

確認

コマンド	内容
keelson app curl <path> [-i] [--method <method>] [--data <body|@file>] [--form <name=value|name=@file>] [--header <name:value>]	認証付きでアプリにリクエストを送る。デプロイ後の確認
keelson preview [--ttl <duration>] [--allow-writes] [--json]	アプリへの認証付きアクセスに使う、有効期限付きのトークンを発行する
keelson app info / start / stop / restart	アプリの情報表示、起動、サスペンド、再起動。restart は完了まで待つ(--no-watch で受付後に返る)

app curl で --data を指定するときは、--method に POST / PUT / PATCH / DELETE のいずれかも指定してください。--form を指定し、--method を省略した場合は POST になります。複数のフォーム項目やヘッダーを指定する場合は、--form や --header を繰り返します。

レスポンス本文は標準出力に出ます。-i を付けると、HTTP ステータスとレスポンスヘッダーも標準エラー出力に表示します。GET / HEAD の一時的な失敗は既定で最大 2 回再試行し、--retry 0 で無効にできます。

preview と app curl は、現在配信しているデプロイを行った本人以外が実行すると、読み取りだけでもブラウザでの承認が必要です。この承認では、ブラウザで承認しただけではトークンの発行やリクエストの送信は行われません。承認後 30 分以内に、同じコマンドへ --confirmation <id> を付けて再実行してください。下記の「ブラウザでの承認が必要な操作」とは手順が異なります。

ログ

コマンド	内容
keelson logs app <slug> [--mode live|history] [--severity <level>] [--previous] [--limit <n>] [--since <duration>]	（--previous は現行ランタイムでは未対応で 422 を返す。クラッシュした旧インスタンスの出力は通常のログに含まれる）アプリの標準出力・標準エラー
keelson logs cron <slug> [--severity <level>] [--limit <n>] [--since <duration>]	cron の実行ログ
keelson logs access [--limit <n>] [--since <duration>]	アクセスログ
keelson logs deploy [deploy_id] [--limit <n>] [--since <duration>]	デプロイの進行ログと保存済みの失敗詳細。アプリが起動中に終了した場合は、アプリの起動ログも表示。成功時のビルド出力は保存されないため、表示できるログがなければ理由を表示

--since には 1h や 1d12h のような期間を指定します。指定できる範囲は 1 秒〜30 日です。

--json は、ログ配列などを含む 1 つの JSON オブジェクトを出力します。ログの格納先はコマンドによって異なります。

コマンド	JSON 内のログ
logs app / logs cron	entries 配列。各要素は時刻、重大度（severity）、メッセージなどを持つオブジェクト
logs access	entries 配列。各要素は時刻、HTTP ステータス、パスなどを持つオブジェクト
logs deploy	logs 配列に進行ログのオブジェクトを格納。failure_logs と startup_logs は文字列の配列

シークレット

値はコマンド引数ではなく標準入力または env ファイルから渡します。

コマンド	内容
keelson secrets list	設定済みの名前と更新日時。値は表示しない
echo -n "<value>" | keelson secrets set <KEY> [--apply]	1 件設定。--apply で再デプロイまで要求(受付後に返る)
keelson secrets set --from-env-file <path> [--apply]	env ファイルからまとめて設定。key ごとに保存するので、途中で失敗すると一部だけ保存された状態になる(エラーに保存済みの key が入る)
keelson secrets unset <KEY>	削除

シークレットは次のデプロイ(または --apply)で反映されます。

アプリ管理

コマンド	内容
keelson apps list [--workspace <slug>] [--query <text>] [--exact]	アプリ一覧。--workspace を省略すると所属する全ワークスペースを対象にする。--json の結果は、指定時は apps 配列、省略時は workspaces 配列に格納される
keelson apps duplicate <slug> --name <new> [--copy-secrets] [--enable-schedule]	アプリを複製。cron のスケジュールは既定で無効のまま複製
keelson apps rename <new_slug>	公開 URL の slug を変える。旧 URL は 410 を返し、自動リダイレクトはされない。反映まで時間がかかる
keelson apps delete [slug]	アプリを削除。ブラウザでの承認が必要
keelson quotas	プランの上限と使用量

apps rename の実行後は、手元の keelson.yaml の slug も新しい値に変更してください。

複製で引き継がれるもの

複製は、元アプリの最新の成功したデプロイを基に作られます。複製先は、独自の URL とデプロイ履歴を持つ別のアプリです。

項目	複製時の扱い
アプリのコード	最新の成功したデプロイから複製する
設定 (keelson.yaml)	複製先の新しいアプリ識別情報を除いて複製する
定期実行ジョブの定義	複製するが、複製先のデプロイが成功した後に停止状態で作られる。--enable-schedule を付けると有効になるが、設定で enabled: false を明示したジョブは停止状態のまま
アプリ単位のシークレット	既定では複製しない。--copy-secrets を付けると複製する
ワークスペース単位のシークレット	複製しないが、ワークスペース内の全アプリに渡されるため複製先でもそのまま利用できる
プラットフォーム管理の資格情報	複製先用の新しい資格情報を発行する
Keelson 管理 DB の中身	複製せず、新しい空の DB を作る。CLI には DB の中身を複製するオプションはない
デプロイ履歴	複製しない。元アプリの最新の成功したデプロイを基に、複製先の新しいデプロイを作る

定期実行ジョブ

コマンド	内容
keelson crons list [--include-disabled]	ジョブ一覧
keelson crons trigger <name> [--wait]	今すぐ実行。--wait で実行結果まで待つ
keelson crons enable <name> / disable <name>	有効化 / 無効化
keelson crons runs list [--cron <name>] [--limit <n>] [--offset <n>]	実行履歴
keelson dev cron run <name> [--file <path>] [--dir <path>]	keelson.yaml の cron をローカルで 1 回実行する
keelson dev task run <name> [--payload <JSON> | --payload -] [--file <path>] [--dir <path>] [--json]	keelson.yaml のバックグラウンドタスクをローカルで 1 回、同期で実行する（再試行なし）。--payload はタスクの payload を JSON で渡す（- で標準入力から読む。省略時は null）。--json では標準出力に結果の JSON を 1 つだけ出す。手元で enqueue したときに SDK が使うコマンド。バックグラウンドタスクを参照

ローカル開発

コマンド	内容
keelson dev serve [--port <n>] [--users <file>] [--as <id>] -- <command...>	<command> でアプリのサーバーを起動し、その手前で Keelson と同じユーザー情報のヘッダーを付けて中継する。利用者は切り替えページ（/__keelson/dev）や X-Keelson-Dev-As ヘッダーで切り替える。--port は待ち受けるポート（既定 5173）、--users は名簿ファイル（既定 ./.keelson/dev-users.json、無ければ組み込みの 4 人）、--as は起動時の利用者。アプリには空いているポートを PORT で渡し、<command> 中の {port} も置き換える。デプロイ先の環境では起動しない。ローカルで動かすを参照
keelson dev serve --check	何も起動せずに終了コード 0 で終わる。この CLI が dev serve に対応しているかの判定に使う

データベース

コマンド	内容
keelson db apply [file.sql]	Managed SQLite に SQL を実行(省略か - で標準入力)。既にテーブルなどがある DB へはブラウザでの承認が必要。テーブル・インデックス・ビュー・トリガーを 1 つも持たない初回の DB には承認なしで適用される
keelson snapshots list	復元ポイントと、実行中・直近のエクスポートの一覧。エクスポートは成功・失敗したものも含む
keelson snapshots create	手動スナップショット
keelson snapshots download <id> [-o <file>]	バックアップのダウンロード。-o を省くとダウンロード URL を表示するだけでファイルは書かない
keelson snapshots export --at <RFC3339>	任意時点(PITR)のエクスポートを作成。完了後に download で取得
keelson snapshots restore <id>	復元。ブラウザでの承認が必要。72 時間以内なら取り消し可
keelson snapshots restore-status	最新の復元の進捗と結果を確認
keelson db revoke-tokens [app] [--yes]	DB の認証トークンを失効させる(破壊的)。端末内で確認を求める。非対話端末では --yes。失効後、新しいリビジョンに切り替わるまで DB は一時的に使えない
keelson db recover [app] / credential-status [app]	認証情報の復旧と状態

アクセス制御

コマンド	内容
keelson groups list	グループ一覧
keelson groups create <key> [--name <text>] [--description <text>] [--if-not-exists]	カスタムグループを作成
keelson groups members list <key>	グループのメンバー
keelson groups members add|remove <key> <email>...	既存メンバーの所属を変更(招待ではない)
keelson access show --app <slug>	アプリの閲覧 / 管理グループ
keelson access set --app <slug> [--view <key>]... [--manage <key>]... [--allow-self-lockout]	閲覧・管理権限を持つグループを設定する

access set は、指定した種類の権限をすべて置き換えます。--view だけを指定した場合、管理権限は変更しません。閲覧権限を空にするには --view none を指定します。管理権限は空にできません。

複数のグループを指定する場合は、フラグを繰り返してください。例えば、閲覧グループを sales と engineering に変更するには次のように実行します。

keelson access set --app my-app --view sales --view engineering

自分の管理権限が失われる変更には --allow-self-lockout が必要です。

外部連携

コマンド	内容
keelson apps tokens create --app <slug> --name <name> --scope <scope> [--scope <scope>]... [--allowed-ip <cidr>]...	アプリトークンを発行(1 回だけ表示)。--app は省略できない
keelson apps tokens list	一覧(メタデータのみ)
keelson apps tokens rotate --app <slug> --token-id <id>	ローテーション。旧トークンは猶予付きで失効
keelson apps tokens delete <token_id>	失効
keelson apps directory enable	Directory API のトークンを発行し、KEELSON_DIRECTORY_TOKEN として登録(要再デプロイ)
keelson domains list	カスタムドメインの一覧と状態
keelson domains add|verify|remove <hostname> [--yes]	カスタムドメインの追加・検証・削除(Team)。remove は非対話端末では --yes

--scope に指定できる値は次のとおりです。受信用と Directory 用は同じトークンに混在できません。

scope	用途
api	外部システムからアプリの /api/external/... を呼ぶ
webhook	外部サービスからアプリの Webhook を受ける
directory:members:read / directory:identity:read / directory:groups:read / directory:group-members:read	アプリから Directory API を呼ぶ(通常は apps directory enable が付与する)

フィードバック

keelson feedback --app <slug> [--deploy <id>] < feedback.json は、CLI と Skill の使い勝手についてのフィードバックを送ります。標準入力に JSON オブジェクトを 1 つ渡します。定義されていないフィールドは拒否されます。

フィールド	内容
verdict（必須）	score と summary を持つオブジェクト。score は 1〜10 の整数、summary は 1〜1,000 文字の総評。両方とも必須
friction	困った点を記録するオブジェクトの配列。最大 20 件。各要素のフィールドは下記を参照
yaml_confusions / error_message_reviews / wanted_commands / kept_good	それぞれ文字列の配列。最大 20 件
skill_gaps / verification_method	文字列

friction の各要素には、次の 6 フィールドがすべて必要です。

フィールド	型・内容
step	文字列。困った場面や作業の段階
command	文字列。実行したコマンド
output_quote	文字列。表示されたメッセージの引用
expected	文字列。期待していた動作
lost_minutes	0〜1,440 の整数。対処にかかった分数
recovered	真偽値。解決できた場合は true、未解決なら false

例えば、次の内容を feedback.json に保存して送信できます。内容は実際の体験に合わせて書き換えてください。

{
  "verdict": {
    "score": 8,
    "summary": "デプロイできたが、非対話実行時の確認方法で迷った。"
  },
  "friction": [
    {
      "step": "CI からのデプロイ",
      "command": "keelson deploy",
      "output_quote": "The confirmation response could not be read from standard input.",
      "expected": "非対話実行に必要なフラグを事前に知りたかった。",
      "lost_minutes": 3,
      "recovered": true
    }
  ]
}

コマンドの別名

次の旧名も受け付けます。撤去時期は未定ですが、正式な名前のほうを使ってください。別名は --help に独立したコマンドとしては出ません。

別名	正式な名前
keelson backups list / trigger / download / restore	keelson snapshots list / create / download / restore
keelson tokens list / delete	keelson apps tokens list / delete
keelson skill install [--global] [--codex] [--yes]	keelson install-agent <claude-code|codex|cursor> [--global] [--yes]
keelson tenants list	keelson workspaces list
keelson db rotate-credentials	keelson db revoke-tokens
--tenant	--workspace

ブラウザでの承認が必要な操作

アプリの削除、既存スキーマがある DB への SQL の実行、スナップショットからの復元は、CLI だけでは完了しません。コマンドは承認用 URL を表示し(confirmation_required)、ブラウザで承認すると操作がサーバー側で実行されます。コマンドを再実行する必要はありません。承認の期限は 15 分です。

URL を表示したあとの挙動は実行のしかたで変わります。

• 対話端末: 既定で承認と実行の完了まで待つ。--wait=false で待たずに返る
• --json または非対話端末: 既定で待たずに返る。--wait を付ければ待つ

preview / app curl の承認は、これとは別の再実行方式です(「確認」の節を参照)。rollback / db revoke-tokens / domains remove はブラウザ承認ではなく端末内の確認で、非対話端末では --yes が要ります。

環境変数

変数	内容
KEELSON_TOKEN	ログインの代わりに使うトークン(CI 向け)。保存済みログインより優先。設定してあると空文字でもエラーになる
KEELSON_NO_UPDATE_CHECK=1 / KEELSON_NO_SKILL_SYNC=1	更新確認 / Skill の自動更新を止める(KEELSON_NO_SKILL_SYNC は空でなければ 0 でも止まる)
KEELSON_NO_TELEMETRY=1	CLI の利用状況データを止める
KEELSON_CONFIG_DIR	設定ファイル(credentials.json / config.json)を置くディレクトリ
KEELSON_API_BASE_URL / APP_DOMAIN_BASE	接続先 API とアプリドメインの上書き(通常は不要)