cargo-content

Cargo CLI — コンテンツ

ワークスペースのファイル：ファイル（PDF、CSV、テキスト）をアップロードして整理し、グループ化または同期してライブラリにまとめます。ライブラリは、エージェントの応答の根拠となるナレッジリソース（検索拡張生成、RAG）です。ファイルは単なるストレージとしても使えます。CLI、HTTP オブジェクト API、ホストされたワーカー、ワークフローノード、エージェントから、パスを指定して書き込み、読み戻し、フォルダーの内容を一覧表示し、リンクを渡せます。ファイルをストレージとして使うをご覧ください。

トップレベルドメインの新設（CLI ≥ 1.0.19）。 ファイルとライブラリは ai ドメインから content ドメインに移動しました — cargo-ai content file … と cargo-ai content library …。以前の cargo-ai ai file … コマンドは存在しなくなりました。unknown command エラーが表示される場合は、古いコマンドを使っています。

エージェントにファイルまたはライブラリをアタッチするには（リリースの resources 配列を使用）、cargo-aiをご覧ください。 ファイルを整理するフォルダーには、cargo-workspace-management（cargo-ai workspaceManagement folder …）を使用してください。 バッチ実行の入力ファイル（バッチ処理を実行するためにアップロードする CSV）は別の機能です — cargo-ai workspaceManagement file upload。詳しくはcargo-workspace-managementをご覧ください。

ファイル、ライブラリ、エージェントへのアタッチの一連の例は references/examples/files.md をご覧ください。 ファイルをストレージとして使う場合のパスモデル、ストレージ設定と各サーフェスのデフォルト、署名付きリンクと公開リンク、コンテキストミラー、および HTTP／ワーカー／ノード／エージェントの各サーフェスについては references/objects.md をご覧ください。 JSON レスポンスの構造全体については references/response-shapes.md をご覧ください。 よくあるエラーとその解決方法については references/troubleshooting.md をご覧ください。

初期設定

すでにサインイン済みで（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 を標準出力に出力します。失敗時は {"errorMessage": "..."} を返し、ゼロ以外の終了コードで終了します。実行またはバッチを作成するコマンドはすべて非同期です — --wait-until-finished を渡すか、対応する get をポーリングしてください。スキル一式をインストールすると、../cargo/references/prerequisites.mdに CLI バージョンの固定、トークンスコープ、管理者専用の機能が記載されています。

まずリソースを確認する

cargo-ai content file list                 # all uploaded files (uuid, name, contentType, size)
cargo-ai content library list              # knowledge libraries (native or connector-backed)

ファイル

ファイル（PDF、CSV、テキスト）をアップロードすると、エージェントは特定のナレッジを根拠に応答できるようになります。アップロードのレスポンスには、エージェントのリリースにファイルをアタッチする際に参照する uuid が含まれます（cargo-aiをご覧ください）。

# List all files
cargo-ai content file list

# Get a single file
cargo-ai content file get <file-uuid>

# Upload a file (optionally straight into a folder)
cargo-ai content file upload --file ./knowledge-base.pdf
cargo-ai content file upload --file ./knowledge-base.pdf --folder-uuid <folder-uuid>

# Update a file's name or folder
cargo-ai content file update --uuid <file-uuid> --name "Q1 Research Notes"
cargo-ai content file update --uuid <file-uuid> --folder-uuid <folder-uuid>

# Remove a file
cargo-ai content file remove <file-uuid>

コンテキストリポジトリ内のコンテンツファイル。 mirrorToContext: true のファイル（upload、ウェブアプリからのアップロード、defineFile のデフォルト）は、コンテキストリポジトリの .files/<path> にコミットされ、プッシュされます（コミット content(mirror): upsert <name>。10 MB を超える場合は、ファイル本体の代わりに JSON メタデータのサイドカーが保存されます）。そのため、コンテキストランタイムのサンドボックスで実行するコマンドから読み取ることができます — 例：cargo-ai context runtime execute --command ls --args '["-1",".files"]' — また、そのリポジトリにアクセスできる人も読み取れます。パスへの書き込み（put、オブジェクト API、ワーカー、ノード、エージェント）のデフォルトは mirrorToContext: false で、Git には含まれません。コンテキストランタイムから .files/ への書き込みはできません（deniedPath）。これらのファイルを変更するには、ここで content file を使用してください。cargo-contextをご覧ください。

ストレージとしてのファイル（パスとリンク）

ファイルのパスは、フォルダー階層とファイル名を組み合わせたものです（reports/2026-q3/summary.pdf）。パスに書き込むと、不足しているフォルダーが作成され、同じ名前の最新ファイルがその場で上書きされます（uuid は同じままで、新しい設定を渡さない限り設定も維持されます）。

