stackbone-cli

Stackbone CLI スキル

このスキルでは、stackbone CLI の操作方法、各コマンドに共通するルール、実行するループについて説明します。フラグ一覧は含まれていません。各フラグ、出力形式、終了コードは、コマンドごとのドキュメントに記載されています。

情報の参照先

ドキュメントは MCP を介して stackbone-docs サーバー（https://docs.stackbone.ai/mcp、公開、ツール search_docs、get_doc、list_docs）から取得できます。stackbone docs を実行すると接続情報が表示されます。

• セッションは list_docs（area cli）から開始してください。 セクションごとに、すべての CLI ページと1行の説明が返されます。以下のページの探し方では、タスクに必要なページを説明しています。一覧からそのパスを取得し、get_doc で読み込んでください。パスを記憶に頼って入力しないでください。ページは移動しても、タイトルは変わりません。
• このセッションで確認していないフラグを使ってコマンドを実行する前に、そのコマンドのページを読んでください。
• どのコマンドを使えばよいかわからない場合は、質問を平易な言葉で search_docs に渡し、area: "cli" を指定してください。
• インストール済みバージョンについては、stackbone <command> --help が正しい情報源です。ドキュメントとバイナリの内容が異なる場合は、バイナリを優先してください。

セッションで stackbone-docs ツールを使えませんか？ https://docs.stackbone.ai/llms.txt を取得してください。同じ一覧がページごとに1行で記載され、タイトル、説明、raw Markdown へのリンクが含まれています。タイトルでページを選び、そのリンクを取得してください。https://docs.stackbone.ai/llms-full.txt にはすべてのページが1つのファイルにまとめられています（約700 KB）。

CLI の呼び出し方

• バイナリは stackbone です（インストールせずに pnpm dlx @stackbone/cli <command> を実行するか、pnpm add -g @stackbone/cli でグローバルにインストールします）。stackbone --help が失敗する場合、CLI はインストールされていません。
• 利用する側では、すべての呼び出しに --json を渡してください。 stdout に { "schema_version": 1, … } の1行が出力されるか、stderr に { "error": { "code", "message", "suggestion" } } が出力されます。
• 破壊的な操作を行う動詞（retry、cancel、remove、rollback、approve、reject）には --yes を渡してください。 指定しない場合、ネットワーク呼び出しを行う前に動詞は終了コード 5 で終了します。
• --json、--yes、CI=1 はいずれもプロンプトを無効にします。 値の入力、選択、確認を求めるはずのコマンドは、停止せずにエラーになります。そのため、必須の値はすべてフラグとして渡してください。
• 終了コードに応じて処理を分岐してください。 0 は成功、1 は一般エラー、2 は未認証（stackbone login）、3 はプロジェクトがない、または stackbone dev が実行されていない、4 は見つからない、または登録済みのデプロイがない、5 は権限エラーです。エンベロープ内の error.code には、より詳細な情報（dev_not_running、runtime_not_configured など）が含まれます。
• コマンドが失敗した場合は、--json を付けて再実行し、error.suggestion を確認してください。次に試すべきコマンドが記載されています。その後、CLI 自体のログを stderr に出力するには STACKBONE_LOG_LEVEL=debug を指定し、dev の起動段階で停止する場合は --verbose を指定してください。

セッションの開始

ほかのことを行う前に次のコマンドを実行し、終了コードに応じて処理してください。

stackbone whoami --json     # exit 2 → stackbone login (device flow; --no-browser when headless)
stackbone metadata --json   # auth + linked project + agents in one payload; exit 3 → init or link

一連の作業

新しいワークスペース。 stackbone login → stackbone init <dir> [--with agent|workflow|workflow-agent] [--name <ws>] → cd <dir> → stackbone dev。init はワークスペースを組織にリンクし、.stackbone/project.json を書き込むため、サインイン済みのセッションが必要です。ワークスペースの依存関係は自動でインストールされるため、自分でインストール手順を追加しないでください。インストールをスキップまたは復旧する必要がある場合は、このコマンドのページを参照してください。TTY がある場合は、セットアップするコーディングエージェント（スキルとドキュメント用 MCP サーバー）を尋ねます。非対話型の実行では、--agents claude-code,cursor,… を渡さない限り、何もセットアップされません。

ワークスペースを拡張する。 stackbone add agent <name> / add workflow <name> [--calls <agent>] / add workflow-agent <name>。オフラインでログインも不要です。新しいファイルのみを書き込み、既存の TypeScript は編集しません。名前が重複すると、--force を指定しない限り失敗します。ワークスペース内で実行する必要があります（それ以外の場合は終了コード 3）。その後、stackbone スキルを使ってコードを記述します。

開発ループ。 stackbone dev は Postgres、Redis、MinIO を起動し、ホットリロード付きでワークスペースを http://127.0.0.1:4242 でコンパイルして提供するとともに、クラウドの Studio からアクセスできるようトンネルを開きます。新しいマシンでの初回実行は、モデルプロバイダーが設定されるまで停止します（Studio へのリンクが表示されます。または、起動前に MODEL_PROVIDER_BASE_URL と MODEL_PROVIDER_API_KEY をエクスポートしてください）。その後：

stackbone workflows list --json
stackbone workflows start <name> --input '{"…"}' --json   # validates against the declared schema → { runId }
stackbone runs get <runId> --json
stackbone logs tail --run <runId> --json                   # the per-step frames; --follow for a live run

Studio の Playground からエージェントとチャットするか、"model": "<agent-name>" と空ではない任意の bearer を指定して POST http://127.0.0.1:4242/openai/v1/chat/completions を実行します（Getting started（CLI › Guides））。

