CLI コマンド

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

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

共通フラグ

対応するコマンドで使えるフラグです。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>	対象ワークスペース。--workspace → keelson.yaml の workspace → 前回使った既定 → 所属が 1 つならそれ、の順で決まる。複数に属していて前段で決まらないときだけ必要。同名のワークスペースがあるときは slug か ID で指定
--json	結果を JSON で出力。スクリプトやエージェントから使うときに
--quiet	説明や進捗を抑える。出力の形はコマンドごとに違う(secrets set は key ごとに 1 行、deploys list は ID ごとに 1 行、deploy --check は成功時に何も出さない)
--timeout <duration> / --retry <n>	API 呼び出しのタイムアウト(既定 15 秒)と再試行回数(既定 0)
--no-browser	ブラウザを開かず URL を表示する(login、承認が必要な操作)

--json でコマンドが失敗すると、標準出力に {"error":{"code","message","hint","retryable"}} が返ります。hint に従ってください。retryable が false なら同じコマンドを繰り返しても結果は変わりません。

旧名の --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 feedback --help

デプロイ

コマンド	内容
keelson deploy	カレントディレクトリのアプリをデプロイ。完了まで待つかどうかは下の表を参照
keelson deploy --new [--region <region>] [--secrets-from-env-file <path>]	アプリを作成して初回デプロイ。env ファイルの値をシークレットとして登録し、そのファイルはアーカイブから除外
keelson deploy --check [--json]	アップロードせず、設定の検証とアーカイブ内容(除外ファイル、秘匿値らしきファイル)を表示。ローカル検証なので、プランの上限に当たるかどうかまでは分からない
keelson deploy --ndjson --yes	スクリプト向け。進捗を 1 行 1 JSON で流し、完了時に {"result":"success"|"failed"}
keelson status [deploy_id] [--wait] [--max-wait <duration>]	指定したデプロイ(省略時はアプリの最新デプロイ)の状態。最新デプロイが失敗していても前の成功リビジョンが動いていることはあるので、いま動いているものの状態は app info で見る
keelson diagnose [deploy_id]	失敗したデプロイの診断(id あり。起動失敗時は保存済みのアプリの起動ログを含む)/ 稼働中アプリの診断(id なし)
keelson deploys list [--limit] [--offset]	デプロイ履歴
keelson deploys download <deploy_id> [-o <path>]	そのデプロイに使ったソースアーカイブをダウンロード(保持期間内のみ)
keelson rollback [deploy_id] [--yes]	前の成功デプロイ(または指定したデプロイ)に戻す。対象はコンテナイメージを持つ成功デプロイだけで、静的サイトは以前のソースを再デプロイして戻す。ビルドせずに戻すが db.migrate は再実行される。受け付けた時点で返るので、返ってきたデプロイ ID を status --wait で確認する。--json や非対話端末では --yes が必要

deploy が完了を待つかどうか

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

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

NDJSON の読み方

段階の実行中は {"stage":"health_check","status":"progress",…} のような行が流れます。進捗行の status で成否を判定しないでください。判定は次の 3 つで行います。

• 監視まで進んだ場合、最後に result を持つ行が出る
• keelson.yaml が無い、設定が不正など、監視に入る前の失敗は {"error":{…}} の 1 行だけで、result 行は出ない
• プロセスの終了コード。0 以外は失敗

確認

コマンド	内容
keelson app curl <path> [-i] [--method] [--data] [--form] [--header]	認証済みでアプリにリクエストを送る。GET / HEAD の一時的な失敗は既定で最大 2 回再試行(--retry 0 で止める)。--data を付けるときは --method も指定する。--form は省略時 POST。-i の status / header は標準エラー、body は標準出力。デプロイ後の確認
keelson preview [--ttl] [--allow-writes] [--json]	認証済みの短命な券を発行する
keelson app info / start / stop / restart	アプリの情報表示、起動、サスペンド、再起動。restart は完了まで待つ(--no-watch で受付後に返る)

preview と app curl は、いま動いているデプロイを行った本人以外が実行すると、読み取りだけでもブラウザでの承認が要ります。この承認は下の「ブラウザでの承認が必要な操作」とは別の流れで、承認しても操作は実行されません。承認後に同じコマンドへ --confirmation <id> を付けて再実行します(期限 30 分)。

ログ

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

--since は 1h や 1d12h のような期間(1 秒〜30 日)です。--json の各行は文字列ではなく、時刻や severity を持つオブジェクトです。

シークレット

値はコマンド引数ではなく標準入力または 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 を省略すると所属する全ワークスペースを対象にする(keelson.yaml や前回の既定では絞らない)。--json の形は --workspace あり({apps: […]})となし({workspaces: […]})で違う
keelson apps duplicate <slug> --name <new> [--copy-secrets] [--enable-schedule]	アプリを複製。cron のスケジュールは既定で無効のまま複製
keelson apps rename <new_slug>	公開 URL の slug を変える。旧 URL は 410 を返し、自動リダイレクトはされない。反映まで時間がかかる。手元の keelson.yaml の slug も書き換える
keelson apps delete [slug]	アプリを削除。ブラウザでの承認が必要
keelson quotas	プランの上限と使用量

定期実行ジョブ

コマンド	内容
keelson crons list [--include-disabled]	ジョブ一覧
keelson crons trigger <name> [--wait]	今すぐ実行。--wait で実行結果まで待つ
keelson crons enable <name> / disable <name>	有効化 / 無効化
keelson crons runs list [--cron <name>] [--limit] [--offset]	実行履歴
keelson dev cron run <name> [--file] [--dir]	keelson.yaml の cron をローカルで 1 回実行(スケジューラではない)

データベース

コマンド	内容
keelson db apply [file.sql]	Managed SQLite に SQL を実行(省略か - で標準入力)。既にテーブルなどがある DB へはブラウザでの承認が必要。テーブル・インデックス・ビュー・トリガーを 1 つも持たない初回の DB には承認なしで適用される
keelson snapshots list	復元ポイントと実行中の取り出し（exports）の一覧
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] [--description] [--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>...|--view none] [--manage <key>...] [--allow-self-lockout]	権限を設定。指定した側は丸ごと置き換え、指定しなかった側は保持。管理は空にできない。自分の権限が失われる変更は --allow-self-lockout が要る

外部連携

コマンド	内容
keelson apps tokens create --app <slug> --name <n> --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
keelson dev email --to ... --subject ...	ローカルのアプリに受信メールをテスト送信

--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 が付与する)

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

アプリの削除、既存スキーマがある 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 とアプリドメインの上書き(通常は不要)