cargo-ai content file put reports/2026-q3/summary.pdf --file ./summary.pdf   # → { file, path }; any size
#   --content-type <mime> (guessed from the extension) · --index none|vectorStore (none)
#   --visibility private|public (private) · --mirror-to-context (off)
cargo-ai content file ls reports/ --limit 100            # prefix match, ordered by path; --limit ≤ 1000, --cursor <nextCursor>
cargo-ai content file download reports/2026-q3/summary.pdf --out ./copy.pdf
cargo-ai content file url reports/2026-q3/summary.pdf --expires 3600 [--download]   # → { url, expiresAt, publicUrl? }
cargo-ai content file visibility reports/2026-q3/summary.pdf public   # private revokes the public link at once
cargo-ai content file rm reports/2026-q3/summary.pdf

オプション	upload／ウェブアプリ／defineFile	put／オブジェクト API／ワーカー／writeFile ノード	エージェントによる書き込み
indexMode (--index)	vectorStore	none	常に none
mirrorToContext	true	false	常に false
visibility	private	private	常に private

HTTP 経由では、同じファイルをオブジェクトとして扱います。PUT／GET（詳細情報は ?meta=true）／DELETE /v1/content/objects/<path>、GET /v1/content/objects?prefix= を使用します。ワーカーからは createCargoObjects(env)（@cargo-ai/worker-sdk）、プレイでは writeFile／readFile／getFileUrl ノード、エージェントでは書き込み可能なフォルダー（capability_file_write）を使用します。詳細はすべて references/objects.md を参照してください。

ライブラリ

ライブラリはファイルをまとめたものです。エージェントのリリース resources が受け取るのはファイルまたはフォルダーの項目であり、ライブラリの UUID ではありません。そのため、エージェントはライブラリ内のファイル、またはファイルの保存先フォルダーを通じてライブラリにアクセスします。ライブラリには次の 2 種類があります。

• native — アップロードしたファイルをワークスペースで管理するコレクションです（CLI からは作成できません。library create はコネクター専用です）。
• connector — 非構造化データ抽出ツール（--extractor-slug）を介して外部ソース（ヘルプセンターやナレッジベースなど）から同期されます。cargo-connection から connectorUuid を取得してください。

# List libraries (filter by kind or connector)
cargo-ai content library list
cargo-ai content library list --kind native
cargo-ai content library list --kind connector --connector-uuid <connector-uuid>

# Get a single library
cargo-ai content library get <library-uuid>

# Create a connector-backed library
cargo-ai content library create \
  --name "Help Center" \
  --connector-uuid <connector-uuid> \
  --extractor-slug <extractor-slug> \
  --folder-uuid <folder-uuid> \
  --config '{}'

# Update / remove
cargo-ai content library update --uuid <library-uuid> --name "Updated Name"
cargo-ai content library remove <library-uuid>

重要なルール

• 署名付き URL は認証なしでアクセスできます。 URL を持っている人は、期限が切れるまでファイルを開けます（デフォルトは 3600 秒、最大 10800 秒です）。public ファイルには、安定した認証不要のリンク https://api.getcargo.io/files/public/<uuid>/<name> が追加されます。このリンクは、ファイルが非公開にされるか削除されるまで有効です。ユーザーがファイルの共有を求めた場合に限り、どちらかのリンクを共有してください。また、レコード単位の個人データに対しては、絶対に共有しないでください。
• upload と put ではデフォルトが異なります。 upload はインデックス化し（vectorStore に登録して OpenAI に送信）、コンテキストリポジトリにもミラーリングします。put はどちらも行いません。--index vectorStore を指定して書き込むまでは、put したファイルはエージェントから検索できません。capability_file_search では対象外となり、capability_file_analyze は処理を拒否します。
• ミラーリングされたファイルは Git に保存されます。 mirrorToContext: true にすると、ファイルはコンテキストリポジトリの .files/ 配下にコミットされます。Content 内に保持するファイルでは、--index none を指定し、ミラーリングをオフ（put）にしてください。
• パスへの書き込みは確認なしに上書きします。 そのフォルダー内にある同じ名前の最新ファイルがその場で置き換えられ、その uuid（およびそれを参照するすべてのエージェントリソース）から新しいバイトデータが提供されます。読み取り専用のフォルダー（コネクター）は folderReadOnly エラーを返します。

エージェントへの追加

ファイルとライブラリはナレッジリソースです。エージェントのドラフトリリースの resources 配列に追加してデプロイするまでは、何も行いません。この設定は cargo-ai にあります（ai release update-draft --resources … → ai release deploy-draft）。アップロード → 追加 → デプロイの手順については references/examples/files.md を参照してください。

ヘルプ

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

cargo-ai content file upload --help
cargo-ai content library create --help