スキーマの変更。 src/schema.ts を編集 → stackbone db migrate create <name> → .stackbone/migrations/ 内に生成された SQL を確認 → stackbone db migrate up → stackbone db migrate status。適用済みのマイグレーションは編集せず、新しいものを作成してください。マイグレーションファイルに BEGIN / COMMIT を含めないでください。

インストール環境を運用する。 --agent を指定しない動詞は、ローカル開発用インストールを対象とするため、stackbone dev の実行が必要です（実行されていない場合は dev_not_running、終了コード 3）。stackbone agents list --json でインストール ID を確認できます。デプロイ済みのインストールを対象にするには、呼び出しごとに --agent <id> を渡します。承認：stackbone hitl list --status pending --json → stackbone hitl approve|reject <id> --yes --json。

デプロイする。 公開コマンドはありません。stackbone package はデプロイ用フォルダー（コンパイル済みワークスペース、Dockerfile、compose、.env、README）を書き込み、そのフォルダーを使って誰かが docker compose up -d を実行します。stackbone build は、自分で用意したイメージ用のバンドルのみを書き込みます。その後、実行中のボックスを登録します：stackbone link --agent <slug> --installation <id> --url <public-url> --secret <hmac-secret> --tag <image-tag>（タグはバージョンです。デプロイのたびに link を再実行してください）。1 つのボックスが応答するのは 1 つのインストールのみです。そのため、--installation には stackbone agents list --json で確認できる、そのエージェントの cloud 行の ID を指定します。link はインストールを作成しないため、先にエージェントをインストールしてください。初めて link を実行する前に、link（CLI › Reference）を参照してください。シークレットの入手先が説明されています。

デプロイ後は、3 つのスキルが役割を引き継ぎます。 接続されていないボックスは何にも到達できず、何も測定できません。また、それぞれのスキルは、CLI からアクセスできないサイドバーのグループを 1 つずつ担当します。stackbone-integrations はプロバイダーを接続し、エージェントが自動で受信できるようトリガーを有効にし、エージェントの出力をどこかへ送信します。stackbone-guardrails は実行中のエージェントに制限を設けます。ターンをブロックしたり、データをマスクしたり、人による確認のために保留したりできます。stackbone-evals は、手動で Playground を試す作業を、CI で実行できるスイートに変えます。

CI／ヘッドレス環境。 ログインはデバイスフローのみです（トークン用の環境変数はありません）。ブラウザーが使える環境で stackbone login を一度実行し、~/.stackbone/credentials.json（chmod 600）を CI に持ち込んでください。その後はすべてのコマンドに --json を指定し、破壊的な動詞には --yes を指定します。コーディングエージェントのセットアップが必要な場合は、init／link に --agents <list> を指定してください。

どこでも適用されるルール

• .stackbone/ は絶対にコミットしないでください（init によって Git の除外対象になります）。このディレクトリがないクローンで stackbone dev を実行すると、このプロジェクトがどのエージェントなのかを尋ねた後、ファイルを書き込みます。link では代用できません。デプロイ済みのボックス（--installation --url --secret --tag）が必要で、インストール ID を記録するプロジェクトファイルがない場合は、処理を拒否します。
• ページネーション付きのリストでは --limit と --cursor を指定し、items と nextCursor が返されます。nextCursor を渡して次に進んでください。logs tail は代わりにストリーミングします。
• シークレットが出力されることはありません。secrets list は値をマスクし、値を表示するコマンドもありません。CLI から値を読み取ろうとしないでください。
• db query では、読み取り専用の SELECT を 1 つだけ実行できます。スキーマの変更には db migrate create を使用してください。RAG スキーマはプラットフォームによってプロビジョニングされるため、手動でマイグレーションしないでください。
• init は --starter や --template を受け付けません。指定すると、移行を促すメッセージとともにゼロ以外の終了コードで終了します。各パーツのテンプレートは add で指定します（stackbone add workflow <name> --template <t>）。
• 古い資料で見かける可能性のある廃止済みコマンド：publish、openrouter、connectors。これらは存在しません。代わりに、build / package と link、Gateway（ホーム › 機能）、Studio のインテグレーションページを使用してください。
• 対話型プロンプトは、人が ! stackbone … と入力する場合を想定して保護されています。コマンドを実行する側である場合、デフォルトで --json --yes を使用します。

ページの見つけ方

• 1 つのコマンドのフラグ、動詞、出力形式、または終了コード：CLI › リファレンスの、コマンド名が付いたページ（login / logout は「サインインとサインアウト」、whoami / current / list / organization use / metadata は「アカウントと組織」を参照）。
• すべてのコマンドに共通するルール（動詞が対象を選ぶ方法、JSON エンベロープ、ページネーション、--yes の必須条件、終了コード）：CLI › リファレンスの「コマンドの規約」を参照してください。グローバルフラグ、環境変数、ディスク上の状態については「設定リファレンス」を参照してください。
• dev の起動が停止する場合、またはコマンドが対象への操作を拒否する場合：CLI › ガイドの「トラブルシューティング」を参照してください（または stackbone-debug スキルを使用してください）。
• その他すべて（HTTP ワイヤ形式、リリース、コーディングエージェントの手動セットアップ）：質問を平易な言葉で入力し、領域に cli を指定して search_docs を実行してください。デプロイとセットアップのページについては、領域に home を指定してください。

その他のスキル

• stackbone：ワークスペース内のコード（defineDeepAgent、'use workflow'、環境に自動的に存在する stackbone クライアント）。
• stackbone-debug：エラー、失敗または停止した実行、保留中の承認の原因を特定します。
• stackbone-coder：1 行のアイデアからインタビューを通じて、新しいパーツの作成を始めます。