cargo-workspace-management

Cargo CLI — ワークスペース

ワークスペースの管理：ユーザー、API トークン、フォルダー、ロール、ワークスペースレベルのファイルの管理、およびワークスペース管理へのレポートの送信。

JSON レスポンスの完全な構造については、references/response-shapes.md を参照してください。 よくあるエラーとその修正方法については、references/troubleshooting.md を参照してください。 ユーザーの招待と管理の例については、references/examples/users.md を参照してください。 API トークンの作成とローテーションの例については、references/examples/tokens.md を参照してください。 リソースをフォルダーに整理する例については、references/examples/folders.md を参照してください。 ワークスペース管理レポートの送信例については、references/examples/reports.md を参照してください。 セッションの追跡については、references/examples/sessions.md を参照してください。Cargo インストーラーは Claude Code の SessionStart + Stop + SessionEnd フックを自動的にセットアップします。

初期設定

すでにサインイン済みで（cargo-ai whoami がワークスペースを返す場合）、次のセクションに進んでください。

npm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`
cargo-ai login --email [email protected]  # emailed code, no browser; creates the account on first use
                                        # alternatives: --oauth (browser) · --token <api-token> (CI)
cargo-ai whoami                         # confirm the active workspace before any write

すべてのコマンドは JSON を stdout に出力します。失敗時はゼロ以外で終了し、{"error": "...", "status": ..., "body": ...} を stderr に出力します。実行またはバッチを作成するコマンドはすべて非同期です。--wait-until-finished を渡すか、対応する get をポーリングしてください。管理者のみ： ユーザー、ロール、envVar の書き込みには、ワークスペース管理の書き込み（管理者）アクセス権が必要です。すべてのユーザーは自身のトークンを作成、一覧表示、削除できます。管理者アクセス権がある場合は、サービスユーザーのトークンも操作できます。フォルダーへの書き込みにはフォルダーの書き込み権限が必要ですが、report create と session upsert には権限は不要です。スキルバンドル全体をインストールすると、../cargo/references/prerequisites.md に CLI のバージョン固定、トークンのスコープ、管理者限定の機能が追加されます。

まずリソースを確認する

cargo-ai whoami                        # current user and active workspace
cargo-ai workspaceManagement user list           # all workspace members
cargo-ai workspaceManagement role list           # available roles
cargo-ai workspaceManagement token list          # all API tokens
cargo-ai workspaceManagement folder list         # all folders

クイックリファレンス

cargo-ai whoami
cargo-ai workspaceManagement user list
cargo-ai workspaceManagement user create --email <email> --role-slug <slug>
cargo-ai workspaceManagement role create --name <name> --slug <slug> --permissions '<json>'
cargo-ai workspaceManagement workspaces list
cargo-ai workspaceManagement token list
cargo-ai workspaceManagement token create --name <name>
cargo-ai workspaceManagement token remove <token-uuid>
cargo-ai workspaceManagement folder list
cargo-ai workspaceManagement folder create --name <name> --emoji-slug <slug> --kind <kind>
cargo-ai workspaceManagement report create --title <title> --description <description>
cargo-ai workspaceManagement session upsert --session-id <id> --title <title> --summary <summary> [--finished]
cargo-ai workspaceManagement envVar list
cargo-ai workspaceManagement envVar create --key <KEY> [--value <v>] [--secret]

現在のユーザーとワークスペース

# Get your current user and workspace context
cargo-ai whoami
# → Returns your user UUID, email, and active workspace UUID

# Workspaces this user can reach, and the one selected now
cargo-ai workspaceManagement workspaces list
cargo-ai workspaceManagement workspaces get-current      # honors CARGO_WORKSPACE_UUID

# Create another workspace (it is not selected for you — sign in to it or set CARGO_WORKSPACE_UUID)
cargo-ai workspaceManagement workspaces create --name "Acme GTM"

# Update the selected workspace — pass the literal "null" to clear a nullable field
cargo-ai workspaceManagement workspaces update --name "Acme GTM (prod)"
cargo-ai workspaceManagement workspaces update --allowed-email-domains acme.com,acme.io
cargo-ai workspaceManagement workspaces update --default-role-uuid <role-uuid>   # role new members get

workspaces update では、--openai-api-key、--logo-base64、--metadata、--syncs、および Chrome 拡張機能のエージェントフィールドも指定できます。これは管理者による書き込み操作であり、--openai-api-key はシークレットです。インラインではなく、環境変数から渡してください。

ユーザー

# List all workspace members
cargo-ai workspaceManagement user list

# Invite a new user (requires their email and a role)
cargo-ai workspaceManagement user create \
  --email [email protected] \
  --role-slug <role-slug>

# Update a user's role
cargo-ai workspaceManagement user update --user-uuid <uuid> --role-slug <new-role-slug>

# Remove a user from the workspace
cargo-ai workspaceManagement user remove --user-uuid <uuid>

# Grant one user access to one resource (a workflow, folder, agent, app, …)
cargo-ai workspaceManagement user upsert-permission \
  --user-uuids <uuid> --action orchestration:workflow:read --resource-uuid <workflow-uuid> --effect allow

# Take a grant back
cargo-ai workspaceManagement user remove-permission --user-uuid <uuid> --resource-uuid <workflow-uuid> --effect allow

upsert-permission について、知っておくべき点が 2 つあります。

• --action は権限アクションであり、read / write ではありません。 ロールに記載されているアクションのいずれかである必要があります。リソーススコープ付きのアクションは、orchestration:workflow:*|read|write、ai:agent:…、ai:mcpServer:…、hosting:app:…、hosting:worker:…、content:file:…、workspaceManagement:folder:… です。（CLI 1.0.128 より前は、ヘルプにある --action read の例は無効でした。）
• --effect deny は既存のメンバーにのみ適用されます。 そのため、--user-uuids を指定します。--emails を指定すると、その経路では招待が行われるため拒否されます。cargo#6369（CLI 1.0.128）より前は、API が effect を無視し、常に allow を設定していました。引き続きそうなるワークスペースでは、ロールに deny を設定してください（role create|update --permissions）。remove-permission はどちらの場合も --effect を反映します。

--emails は、まだメンバーではないアドレスを招待するため、まず user list で確認してください。

メンバーごとの月間クレジット上限。 PUT /v1/workspaceManagement/users/<user-uuid> は {"monthlyCreditsLimit": <n> | null} を受け付けます。この値は、メンバーがトリガーした実行、バッチ、エージェントメッセージ全体について、UTC の暦月ごとに消費できるクレジット数です。null を指定すると上限が解除されます。管理者はウェブアプリ（Settings → Users → メンバーのクレジット上限）でも設定できます。user list はこのフィールドを返しますが、これを指定する CLI フラグはありません。メンバーが上限に達すると、翌月まで新たにクレジットを消費する作業は拒否されます。ワークスペースの残高が空の場合と同様です。チェックは作業の開始前に行われ、最大 1 分間キャッシュされた利用額を参照するため、メンバーの利用額が上限をわずかに超えることがあります。フェイルオープン方式のため、上限または台帳を読み取れない場合は作業が実行されます。この制限は cargo#6379 で適用されるようになりました。それ以前に設定した上限は保存されていましたが、適用されていませんでした。メンバーごとの利用額は cargo-billing（usage get-metrics --group-by user_uuid）で確認できます。

サービスユーザー

サービスユーザーは、独自のロールを持つ非人間のアイデンティティです。ホストされたワーカー、コーディングエージェントのサンドボックス、接続済みの GitHub リポジトリなどがこれに該当し、自動化で個人のアクセス権を借用することはありません。受信トレイもログイン手段もなく、独自の API トークンでのみ認証します（アドレスは su-<uuid>@service-users.getcargo.io で、このドメインへの個人ユーザーの招待は拒否されます）。

CLI では作成できません — user create が受け取るのは --email と --role-slug のみです。ウェブアプリ、プロジェクトの defineUser（../cargo-project/references/resources.md を参照）、または API（workspace-management の書き込みアクセス）を使用してください。

# POST /v1/workspaceManagement/users
{"kind":"service","firstName":"Enrichment","lastName":"Worker","roleSlug":"<role-slug>"}
# → 201 {user}; 404 roleNotFound / workspaceNotFound
# A token for it: POST /v1/workspaceManagement/tokens {"name":"…","userUuid":"<service-user-uuid>"}
#   (403 unless the caller has workspace-management write and the target is kind "service")

firstName／lastName は省略可能です（1〜255 文字）。CLI の token create でトークンを発行できるのは実行者本人のみなので、サービスユーザー自身のトークンも API またはウェブアプリから発行します。

実行ユーザーの指定。 ワーカー（hosting worker update --run-as-user-uuid、defineWorker({ runAs })）、エージェントのコーディングリポジトリ（repository.runAsUserUuid、defineAgent({ repository: { runAs } })）、または接続済みリポジトリは、サービスユーザーとして実行できます。その場合、Cargo は一時的な CARGO_API_TOKEN をバインドします。割り当てには次の 2 つのチェックが適用されます。

理由	発生条件	ステータス
runAsUserNotFound	ユーザーが見つからない、または kind: "service" ではない場合 — 個人ユーザーを実行ユーザーに指定することはできません	hosting／state ルートでは 404、ai のチャット、メッセージ、リリースのルートでは 403
runAsUserNotPermitted	サービスユーザーの権限（自身の権限とロールの権限。deny エントリーを含む）のいずれかが、あなたの allow エントリーで許可されていない場合	403

そのため、自分がすでに持っているアクセス権のみを自動化に付与できます。また、自分より広範なロールを持つサービスユーザーを割り当てることはできません。

ロール

ロールは、ワークスペース内でユーザーが実行できる操作を定義します。

# List available roles
cargo-ai workspaceManagement role list

# Create a custom role: a slug, a colour, and a list of permission statements
cargo-ai workspaceManagement role create \
  --name "Run operator" --slug run-operator --color green \
  --description "Starts and reads runs and batches; cannot edit workflows" \
  --permissions '[
    {"effect":"allow","resources":null,"actions":["orchestration:read","orchestration:run:*","orchestration:batch:*","storage:read","segmentation:read"]}
  ]'

# Update or remove a custom role (built-in roles can't be changed)
cargo-ai workspaceManagement role update --uuid <role-uuid> --permissions '[...]'
cargo-ai workspaceManagement role remove <role-uuid>

ユーザーを招待する前に、利用可能なロールを必ず確認してください。ユーザーの作成または更新には、role list で確認した slug を使用します。

権限ステートメントは {"effect": "allow" | "deny", "resources": [<uuid>, …] | null, "actions": [...]} です。resources: null は、ステートメントをワークスペース全体に適用します。role update の --permissions はリスト全体を置き換えます。アクションは、ai、billing、connection、content、context、domainManagement、hosting、mailboxManagement、observability、orchestration、revenueOrganization、segmentation、storage、systemOfRecordIntegration、workspaceManagement に対する <domain>:*|read|write 形式に加え、リソースレベルのサブアクション（orchestration:workflow:…、ai:agent:…、hosting:app:…、workspaceManagement:folder:… など）を使用します。

オーケストレーションでは、実行と編集は別の権限です。orchestration:run:*|read|write は実行を対象とし、orchestration:batch:*|read|write はバッチを対象とします。これらは互いを含まず、ワークフロー、プレイ、ツールの編集権限もありません（それには orchestration:write／orchestration:workflow:write が必要です）。orchestration:read／:write／:* は、引き続き両方を含みます。これにより、ロールにワークフローの動作を変更させずに、実行の開始と監視を許可できます。

role create は slugAlreadyExists または slugReserved（組み込みの slug）で失敗します。メンバーがそのロールを持っている場合、またはそのロールがワークスペースのデフォルトロールである場合、role remove は roleInUse で失敗します。先にロールを再割り当てしてください。

API トークン

各トークンには、人が読める name と permissions フィールドがあります。CLI 経由で作成されたトークンは permissions: null で発行されます。これは、そのトークンが所有ユーザー（token create を実行したユーザー）の権限を引き継ぐことを意味します。そのため、トークンの実効アクセス範囲は、そのユーザーがワークスペースで実行できる操作に制限されます。きめ細かな権限の範囲指定（許可／拒否を明示するリスト）は、API または Cargo アプリで設定します。

# List your API tokens (includes name, permissions, and the token value of each)
cargo-ai workspaceManagement token list

# Create a new token — --name is required
cargo-ai workspaceManagement token create --name "CI/CD pipeline"
# → Returns the token value — store it securely

# Remove a token
cargo-ai workspaceManagement token remove <token-uuid>

名前： 後で token list を実行したときにトークンの用途が明確にわかる --name を指定してください（例："GitHub Actions — production"、"Local dev — alice"、"Zapier integration"）。一覧でトークンを見分ける方法は名前だけです。

セキュリティ： トークンの値は作成時と、token list の実行時（自分のトークン、および管理者の場合はサービスユーザーのトークン）に返されます。どちらの出力も秘密情報として扱い、値はシークレットマネージャー（例：GitHub Secrets、AWS Secrets Manager）に保存してください。

フォルダー

フォルダーは Cargo アプリ内のリソース（プレイ、ツール、エージェント）を整理します。

# List all folders
cargo-ai workspaceManagement folder list

# Create a folder (kind: tool, play, agent, file, mcpServer, model, app, worker, alert, or mailbox)
cargo-ai workspaceManagement folder create --name "Q1 Campaigns" --emoji-slug "rocket" --kind "play"

# Get a folder
cargo-ai workspaceManagement folder get <folder-uuid>

# Update a folder (rename, move under a parent, or reorder among its siblings)
cargo-ai workspaceManagement folder update --uuid <folder-uuid> --name "Q1 2025 Campaigns"
cargo-ai workspaceManagement folder update --uuid <folder-uuid> --parent-uuid <parent-folder-uuid> --order 0

# Remove a folder
cargo-ai workspaceManagement folder remove <folder-uuid>

レポート

ワークスペース管理者にレポートを送信します。CLI が失敗する、予期しない動作をする、必要な機能がない場合、または CLI でのタスクの達成にユーザーやエージェントが苦労している場合は、必ずレポートを送信してください。 これは公式のフィードバック窓口です。すべてのレポートは Cargo チームが確認し、CLI、そのスキル、基盤となる API の改善に活用します。

# Submit a report to workspace management
cargo-ai workspaceManagement report create \
  --title "<short summary>" \
  --description "<detailed description, including the command(s) tried and the error(s) seen>"

レポートを送信する状況（以下に限定されません）：

• コマンドが errorMessage とともにゼロ以外の終了コードを返し、--help や references/troubleshooting.md を参照しても解決できない。
• CLI の使い方に誤りがある、または構文が不明確である（例：どのフラグを渡せばよいかわからない、あるいは --filter／--nodes／--action の JSON スキーマが曖昧である）。
• ユーザーまたは AI エージェントが進展のないまま同じコマンドを繰り返し再試行している（同じタスクで 2 回以上失敗）。
• ドキュメントに記載されたコマンドがスキルの説明どおりに動作しない、または応答の形式が references/response-shapes.md の記載と異なる。
• 必要な機能がまったくないように見える（必要な操作を実行するコマンドが存在しない）。
• 非同期操作が終了状態に到達しない、または実行ごとに一貫しない結果を返す。

レポートに記載する内容：

• --title：問題の概要を一行で記載します（例："batch create fails with 'playNotCompatible' on tool workflow"）。
• --description：実行したコマンド（機密値は伏せる）、JSON の errorMessage、期待した動作、試したこと、および関連する UUID（run、batch、workflow、model）を記載します。情報が詳しいほど、問題を迅速に振り分けられます。

# Example: report a CLI struggle after multiple failed attempts
cargo-ai workspaceManagement report create \
  --title "segment fetch returns empty results despite matching records in UI" \
  --description "Ran: cargo-ai segmentation segment fetch --model-uuid <uuid> --filter '{\"conjonction\":\"and\",\"groups\":[...]}'. Got 0 records. The same filter shows 1,200 matches in the app UI. Tried both --filter and --segment-uuid; both return empty. Expected: the same records as the UI."

CLI のタスクが失敗しても、黙って諦めないでください。レポートを送信してください。 これによりフィードバックの循環が生まれ、CLI とこれらのスキルを改善できます。

セッション

Claude Code のセッションを workspace_management.sessions に記録します。(workspaceUuid, sessionId) ごとに 1 行です。Cargo ルーターの Claude Code SessionStart + Stop + SessionEnd フックのレシピで使用します。フックの設定方法については、../cargo/SKILL.md を参照してください。

# Upsert a session. Idempotent on --session-id within the workspace.
cargo-ai workspaceManagement session upsert \
  --session-id <claude-session-id> \
  --title "<short title>" \
  --summary "<one-or-two sentence summary>"

# Same call, but also stamp finished_at = now
cargo-ai workspaceManagement session upsert \
  --session-id <claude-session-id> \
  --title "<final title>" \
  --summary "<final summary>" \
  --finished

• 毎回の呼び出しで --session-id、--title、--summary が必須です。スキーマでは title と summary が NOT NULL のため、開始時の呼び出しではプレースホルダーを渡し、終了時の呼び出しで上書きしてください。
• --finished は finished_at = now を設定します。明示的なタイムスタンプを指定する場合は、代わりに --finished-at <iso> を使用してください。
• 同じ --session-id で upsert を 2 回呼び出すと、同じ行が更新されます。title と summary は上書きされ、finished_at は --finished または --finished-at が渡された場合にのみ設定されます。

upsert されたセッションを JSON で返します。Cargo インストーラーは、このコマンドを自動で呼び出す SessionStart + Stop + SessionEnd フックを設定します。SessionStart はプレースホルダーを書き込み、各ターンの Stop フックは行をチェックポイントとして保存し（--finished なし）、SessionEnd はトランスクリプトに基づく AI の要約を --finished 付きで書き込みます。詳しくは references/examples/sessions.md を参照してください。

環境変数

ワークスペースの環境変数は、ワークスペース内のすべてのワーカー、アプリ、エージェントに注入されます。同じキーを持つワーカーまたはアプリレベルのエントリがある場合は、そちらが優先されます。カタログはひとつですが、読み取られるタイミングは利用者によって異なります。

• エージェントと、プロジェクトの workspaceEnv("NAME") ポインターは、使用するたびにサーバーサイドで値を読み取るため、値をローテーションすれば、再デプロイなしで反映されます。
• ホスト型のワーカーとアプリは、デプロイ時に値を取り込みます。 ワーカーのバインディングはデプロイをプロモートした時点で割り当てられ、シークレットではない値はバンドルにコンパイルされます。アプリには、パブリックプレフィックス（VITE_、NEXT_PUBLIC_ など）が付いたシークレットではないエントリのみが渡され、ビルドに埋め込まれます。変更後は、hosting deployment create + promote を再度実行してください。詳細は ../cargo-hosting/SKILL.md → Worker env vars and secrets を参照してください。

cargo-ai workspaceManagement envVar list

# Create. Omit --value to read it from the environment variable of the same name.
cargo-ai workspaceManagement envVar create \
  --key OPENAI_API_KEY \
  --value sk-... \
  --secret \
  --description "Used by the enrichment worker"

# Update. Omit --value to keep the stored one.
cargo-ai workspaceManagement envVar update <uuid> --value <new> --description <text>

cargo-ai workspaceManagement envVar remove <uuid>

• --secret を指定すると、値は保存時に暗号化され、以後返されることはありません。list や update を実行しても値は表示されません。認証情報にはこのオプションを使用してください。update で --no-secret を指定すると、変数をプレーンテキストに戻せます（list に再び表示されるようになります）。
• create では --value は省略できます。 省略すると、CLI はシェルから同名の環境変数を読み取ります。そのため、export OPENAI_API_KEY=… && cargo-ai workspaceManagement envVar create --key OPENAI_API_KEY --secret とすれば、値をシェルの履歴やこのコマンドラインに残さずに済みます。
• update に渡すのはキーではなく uuid です。 envVar list で確認してください。

プロジェクトからエントリを参照する場合は、値をコードにコピーするのではなく、workspaceEnv("NAME") を使用してください。これは使用のたびにサーバーサイドで解決されるポインターです。もうひとつの選択肢である secret("NAME") は意味が異なり、デプロイ時に お使いの 環境から読み取ります。詳細は ../cargo-project/SKILL.md → Critical rules を参照してください。

ワークスペースファイル

ワークスペースファイルは、バッチ実行で使用するためにアップロードされた CSV またはその他のデータファイルです。

# Upload a file
cargo-ai workspaceManagement file upload --file <path-to-file>
# → Returns s3Filename

# Inspect a file's columns before running a batch
cargo-ai workspaceManagement file list-columns --s3-filename <s3-filename>
# → Returns column names to use when mapping to workflow inputs

s3-filename は、cargo-ai workspaceManagement file upload でファイルをアップロードした際に返されます。ファイルのアップロードからバッチ実行までのワークフロー全体については、cargo-orchestration スキルの references/examples/tools.md を参照してください。

ヘルプ

すべてのコマンドで --help を使用できます。

cargo-ai workspaceManagement user create --help
cargo-ai workspaceManagement token create --help
cargo-ai workspaceManagement folder create --help