uploads-cli について
uploads-cliは、ファイルをuploads.shにアップロードし、GitHubのプルリクエストやIssueに添付する手順を説明するスキルです。ローカルのuploads CLIとホスト型MCPを扱い、ステージング、メタデータ、管理コメント、ファイル承認を紹介します。
主な機能
- 01ファイルをアップロードして公開URLを取得
- 02GitHubのPRやIssueへのファイル添付
- 03PR作成前のファイルのステージング
- 04メタデータによる検索と管理
- 05保留中ファイルの承認
活用シーン
- 01PRにスクリーンショットやレポートを追加
- 02ブランチのファイルを後日の昇格用にステージ
- 03メタデータでアップロード済みファイルを検索
- 04保留中の添付ファイルを確認して承認
MCP 対応
このスキルは、https://agents.uploads.sh/mcp のホスト型MCPと、ローカルstdio MCPおよびuploads CLIの手順を説明します。ホスト型ツールは受け取ったファイル内容や公開URLを扱い、ローカルCLIはファイルシステムのパスやGitの情報を利用します。
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/uploads-cliを入力して読み込まれたか確認します。
詳細
翻訳後に原文が更新されています。最新の内容は原文をご確認ください。
ファイルを uploads.sh にアップロードして GitHub に埋め込む
できることと、その理由
GitHub のネイティブな画像ホスティング（github.com/user-attachments/…）は、ブラウザーセッションから利用できます。また、GitHub CLI 2.99（2026 年 9 月）以降は、プッシュ権限があれば、既存の PR または issue に対する gh … --attach でも利用できます。公開 REST エンドポイントは依然として存在せず、ホストされたファイルは GitHub からのみアクセスできます。gh … --body-file で作成する PR／issue の本文に記載するその他の画像 URL は、すでに一般公開されている場所を指している必要があります。github-screenshots スキルでは、gh --attach だけで十分な場合について説明しています。
このスキルでは、2 つの転送方式に対応しています。ローカルファイル、git、localhost に対応する**uploads CLI**と、すでに手元にあるバイトデータ、またはフェッチ対象の公開 HTTPS URL に対応し、チェックアウトが不要なホスト型 MCP（https://agents.uploads.sh/mcp）です。どちらも uploads.sh API に PUT し、安定した公開 URL と、すぐに貼り付けられる Markdown を返します。PR と issue では、管理された添付ファイルコメントをどちらの方式でも利用できます。CLI はローカルの gh にフォールバックできます。ホスト型 MCP はボット専用です。
MCP と CLI の比較
同じ製品の、異なる 2 つの転送方式です。スキルはバイナリをインストールしません。
| 必要なもの | 使用するもの | 理由 |
|---|---|---|
| コンテキスト内にすでにあるバイト列（ChatGPT の添付ファイル、base64） | ホスト型 MCP put | files: [{ filename, contentBase64 }]。repo と（pr | branch）を渡します。Git からの推測は行いません。 |
| すでに公開 HTTPS URL にあるファイル | CLI put --url またはホスト型 MCP put | CLI：uploads put --url https://… --pr 123。ホスト型：{ contentUrl }（URL パスにファイル名が含まれる場合、ファイル名は省略可能です）。ワーカー／CLI が取得します。認証ヘッダーは不要です。ホスト型はプライベート／内部ホストを拒否します。CLI（および stdio MCP）では http://localhost／127.0.0.1／*.localhost も取得します。LAN およびリンクローカルは引き続き拒否されます。 |
| 一覧表示、検索、メタデータ、コメント、昇格 | どちらでも | ホスト型：list、find_files、get_metadata／set_metadata、comment、promote。CLI：uploads list／find／meta／comment／attach --promote。 |
| プルリクエスト別またはリポジトリ別の、最近タグ付けされたファイル | ホスト型 MCP list_activity／list_repo_files | ホスト型のみです。list_activity はプルリクエスト別（デフォルト）またはリポジトリ別にグループ化します。list_repo_files には repo が必要です。時刻はタグのメタデータであり、アップロード時刻ではありません。フィードは公開されません。 |
| この PR（またはリポジトリ）のスクリーンショットを表示するライブページ | どちらでも | CLI uploads feed create または MCP feed_create。リポジトリ全体の場合：repo のみ。1 つの PR の場合：repo と pr、または github（owner/repo#123／GitHub URL）。同じ製品ですが、厳選されたギャラリーではありません。既存のフィードを開くには、feed_get／uploads feed show を使用します。 |
| ローカルパスまたは現在のブランチからの添付 | CLI | ホスト型サーバーにはファイルシステムがなく、attach ツールもありません。代わりに put を使用してください。 |
localhost／プライベートネットワーク上のスクリーンショット | CLI uploads screenshot --via local | リモートレンダリングからはお使いのマシンにアクセスできません。 |
| どちらのトランスポートも使えない場合 | 停止 | npm install -g を ChatGPT で使う方法として扱わないでください。https://agents.uploads.sh/mcp での OAuth が公開済みのリモートパスです。 |
このスキルの残りの CLI の例では、チェックアウトと uploads | ||
| バイナリがあることを前提としています。ホスト型ツールのコントラクトは、下記の注意事項（MCP の箇条書き）にあります。 |
一般的なケースでは、uploads attach <file...> を使用します。現在のブランチの PR を推定し、安定した添付キーを使ってすべてのファイルを並行してアップロードし、デフォルトでコメントを管理します。ファイルに問題があっても、ほかのファイルの処理はブロックされません。JSON には uploads と failures が含まれます（失敗があれば終了コードは 1）。
uploads attach ./before.png ./after.png
uploads attach ./shot.png --issue 45 --repo buildinternet/uploads
安定した URL だけが必要な場合は、--no-comment を指定します。より細かく名前と出力を制御するには、put を使用します。
アップロード済みオブジェクトを添付する（issue #702）。 ディスク上に存在しない attach 引数がワークスペースのオブジェクトキー（例：f/AbC123/shot.webp）または uploads.sh の URL（ストレージホスト、埋め込みホスト、または /f/ ページ）として解決される場合、file not found エラーにはならず、再ダウンロード／再アップロードを行わずにサーバー側コピーで添付されます。ソース独自の派生メタデータ（path／url／viewport／state／…）は引き継がれ、gh.repo／gh.kind／gh.number／gh.ref は新たに付与されます。デフォルトではコピーされます。コピー成功後にソースを削除するには、--move を指定します。ディスク上に存在するパスは、キーとしても解析できる場合であっても、常にローカルファイルとして優先されます。
uploads attach f/AbC123/shot.webp --pr 123
uploads attach https://storage.uploads.sh/<workspace>/f/AbC123/shot.webp --pr 123 --move
PR が作成される前から、作業中にステージングする。 uploads attach ./shot.png --branch [name] は、PR／issue 番号ではなく、gh/<owner>/<repo>/branch/<branch>/<filename> の下にファイルをステージングします。アップロード経路は同じで、ターゲット指定フラグは不要で、コメントも作成されません（まだコメントする対象がないためです）。値を指定しない場合、--branch は現在の git ブランチを解決します。名前に含まれる / は - に置き換えられます。最後に一度だけではなく、作業中の視覚的な節目ごとにこの方法で添付してください。ステージングしたファイルには、昇格によって promoted に切り替わるまで gh.status=staged が設定されます。そのため、uploads find gh.status=staged（絞り込むには gh.branch=<name> を追加）で、まだ処理中のファイルを一覧表示できます。またサーバーは、gh.* タグ付きアップロードに gh.uploader／gh.uploader-id（トークンの発行元ユーザーに基づく）も付与するため、uploads find gh.status=staged gh.uploader=<login> で、特定のコントリビューターが処理中のファイルに絞り込めます。
ステージング済みの内容を確認する：uploads staged。 専用の読み取り専用ビューを使うと、上記の find／list クエリを手動で組み立てずに、「このブランチに何がステージングされていて、自動添付されるか」を確認できます。
uploads staged # current branch, repo from gh/git remote
uploads staged --branch feature/thing --repo owner/name
uploads staged --format json
ブランチとリポジトリの解決方法は attach --branch と同じです（デフォルトでは現在の git ブランチを使用し、ワークツリーにも対応しています）。すでにプルリクエストにあるファイルは一覧表示されません。これには、gh.status=promoted、gh.promoted-to または gh.promoted-at マーカーがある場合と、同じファイル名のプルリクエスト用コピーがあり、そのコピーが gh.staged-at と同じかそれより新しい場合が含まれます。再ステージされたファイルのほうが新しい場合は、一覧に残ります。プライベートリポジトリでは、ステージングキーは gh/private/<id>/branch/<filename> です。ID が単一のブランチに属するため、キーにブランチ名は含まれません。uploads staged --branch はその ID を一覧表示し、gh.branch がそのブランチであるファイルを残します。gh.branch のないファイルは、このブランチのプレフィックスの下で一覧表示されたものなので残ります。gh.status=unstaged のファイルは除外されます。uploads staged は書き込みを行いません。
保留中のファイルを公開する：uploads approve。 分類器は、秘密情報や機微な個人データが含まれていると判断したファイルを保留にすることがあります。その場合、管理対象のコメントでは画像の代わりに 🔒 N files are held for review と表示されます。承認する前に各ファイルを確認してください。実際の認証情報が含まれている場合は、ローテーションしてファイルを差し替えてください。files:write が必要です。
uploads approve --pr 123 # list held files and why; changes nothing
uploads approve --pr 123 --all # approve every held file on the PR
uploads approve gh/owner/name/pull/123/settings.png
ブランチをクリアする：uploads unstage。 ファイルを gh.status=unstaged に設定し、uploads staged、自動昇格、Claude プラグインのバンドから除外します。オブジェクトとその URL は保持されます。files:delete ではなく、files:write が必要です。
uploads unstage --branch feature/thing
uploads unstage --branch feature/thing --repo owner/name --dry-run
uploads unstage gh/owner/name/branch/feature-thing/shot.png
--branch は現在の git ブランチをデフォルトにしません。すでに昇格済みのものも含め、ステージング解除するオブジェクトをキーで指定する場合は、--branch ではなくキーを渡してください。プライベートリポジトリでは、このブランチのプレフィックス ID（gh/private/<id>/branch/…）が一覧表示されます。これは uploads staged が使用するものと同じセットです。キーと --branch を同時に指定するとエラーになります。
ローカルの stdio MCP では、これを unstage（branch または keys、任意の
repo および dryRun）として提供します。ホスト型 MCP ツールも unstage です。ホスト型には
Git のデフォルト値がないため、branch を指定する場合は repo が必須です。
uploads list に --branch はありません。--branch を含む不明なフラグは
エラーになります。uploads staged --branch <name> を使用してください。
通常モードでは、ステージ済みファイルごとに簡潔な行（ファイル名、サイズ、
gh.staged-at、公開 URL）を出力し、続いて binding: の行と
once the PR exists: uploads attach --promote を出力します（binding: other
の場合は、別のワークスペースからのプロモートはテナント間ゲートで拒否されるため、
プロモートの行は省略されます）。ステージ済みファイルがない場合は、ゼロ件を示す行を
1 行だけ出力します。--format json（またはグローバルな --json）では、ファイルが
0 件の場合も常に有効なドキュメント — { repo, branch, files, binding } — を出力します。
files は [] になり、標準出力が空になることはありません。
binding には、ステージ時の警告で使われるものと同じ repo↔workspace の確認結果が含まれます
（下記の「リポジトリのバインド」を参照）。そのため、個別に判断する必要はありません。
binding.state | binding.autoAttach | 意味 |
|---|---|---|
self | true | リポジトリはこのワークスペースにバインドされています — PR を開くとステージ済みファイルが自動で添付されます。 |
none | false | リポジトリはまだリンクされていません — リンクする（uploads github link）か、自動添付されないままになります。 |
other | false | リポジトリは別のワークスペースにリンクされています — ここからはこれらのファイルは自動添付されません。 |
unknown | false | バインドの確認に失敗しました（オフライン、またはルートを備えていない古いサーバー） — 参考情報のみで、表示を妨げることはありません。 |
none／other の文言は、attach --branch のステージ時警告（issue #398）と
まったく同じです — 情報源を一元化することで、2 つの表示が食い違わないようにしています。
ローカルの stdio MCP では、これを staged ツール（branch／repo 引数、
同じ { repo, branch, files, binding } 形式）として提供します。ホスト型 MCP には
専用の staged ツールはありません（Git のデフォルト値がないため）。ホスト型の
put／promote で repo／branch を明示する方法と、list／find_files のレシピについては、
以下の 注意事項（MCP の箇条書き）を参照してください。
PR がそのブランチに存在すれば、ファイルを PR の添付コメントに追加するための手順は ほかに必要ありません。
- リポジトリに GitHub App がインストールされている場合：PR が開かれたとき、 再度開かれたとき、または新しいコミットが追加されたときに、Webhook がステージ済みファイルを PR の添付プレフィックスに自動でプロモートし、管理対象のコメントを作成または更新します。
- GitHub App がない場合：その PR を対象とする次回の
uploads attachで、コメントを 更新する前にステージ済みファイルが PR の添付プレフィックスに自動でプロモートされます。 最初の attach で新たにアップロードするものがない場合は、uploads attach --promote（ファイル引数なし）を実行すると、プロモートとコメントの更新のみを行います。ステージ済み ファイルがない場合も終了コード0で終了します。特定の呼び出しで自動プロモートを スキップするには、--no-promoteを指定してください。
プロモートの対象は PR のみで、issue は対象外です。また、どちらの方法も、ワークスペースの
サーバーがまだプロモートに対応していない場合は、エラーを出さずに処理を続行します。
PR が作成される前にブランチ名が変更された場合は？ ステージングされたキーにはステージング時のブランチ名が埋め込まれるため、新しいヘッド ref で昇格しようとしても何も見つかりません。これは自動的に処理されます。名前変更後のブランチで uploads のステージングまたは昇格コマンド（attach --branch、put、attach --pr、attach --promote）を実行すると、ブランチの git reflog から名前変更を読み取り、サーバーに登録して、昇格時に古い名前も検索します。これには、PR が作成される前にブランチで uploads をもう一度実行する必要があります。ブランチ名が変更または削除され、実行しないまま PR が作成された場合、ファイルはステージングされたままになります（URL は引き続き有効です）が、添付されません。uploads attach --pr <n> --from-branch <old-branch-name> で復旧してください（ファイル引数は 0 個でもかまいません）。古いブランチのプレフィックスを PR に昇格し、コメントを更新します。通常のステージングとプライベートリポジトリのステージングの両方で機能します。
昇格するには、リポジトリがすでにワークスペースに紐付けられている必要があります。 webhook と上記の CLI 起動経路は、どちらも管理対象コメントで使われる同じリポジトリ↔ワークスペースの紐付けに依存します（以下の「リポジトリの紐付け」を参照）。そのリポジトリに対して以前に成功した attach／comment／昇格の呼び出しがあれば暗黙的に紐付けられます。または、uploads github link で明示的に紐付けられます。これまで一度も紐付けられておらず、--branch を使ったステージングしか行われていないリポジトリでは、エラーもコメントも発生しません。PR 作成時の昇格は何もせずに終了します。リポジトリがすでに紐付けられていると確認できない場合は、自動添付を約束しないでください。紐付けの履歴に関係なく機能する、セットアップ不要の代替手段は、PR 作成後に uploads attach --promote（または対象を指定した uploads attach）を一度実行することです。
コメントが見つからない場合は？ まず少し待ってください。App がインストールされ、issue_comment を購読している場合、削除されたり壊れたりしたボットのコメントは次の webhook 配信時に自動修復されます。慌てて再投稿しないでください。それでも見つからない場合は、リポジトリ↔ワークスペースの紐付けを確認してください。uploads github link --status を実行すると、紐付けを登録せずに読み取り専用で状態を確認できます。以下の「リポジトリの紐付け」を参照してください。
GitHub 向けの大きな特長は、--pr／--issue によってハッシュを含まない安定したキー（gh/<owner>/<repo>/pull/<num>/<name>）が生成されることです。そのため、同じファイル名を再アップロードすると既存の場所が上書きされ、URL は変わりません。確認プロンプトは表示されません。これはエージェントや再実行を想定した意図的な仕様です。人間向けモードでは、上書き後に >> replaced existing object (same URL) と表示され、JSON では "replaced": true|false が返されます。書き込みを行わずにプレビューするには --dry-run を使ってください。キーがすでに存在する場合は >> would replace existing object (same URL) と表示されます。
それ以外のキーはすべて厳格に扱われます（issue #174）。明示的な --key を指定した場合、または --pr／--issue を指定せずに既定の put パスを使った場合、既存オブジェクトの上書きは拒否されます。CLI エラーには既存オブジェクトの URL が示され、--replace（MCP では replace: true）を追加するよう案内されます。これらのパスで常に上書きする動作に戻すには、UPLOADS_OVERWRITE=1 を設定してください。--dry-run でも拒否されることをプレビューでき、>> would refuse: key already exists と表示されます。これは --pr／--issue のキーには適用されず、これらは常にホットスワップされます。
共有のデュアルホスト構成が適用される場合、レスポンスには2 つの公開 URL が含まれます。
| フィールド | ホスト（既定） | 用途 |
|---|---|---|
url | storage.uploads.sh | 永続リンク、クリックして開く用途、GitHub 以外への埋め込み |
embedUrl | embed.uploads.sh | GitHub PR／issue の Markdown（<img src>／![]()） |
embedUrl は同じオブジェクトを指し、バッジ形式のキャッシュなしヘッダーを備えているため、上書き後に GitHub Camo が再検証します。CLI／MCP の markdown と管理対象の添付ファイルコメントでは、すでに embedUrl が優先されます。UPLOADS_EMBED_PUBLIC_BASE_URL で上書きできます（空にすると無効になります。セルフホストの場合は、キャッシュなしの CDN ベース URL を設定してください）。
前提条件
- シェルを使えない／ChatGPT を利用していますか？ このセクションは読み飛ばしてください。ホスト型 MCP（
https://agents.uploads.sh/mcp）と上の表を使用します。CLI はインストールしないでください。 - Node.js ≥ 22。
- CLI。 エージェントで繰り返し使う場合はグローバルにインストールするか、
npxで一度だけ実行します：
このスキルのすべての例では、グローバルなnpm install --global @buildinternet/uploads npx @buildinternet/uploads --help uploads --versionuploads …バイナリ（インストール後と同じもの）を使用します。uploads モノレポ内に限り、pnpm uploads …はまずローカルソースからビルドします。この方法でプロダクトや PR の例を書かないでください。 スクリプトでの手順では、標準エラー出力をクリーンに保ち、任意の更新通知を省略できる--jsonまたは--quietを優先してください。 - 設定済みのトークン（初回のみ。以下を参照）。
uploads doctorで確認します。 - 認証済みの
ghCLI — PR／issue に書き込む--comment／comment機能でのみ必要です。通常のアップロードには不要です。
初回のセットアップ
設定はユーザーが所有するファイルに保存されるため、スキルを再インストールしても維持されます：
~/.config/buildinternet/config # or $XDG_CONFIG_HOME/buildinternet/config
解決順序はキーごとに最初に一致した値が優先されます：CLI フラグ（--api-url、--token、--workspace）→ UPLOADS_* 環境変数 → --env-file <path> → $BUILDINTERNET_CONFIG → 共有設定ファイル。別の API またはワークスペースに一度だけ接続する場合は、変数をエクスポートするか、--env-file を渡してください。
最も手早い方法は uploads login です。まずワークスペース管理者にワークスペースへの招待を依頼し、その後、対話形式で一度だけ実行してサインインします：
uploads login # opens a browser to approve sign-in, saves config, runs doctor
uploads login --workspace acme # only needed if your account can access more than one
アカウントにまだワークスペースがない場合、login は名前の入力を求め、GitHub のログイン名から生成した候補を角括弧付きのデフォルトとして提示します。Enter キーを押してその名前を使うか、独自の名前を入力してください。有効で未使用の名前を生成できない場合、候補は事前入力されません。--workspace <name> --create を指定するとプロンプトを完全に省略できます。スクリプトではこの形式を使用してください。
これは人が介在する初回のみの手順です（デバイスサインインにはブラウザーが必要です）。設定ファイルが書き込まれた後は、非対話型エージェントからの実行も含め、以降の uploads の呼び出しはすべて保存済みトークンを読み取るだけです。通常のエージェントに ADMIN_TOKEN は必要ありません。
チームメイトを招待する（ワークスペース管理者／オーナーのみ）：ブラウザーで /account/workspaces/<name>/people の下にある people タブを開くと、招待、保留中の招待の取り消し、メンバーの管理者への昇格ができます。または：
uploads invite create --email [email protected] --workspace acme
自分としてデバイスログインします（ADMIN_TOKEN でもワークスペーストークンでもありません）。メールが設定されていない場合、共有用の承認 URL が CLI に表示されます。招待されたユーザーが承認してから、uploads login を実行します。ワークスペース管理者は people タブで既存メンバーを管理者に昇格できます。他の管理者を降格または削除できるのはワークスペースオーナーのみです。
ブラウザーをまったく使えないヘッドレスマシンでは、オペレーターがトークンを直接発行し（/admin/tokens、ADMIN_TOKEN が必要。docs/admin-tokens.md を参照）、エージェントに UPLOADS_TOKEN として渡せます。または登録コード（upe_…。招待リンク／コードを使う別の方法で、相手のメールアドレスがわからない場合に便利です）を uploads login --code で交換できます。どちらも新規セットアップでの通常の手順ではありません。
生成されるトークンの有効期間はデフォルトで 90 日で、files:read と files:write が付与されます。このトークンでは、サーバーがそのユーザーのものとして記録した gh/ オブジェクトを削除できます。その記録より前にアップロードされたファイル、他のユーザーのオブジェクト、gh/ 以外のキー、および purge-expired の実行には、引き続き files:delete が必要です。スコープが不足している場合は 403 insufficient_scope が返され、不足しているスコープと https://uploads.sh/account/developers が示されます。サービス用トークン、またはアップロード元 ID のないレガシートークンは、この自身のオブジェクト用の機能を使用できません。セットアップの確認や調査は、いつでも次のコマンドで行えます：
uploads setup # shows effective configuration
uploads doctor # version + health + auth + workspace
uploads doctor --json
ワークスペーストークンにはワークスペースが埋め込まれているため（up_<workspace>_…、ワークスペースサービス用トークンの場合は ups_<workspace>_…）、--workspace を指定しなくても CLI が推測します。/account/developers では同じ形式のトークンを発行でき、有効期限を省略することもできます（その場合、無効化する方法は取り消しのみです）。管理者が発行したレガシートークンも引き続き有効です。
コマンドごとに指定する代わりに、put のデフォルト（デフォルトのリポジトリ、プレフィックス、画像幅）を一度だけ設定する方法については、「Config commands」を参照してください。
基本的なワークフロー：uploads put
1 つ以上のファイルをアップロードすると、URL とそのまま貼り付けられる Markdown が返されます。
複数のパスは並列でアップロードされます。複数ファイルの JSON は { uploads, failures } です
（いずれかが失敗した場合は終了コード 1）。単一ファイルの JSON はフラットなオブジェクトのままです。
uploads put ./shot.png --repo myorg/myapp --ref 1722 --alt "New live feed cards" --width 700
uploads put ./before.png ./after.png
uploads put --url https://cdn.example/shot.png --pr 123 --name hero.png
人間向けの出力は stderr に、URL と Markdown は stdout に出力されるため、パイプでつないだり
キャプチャしたりできます。標準入力から読み込むファイルとして - を指定します。
主なオプション（すべてのオプションについては uploads put --help を参照してください）：
| フラグ | 用途 |
|---|---|
--alt <text> | Markdown 用の代替テキスト（デフォルト：ファイル名）です。意味のある代替テキストを必ず記述してください。 |
--width <px> | ![]() の代わりに、サイズを指定した <img width=…> HTML を出力します（Markdown では画像のサイズを指定できません）。 |
--repo <owner/repo> | 自動キーのリポジトリ部分です（デフォルト：git remote、または UPLOADS_DEFAULT_REPO）。 |
--ref <id> | PR／issue／ブランチ／日付の部分です（デフォルト：今日、または UPLOADS_DEFAULT_REF）。 |
--destination <id> | 型付きルートです：screenshots | gh | f（キーのプレフィックスを設定します）。 |
--prefix <path> | キーのプレフィックスです（デフォルト：screenshots、または UPLOADS_DEFAULT_PREFIX）。 |
--key <key> | オブジェクトキーを明示的に設定します。以下の自動命名はスキップされます。 |
--name <leaf> | キーの末尾に使う整形済みファイル名とデフォルトの代替テキストを指定します（/ は不可）。--pr／デフォルトのパスは維持されます。--key とは併用できません。 |
--url <url> | この URL を取得し、その本文をアップロードします（複数回指定できます）。ファイル引数とは併用できません。このマシン上のパブリック HTTPS、または http://localhost／127.0.0.1／*.localhost が対象です。ファイル名は URL パス、または --name から取得します。それ以外のプライベート／内部ホストは拒否されます。認証情報は転送されません。 |
--replace | 厳密なキー（--key／デフォルトのパス）にある既存のオブジェクトの上書きを許可します。--pr／--issue には影響しません（または UPLOADS_OVERWRITE=1）。 |
--dry-run | アップロードせずにキーと最終的なパブリック URL を解決して出力します。キーが置き換えられるか（または、厳密なキーの場合に拒否されるか）も報告します。--gallery とは併用できません。--pr／--issue を指定していても、管理対象のコメント同期をスキップします。 |
--content-type <mime> | コンテンツタイプを上書きします（指定しない場合は拡張子から推定されます。optimize によって本文が書き換えられる場合は無視されます）。 |
--frame <id> | optimize の前にクロームを付けるオプションです：phone、browser、iphone-16-pro。 |
--frame-url <url> | --frame browser のアドレスバーに表示するテキストです。 |
--frame-fit cover|contain | 画像を画面にどのように収めるかを指定します（デフォルト：cover）。 |
--no-optimize | クライアント側での画像最適化をスキップします（デフォルト：静止画像は WebP になります）。または UPLOADS_NO_OPTIMIZE=1 を指定します。 |
--optimize-max-edge <px> | 最適化時の長辺の最大サイズです（デフォルト：2400）。 |
--optimize-quality <1-100> | 最適化時の WebP 品質です（デフォルト：85）。 |
--keep-exif | 最適化時に EXIF／XMP／ICC を保持します（デフォルト：プライバシー保護のため削除）。または UPLOADS_KEEP_EXIF=1 を指定します。 |
--no-git | git remote から --repo を導出しません（または UPLOADS_NO_GIT=1）。 |
--format human|url|markdown|json | 標準出力の形式を指定します。--json（グローバル）は json を強制します。 |
-w, --workspace <name> | ワークスペースを上書きします（環境変数およびトークンからの推定より優先されます）。 |
画像の最適化（デフォルトで有効）： PNG／JPEGなどの静止画像は、アップロード前にWebPへ再エンコードされます（長辺は2400px、品質は85に制限）。これにより、PR／issueへの埋め込みを軽量に保てます。オブジェクトキー／ファイル名の拡張子は出力形式に従います（例：shot.png → | |
…/shot.webp）。EXIF／XMPはデフォルトで削除されます（公開URLとプライバシーのため）。埋め込み画像のメタデータが必要な議論では、--keep-exifを指定してください。アニメーションGIF、SVG、動画、画像以外のファイルはそのまま扱われます。最適化後のデータが小さくならない場合は、元のファイルをアップロードします。元のファイルを無劣化でアップロードするには、--no-optimizeを使用してください。 |
フレーム（オプトイン）： --frame phone（汎用ベゼル）、--frame browser、または
--frame iphone-16-pro（コミュニティ提供のデバイス画像。~/.cache/uploads/framesにキャッシュされます）。デフォルトではフレームなしです。
キーの仕組み — パスは3種類で、追加の命名モードはありません。
| 意図 | コマンド |
|---|---|
| アップロードして、URLを取得する | uploads put ./file.png |
| 公開HTTPS URLですでにホストされている | uploads put --url https://cdn.example/file.png |
| 明示的に宛先を指定する | uploads put ./file.png --destination screenshots |
| 再アップロードする可能性がある安定したGitHub埋め込み | uploads put ./file.png --pr <num> |
安定した--prパスを使いつつ、末尾の名前を整理する | uploads put ./capture-2026-…Z.png --pr <num> --name hero.png |
| アップロード先が正確にわかっている | uploads put ./file.png --key screenshots/…/x.png |
タイムスタンプ付きのキャプチャは安定した--prキーと相性が悪いため、末尾の名前を整えるには--name hero.webpを指定してください。アップロード前に公開URLを正確に確認するには、--dry-runを使用してください。
デフォルトのputは高速な方法です。--key、--prefix、--repoは必要ありません。
gitリポジトリ内のデフォルト以外のブランチでは、引数なしのputが自動的にステージングするようになりました — attach --branchと同じキー／メタデータ（gh/<owner>/<repo>/branch/<branch>/<filename>）を使うため、そのブランチのPRが作成されると自動的に添付されます。これは、--pr／--issue／--key／--ref／--prefix／--destinationのいずれも指定されておらず、--no-gitも渡されていない場合に実行されます。これらのフラグのいずれかが指定された場合（またはデフォルトブランチ、detached HEAD、gitリポジトリ外、--no-gitの場合）は、従来の日付付きレイアウトにフォールバックします：
<prefix>/<repo-name>/<ref-or-date>/<basename>-<shorthash>.<ext> — 短いハッシュで衝突を防ぐため、ランダムな名前や別個の「名前を保持」フラグは不要です。ルートを独自に考案するよりも、--destination screenshots（または--pr／--issue付きのgh）を優先してください。ワークスペースで許可される宛先がそれらに限定されている場合があります。--keyで上書きするのは理由がある場合に限り、キーは許可されたルート内に収めてください。ブランチ上で通常の日付付きアップロードを行う場合（オプトアウト）は、--ref／--prefix／--destinationを明示的に渡してください。
出力形式 — 使用する形式を選んでください。
uploads put ./shot.png --format url # just the URL, for scripting
uploads put ./shot.png --format markdown # just the ![]()/<img> snippet
uploads put ./shot.png --json # {workspace,key,url,size,markdown}
引数なしのputでのステージングに関する注記。 デフォルト以外のブランチで引数なしのputがデフォルトでステージングするようになったため（上記参照）、自分でステージングするよう促す代わりに、それを確認する1行の注記が表示されます。人間向けモードではstderrに出力され、--format jsonでは同じレスポンスに追加の任意フィールドhintとして含まれます。
note: staged for branch fix-header — auto-comments to pull request when opened
(or run: uploads attach --promote once it exists). Use --ref/--prefix for a
plain dated upload.
同じ呼び出しでステージング時のバインド警告も発生する場合（issue #398/#400 — リポジトリがこのワークスペースにバインドされていません）、より実行可能な情報であるバインド警告がhint欄に優先して表示されます。人間向けモードでは、どちらの注記もstderrに出力されます。--quiet、環境変数のUPLOADS_NO_NUDGE=1、または設定ファイルのUPLOADS_NO_NUDGE=1（uploads config set UPLOADS_NO_NUDGE 1）で、注記を抑制できます（ステージング自体は抑制されません）。
**以前の「--prを付けて再実行」するよう促す通知（issue #393）**は、引き続き変更なく表示されます。ただし、検出可能なPRがあるときに引数なしのputが日付付きレイアウトに配置される、より限定的なケースに限ります。実際には、PRが開いているブランチで、ステージングをオプトアウトするために--ref／--prefixを明示した場合です。
note: on branch fix-header (PR #142 open) — rerun with --pr 142 for a stable
key plus a managed comment that collects this PR's media, or stage pre-PR
files with: uploads attach <file> --branch
これはベストエフォートです（最大3秒で gh pr view をすばやく検索します）。オープンなPRがない場合は、表現を汎用的な --pr <num> に広げるだけです。上記と同じ抑制が適用されます。
スクリーンショットのキャプチャ：uploads screenshot
URLまたはローカルの .html ファイルをキャプチャしてホストします。別途スクリーンショットツールを用意する必要はなく、デフォルトの方法ではブラウザーのインストールも不要です。
uploads screenshot https://uploads.sh --pr 128
uploads screenshot ./card.html --out ./card.png
uploads screenshot ./card.html --no-upload --out ./card.png
キャプチャ後のスクリーンショットは、上記で説明した put のアップロードパイプラインをそのまま共有します。--frame（任意）、デフォルトでの最適化、--pr／--issue による添付と --comment、--gallery、--meta、同じ出力形式に対応しています。また、CLI コマンドに加えて MCP ツール（screenshot）としても提供されます。
2種類のキャプチャバックエンドを、--via で選択します。
| バックエンド | 説明 | 必要なもの |
|---|---|---|
local | playwright-core 経由で、インストール済みの Chrome／Chromium を操作します | ディスク上で検出可能なブラウザー、または --cdp |
remote | uploads.sh のレンダーエンドポイント経由でサーバー側でレンダリングします | ローカルに必要なものはありません。ワークスペースの月間アップロード予算に算入されます |
--via auto（デフォルト）は、使用可能なブラウザーが見つかった場合はローカルを優先し、見つからない場合はリモートにフォールバックします。UPLOADS_SCREENSHOT_VIA=auto|local|remote（環境変数、--env-file、またはユーザー設定ファイル。詳しくは「設定コマンド」を参照）でデフォルトを永続的に設定できます。--via フラグが常に優先されます。
localhost／プライベートネットワークを対象とする場合は、ローカルのみで動作します。 --via remote（または auto がリモートにフォールバックした場合）では、実行できないリクエストを送信する代わりに、明確なエラーをすぐに返して失敗します。ローカルの .html ファイルは両方のバックエンドで動作します。リモートバックエンドにはファイルの内容がインラインで渡される（≤ 2 MiB）ため、ページが file:// または相対パスで参照するものを解決できるのは --via local の場合のみです。数値の --wait <ms>（読み込み後に固定時間待機）もローカルのみで使用できます。バックエンドに依存しない待機には、--wait load|domcontentloaded|networkidle を使用してください。
すでに実行中の Chrome に接続するには（http://host:port または ws://…）、新たに起動する代わりに --cdp <endpoint> を使用します。エージェントが Playwright MCP または agent-browser のセッションをすでに開いている場合に便利です。明示的な実行ファイルを指定するには、--browser <path>（または UPLOADS_CHROME_PATH／CHROME_PATH）を使用します。
主なオプション（すべてのオプションについては uploads screenshot --help を参照）：
| フラグ | 目的 |
|---|---|
--via auto|local|remote | キャプチャのバックエンドです（デフォルト：auto、または UPLOADS_SCREENSHOT_VIA）。 |
--browser <path> | 使用するローカルブラウザーの実行ファイルを明示します（または UPLOADS_CHROME_PATH / CHROME_PATH）。 |
--cdp <endpoint> | ブラウザーを起動せず、CDP 経由で実行中の Chrome に接続します（ローカルバックエンドのみ）。 |
--viewport <WxH[@Sx]> | サイズとデバイスのスケールファクターです（デフォルト：1280x800@2）。 |
--selector <css> | ビューポートの代わりに、指定した要素をキャプチャします。 |
--full-page | スクロール可能なページ全体をキャプチャします。 |
--max-height <px> | --full-page キャプチャの高さを CSS ピクセル単位で制限します（デフォルト：5000、0 = 制限なし）。ページが上限を超える場合は切り詰められ、stderr に注記が表示され、--format json の hint にも記載されます。--full-page が必要です。--via local と --via remote の両方に適用されます。 |
--dark / --light | prefers-color-scheme をエミュレートします（完全なメディアクエリーのエミュレーションは --via local のみです。--via remote では CSS の color-scheme プロパティのみが設定されるため、ページ独自の prefers-color-scheme クエリーは切り替わりません）。 |
--wait <load|domcontentloaded|networkidle|ms> | 待機方法を設定します（デフォルト：load）。ミリ秒数の指定はローカルのみで有効です。 |
--wait-for <js> | キャプチャ前に、この JS 式が真になるまでページ内でポーリングします（ローカルバックエンドのみ）。フレームワークのハイドレーションを待機できます。React/Next のハンドラーがアタッチされる前に load / networkidle の待機が完了するため、--eval で合成クリックを実行すると、操作に反応しない SSR DOM に対して実行されます。アプリ独自のシグナルを指定します。例：--wait-for 'window.__hydrated===true'。キャプチャのタイムアウト時にタイムアウトします。 |
--eval <js> / --init-script <file> | 待機完了後にセットアップ JS を実行するか、ナビゲーション前にスクリプトを挿入します（ローカルバックエンドのみ）。アプリがハイドレーションするまで、合成イベント（el.click()）はフレームワークのハンドラーに届きません。React/Next アプリでは、--eval と --wait-for を併用してください。 |
--out <file> | PNG をローカルファイルにも書き込み、さらにサイドカーマニフェスト（<file>.uploads.json）も作成します。このマニフェストには、キャプチャから取得したメタデータ（path / url / env / viewport、指定されている場合は --state も含む）とコンテンツハッシュが記録されます。後でこのファイルを put / attach すると、メタデータが自動的に引き継がれます。明示的に指定した --meta / --state が優先されます。--no-sidecar を参照してください。 |
--no-sidecar | --out と同じ場所に <file>.uploads.json サイドカーを書き込みません。 |
--no-upload | ホスティングをスキップします。--out が必要です（ローカルファイルのみ）。 |
--key / --pr / --issue / --comment | put と同じ送信先および添付オプションです（上記を参照）。--pr / --issue を指定すると、ハッシュを含まない安定したキーも設定されます。 |
--branch [name] | PR 作成前に、ブランチに対してステージングします。attach --branch と同じキーを使用します（下記を参照）。デフォルト以外のブランチで引数なしの screenshot を実行した場合にも、自動的にこの方法が使われます。 |
--frame / --no-optimize / --gallery / --meta | put と同じです。共有アップロードパイプラインから再利用されます。 |
Git リポジトリ内のデフォルト以外のブランチでは、単独の screenshot でも自動的にステージングされるようになりました — --branch／attach --branch と同じキー／メタデータ（gh/<owner>/<repo>/branch/<branch>/<filename>）を使い、派生した情報（path／url／env／viewport と --state）をすべて、PR が作成された後も引き継ぎます。これにより、PR がまだ存在しない段階でキャプチャするコーディングエージェントが直面する問題を解消できます。uploads screenshot <url> --out shot.png のようにシンプルなコマンドで早めにキャプチャすれば、attach --pr <num> の時点でメタデータを再指定したり、失ったりせず、そのまま引き継げます。--pr／--issue／--branch／--key／--ref／--prefix／--destination のいずれも設定されておらず、--no-git も指定されていない場合に動作します。同じフラグを指定した場合（またはデフォルトブランチ、detached HEAD、Git リポジトリ外、--no-git の場合）は、従来どおり日付付きの screenshots/<repo>/<date>/... レイアウトにフォールバックします。単独の put と同じステージング通知を表示します（上記を参照）。stderr の文言、JSON の hint フィールド、--quiet／UPLOADS_NO_NUDGE による抑制も同じです。 |
エラーとヒント： 利用可能なブラウザーがないローカルキャプチャは BROWSER_NOT_FOUND（終了コード 2）で失敗します。ヒント：--via remote を試すか、ブラウザーをインストールしてください（npx playwright install chromium）。サーバーが完了できないリモートレンダリングは RENDER_FAILED を返します。レンダリングエンドポイントのバーストレート制限は RATE_LIMITED（終了コード 4）を返します。ヒント：約60秒待ってから再試行してください。ワークスペースの月間アップロード予算を超えるリモートレンダリングでは、通常の UPLOAD_BUDGET コードとヒント（uploads usage を実行し、その後オブジェクトを削除するか上限を引き上げる）が表示されます。レンダリングと put は同じ月間カウンターを共有します。
uploads doctor は、検出されたローカルブラウザー（該当する場合）と、現在 --via auto が選択するバックエンドを報告します。
キーの導出と --state。 オブジェクトのファイル名がキャプチャした URL（ホスト＋パス）から自動導出される場合（日付付きのデフォルトレイアウト、または --pr／--issue の末尾の名前）、--state を渡すと、その値が導出されたファイル名のステムに組み込まれます。たとえば、localhost-docs-mcp.webp は localhost-docs-mcp-before.webp／localhost-docs-mcp-after.webp になります。そのため、同じ URL を --state before、続けて --state after でキャプチャすると、2つ目が1つ目を気付かれないまま上書きすることなく、別々のオブジェクトが作成されます。同じ URL を同じ state で再キャプチャした場合は、既存のオブジェクトがその場で置き換えられます（冪等な再キャプチャ）。明示的に指定した --key は、--state による組み込みの影響を受けません。上書き時は、human モードでは stderr に >> replaced existing object (same URL) と表示されます（上記の put のホットスワップ通知と同じ文言）。--format json では "replaced": true が追加され、--state を指定したキャプチャで既存のオブジェクトが置き換えられた場合は hint フィールドも追加されます。
コールアウトの焼き込み：--annotate
--annotate <file|-> は、手描きのボックス、矢印、ラベル、フリーフォームの線、マスキングをキャプチャに焼き込んでからアップロードします（JSON 仕様。ファイルパス、または stdin を表す - を指定します）。セレクターはライブページに対して解決されます。v1 ではローカルバックエンドのみが対象のため、--via remote でセレクターを含む仕様を指定すると、事前に拒否されます。
uploads screenshot http://localhost:3000 --via local --annotate ./callouts.json
仕様の形式と、既存画像に対する同等のコマンド（uploads annotate <image> --spec <file|->。ピクセルのみで、セレクターは使用しません）については、
annotate-screenshots スキルを参照してください。
カスタムメタデータと検索
すべてのオブジェクトには、クエリ可能なキーと値のメタデータ（最適化／フレームの来歴とは別）を付与できます。put 時にアップロードにタグを付け、後から検索できます。
標準の語彙
メタデータは、毎回同じ表記で入力されてこそ役立ちます。この10個のキーが共通の語彙です。ほとんどは自動で導出されるため、主な作業は独自の表記を作って置き換えないことです。
| キー | ソース | 例 |
|---|---|---|
url | 自動 — スクリーンショットの対象 | https://app.example/settings |
path | 自動 — パス名 | /settings |
env | 自動 — local のみ | local |
theme | 自動 — 強制指定時のみ | dark |
viewport | 自動 — キャプチャオプション／EXIF | 1280x800@2x |
device | 自動 — 画像の EXIF | Apple iPhone 16 Pro |
software | 自動 — 画像の EXIF | Figma |
captured | 自動 — 画像の EXIF | 2026-07-20T20:35:39 |
state | 自分で指定 — --state | before | after |
app | 自分で指定 — --app | web | ios |
path と state は特に重要な2つのキーです。習慣として、毎回両方を渡してください。 path は正しく指定する価値が最も高いキーです（エージェントが route、page、screen と誤記することが最も多いキーです。表記が近い場合は標準の表記が stderr に警告として表示され、候補も提案されますが、自動で書き換えられることはないため、元の指定を修正してください）。また、state は PR のスクリーンショットでよく使われる変更前／変更後のパターンを記録します。どちらも画像だけから推定することはできません。state に指定できる値は固定されており、before、after、empty、error、loading です（--state post のように近い値を指定すると、すぐにエラーになり、after が候補として提示されます）。
uploads screenshot はキャプチャした URL から path を自動で導出するため、追加するのは --state だけで十分です。すでに存在するファイルを uploads put／uploads attach でアップロードする場合、path の導出元がないため、--meta path=/route で明示的に指定してください。また、attach／put --pr／put --issue は、path メタデータがない状態で画像がアップロードされると、リマインダーとして stderr に tip: add --meta path=/route so this shot is findable by page を出力します（JSON の hint フィールドも追加されます）。この動作は --quiet に従います。
uploads screenshot https://app.example/settings --state before
# → stamps url, path=/settings, viewport, state=before
uploads put ./after.png --pr 123 --meta path=/settings --state after --app web
uploads find path=/settings state=after # what it was all for
派生される情報とそのタイミング
uploads screenshotは対象を把握しているため、url、path（クエリ文字列を除去）、viewport、ローカルの対象にはenv=local、--dark／--lightで指定した場合はthemeを設定します。uploads put／attachは、オプティマイザーで画像の EXIF が削除される前に、画像自体の EXIF を読み取り、許可リストにある情報を取り込みます。対象はviewport（ピクセル寸法と DPI から取得）、device、software、capturedです。uploads put／attachは、サイドカーマニフェストも読み取ります。これは、以前に同じファイルに対してscreenshot --outを実行した際に作成されたものです（<file>.uploads.json。コンテンツハッシュで照合されるため、ファイルを再生成または編集すると、静かに紐付けが失われます）。そこにある派生メタデータを取り込みます。これにより、PR の作成前にスクリーンショットを撮る場合の、撮影から添付までの間の空白を埋めます。uploads screenshot ... --out shot.png --state afterを今実行し、後からuploads attach shot.png --pr 123を実行しても、PR キー付きオブジェクトにはpath／url／env／viewport／stateが引き続き設定されます。--no-sidecarで書き込みを無効にできます。
env に設定される値は常に local のみです。prod が設定されることはありません。「localhost 以外」を根拠に推測すると、あらゆるステージング URL やプレビュー URL を誤って分類してしまうため、誤ったメタデータを付けるより付けないほうが適切です。
--keep-exif の指定にかかわらず、EXIF から取り込まれることはありません： GPS タグすべて、ボディとレンズのシリアル番号、Artist／Copyright／OwnerName、自由形式のユーザーコメント。逆に、以前は破棄されていた device と software は、検索可能なメタデータとして公開 /f/ ページに表示されるようになりました。
優先順位： 明示的な --meta／--state／--app ＞ スクリーンショットの撮影情報 ＞ サイドカーマニフェスト ＞ EXIF ＞ 未設定。24 個のキー上限に達した場合、派生キーは最初に削除されます。ユーザーが指定したキーは削除されず、キーの上限に達してもアップロードは失敗しません。
--no-auto または UPLOADS_NO_AUTO_META=1 を指定すると、派生情報の自動設定をすべて無効にできます。
ルールと予約済みキー
アップロード前にクライアント側で検証し、不正な場合は即時に失敗します。キーは ^[a-z][a-z0-9._-]{0,63}$（小文字。gh.repo のようにドットによる名前空間を使用できます）、値は印字可能な ASCII 文字で 1～512 文字です。--meta k=v はリクエストごとに最大 24 回まで繰り返し指定できます。値自体に = を含めることもできます（最初の = だけがキーと値の区切りになります）。content-sha256 と visibility は予約済みです（それぞれサーバー側で計算される値と、実際の R2 可視性制御です）。uploads attach は、慣例で予約されている独自の gh.* キーを自動的に書き込みます。以下を参照してください。
gh/… キーが付いたオブジェクトに対する meta set では、レンダリング対象のキー（path／state）が書き換えられると、管理対象の PR／issue コメントも更新されます。これはベストエフォートで行われ、メタデータの書き込みが完了した後に実行されます。成功時は refreshed the managed comment on <repo>#<num> が stderr に出力されます。ボットのエンドポイントが利用できない場合は、代わりに tip: run \uploads comment --pr ` to refresh the PR comment` が出力されます。どちらの場合も、メタデータの書き込み自体が失敗することはありません。
uploads meta get screenshots/myapp/42/settings.webp
uploads meta set screenshots/myapp/42/settings.webp path=/onboarding --delete url
uploads meta set screenshots/myapp/42/settings.webp --meta path=/onboarding # same thing
uploads list --meta app=web --meta path=/settings # ANDed, repeatable
uploads find app=web path=/settings # same filter, positional pairs
uploads find --meta app=web # --meta works here too
uploads find hero # bare name = filename substring
uploads find --name hero --meta app=web # name + meta, either order
uploads find app=web --all # follow the cursor (max 20 pages)
uploads find app=web --cursor "$CURSOR" # resume one page by hand
uploads meta keys # which meta keys exist here
uploads meta values app # values (with counts) for one key
meta set と find では、k=v を位置引数として指定する方法と、put、attach、screenshot、list で使用する繰り返し指定可能な --meta k=v のどちらの形式も使用できます。1 回の呼び出しで両方の形式を併用することもできます。find では、大文字と小文字を区別しないファイル名の部分文字列（--name <term>、または = を含まない位置引数）も指定できます。どのキーが存在するかわからない場合は、meta keys／meta values <key>（または MCP の list_metadata_keys ツール）から始めてください。キーはユーザー／エージェントが定義するもので、固定スキーマではありません。
実験的な AI ラベル（ai.*）。 デフォルトでは無効です。Flagship の
llm-file-classifier がワークスペースのスラッグ（org／workspace
のターゲティングコンテキスト）に対して有効になっている場合、サーバー経由の put によって、後から ai.kind
（screenshot|photo|diagram|document|code|ui|other）、ai.surface
（mobile|desktop|tablet|unknown）、ai.screen
（login|signup|settings|profile|dashboard|analytics|list|detail|form|search|modal|onboarding|empty|error|checkout|other）、
および ai.classifier=v5（Jev 用に画像がリサイズされた場合は v6、Luna の試行が有効な場合は v4、モデルが画像を認識しない場合は skipped）が書き込まれることがあります。ai.skip
は small、unsupported、resize_failed、または resize_timeout です。スキップされた場合、kind、surface、screen、安全性の値は書き込まれません。呼び出しに失敗すると、ai.classifier=failed と ai.error（timeout|provider_error|no_answer）が書き込まれます。同じ呼び出しで、内部用の ai.rating
（safe|suggestive|explicit）、ai.content
（none|sexual|violence|gore|drugs|hate|self_harm|other）、ai.secret
（none|api_key|password|private_key|token|connection_string|other）、および
ai.pii（none|contact|identity_document|financial|other）も書き込まれることがあります。保存される各フラグには、ai.<flag>.confidence として high（0.85 以上）、medium（0.70 以上 0.85 未満）、または low（0.50 以上 0.70 未満）も付与されます。これら 4 つのフラグは内部用です。チップとして表示されず、公開ページ、ギャラリー、フィード、埋め込み、プルリクエストのコメントにも含まれません。ai.secret が高信頼度（none 以外）、または ai.pii が高信頼度で identity_document|financial|other の場合、CLI 0.59.0 以降でアップロードされたファイルは保留状態（ai.hold=pending）になります。管理用コメントには表示されず、保留中の件数が表示されます。また、公開フィードとギャラリーでは非表示になり、その /f/ ページではサインインが求められます。ホスト型ストレージでは、承認されるまで元の URL は 404 を返し、承認後は同じ URL が復元されます。ファイルを確認してから、uploads approve --pr <n> で保留中のファイルを一覧表示し、--all ですべてを承認するか、uploads approve <key> を実行してください。ファイルに認証情報が含まれている場合は、承認するのではなく、その認証情報をローテーションし、ファイルを置き換えるか削除してください。分類器のバージョンは更新されません。ラベラーは ai.tags や ai.summary を書き込みません。古いファイルにはこれらのキーが残っていることがあります。
uploads meta get <key> または MCP の get_metadata で読み取れます。uploads find ai.kind=screenshot、uploads find ai.screen=login、または uploads find ai.secret=api_key で絞り込めます。ヘッダー内の名前やメールアドレスは ai.secret にも ai.pii にも該当しません。保存されたフラグは、後続の分類でそのキーが書き込まれるまで残ります。スキップ時に安全性の値は書き込まれません。同じバイト列を再アップロードしてもフラグはクリアされません。新しいバイト列は初期状態から始まり、そのバイト列でスキップされた場合はフラグがクリアされたままになります。ai.*
を自分で設定しないでください。このプレフィックスはサーバーが管理しており、API はクライアントからの書き込みを拒否します。ラベルは put のレスポンスには含まれず、waitUntil を通じて少し後に反映されます。署名付きアップロードは分類されません。docs/ops.md（実験的な LLM ファイル分類器）を参照してください。
検索結果はページ分割されます。該当する結果がさらにある場合、find は truncated: true と、次ページの不透明な cursor を stderr に出力します。--json では同じ cursor がペイロードに含まれます。次のページを読み取るには、--cursor を指定して渡し直してください。--all を使うと、最大 20 ページまでカーソルを自動的にたどります。カーソルは不透明な値として扱い、それを生成したクエリと組み合わせる場合にのみ送信してください。
デフォルトの screenshots/… パスでは、put は GitHub コンテキストも自動的に導出し、現在のブランチの PR（または数値の --ref）から gh.repo／gh.kind／gh.number／gh.ref を記録するため、ファイルの /f/ ページに「添付先」リンクが表示されます。これはデフォルトで有効なベストエフォート機能です。--no-auto、--no-git、または UPLOADS_NO_AUTO_META=1 で無効にできます。この自動処理では、明示的に指定した --meta gh.* が自動導出された値より優先されます。これは、下記の --pr／--issue の優先順位とは逆で、そちらでは対象自身の gh.* が常に優先されます。どちらの経路でも、ローカルの gh で PR／issue のタイトルを解決できる場合は、ベストエフォートで gh.title も記録します。解決できなくてもアップロードが妨げられることはありません。
再アップロード時の動作：既存のキーにメタデータありで再アップロードすると、そのファイルのメタデータ一式が置き換わります（マージではなく、削除してから設定します）。メタデータを一切指定せずに再アップロードした場合は、既存のメタデータは変更されず、そのまま保持されます。派生キーもここではメタデータとして扱われるため、何かを派生させる再アップロードではメタデータ一式が置き換わります。uploads meta set でメタデータを整えたキーを再アップロードする場合は、--no-auto を指定してください。
--meta（CLI）または metadata（MCP）で指定した gh.* 以外のメタデータ値は、オブジェクトの公開 /f/<key> ファイルページに表示されます。URL と同様に扱い、内部メモ、シークレット、トークン、ID、非公開パスを含めないでください。
公開メディアギャラリー
既存の複数の公開アップロードを、順序付きコレクションとして共有するにはギャラリーを使用します。ギャラリーには、API から返される不透明な公開 URL が割り当てられます。スクリプトで URL を推測してはいけません。URL を知っている人は誰でも、ギャラリーとそのメディアを閲覧できます。GitHub リポジトリが非公開でもギャラリーは非公開にならず、ギャラリーによってオブジェクトが保持期間の対象外になることもありません。
uploads gallery create --title "Settings redesign"
uploads gallery add gal_example screenshots/app/settings-before.webp screenshots/app/settings-after.webp
uploads put ./after.png --gallery gal_example --alt "Updated settings page"
uploads gallery show gal_example
uploads gallery link gal_example --github buildinternet/uploads#58
uploads gallery list --github https://github.com/buildinternet/uploads/pull/58
gallery add は、各変更の前に最新の楽観的バージョンを取得できるよう、キーを順番に処理します。--json を指定すると、安定した added 配列と failures 配列が返されるため、エージェントは部分的な失敗を安全に確認できます。ワークスペースには最大 100 個の有効なギャラリーを作成でき、各ギャラリーには最大 100 個のアイテムと 20 個の外部参照をリンクできます。ギャラリーを削除しても、削除されるのはギャラリーのレコードのみで、オブジェクトは削除されません。
必要に応じて、uploads gallery link <gallery-id> --github <owner/repo#number> でギャラリーを GitHub の issue または PR にリンクできます。CLI は、厳密な形式の https://github.com/<owner>/<repo>/issues|pull/<number> URL も受け付けます。認証済みの逆引き検索には uploads gallery list --github <coordinate-or-url> を使用します。これはメタデータのみであり、ギャラリーを非公開にしたり、不透明な識別子を変更したりすることはありません。
変更フィード
フィードは、すでに gh.repo（および任意で gh.number）のタグが付いたスクリーンショットを、新しい順に表示する公開ページです。どちらの場合も同じプロダクトであり、フィルターが 1 つ追加されるだけです。これは厳選されたギャラリーではなく、ライブクエリです。URL を知っている人は誰でも閲覧できます。
作成するものの選び方：
- ギャラリー — ファイルを選択して順序を指定します（
uploads gallery create）。 - リポジトリフィード — リポジトリ全体の最新スクリーンショットです。プロジェクト全体の共有リンクにはこちらを使用します。
- PR（または issue）フィード — 同じフィードを 1 つのプルリクエストに絞り込んだものです。レビュー担当者にその PR のみを見せる場合に使用します。
uploads feed create owner/repo
uploads feed create --repo owner/repo
uploads feed create --repo owner/repo --pr 123
uploads feed create --github owner/repo#123
uploads feed create --repo owner/repo --path /settings
uploads feed show feed_example
位置引数の owner/repo は --repo と同じです。リポジトリが異なれば、フィードも異なります。--pr と --issue は番号を受け取り、そのリポジトリ（または現在の git リモート）が必要です。--github は owner/repo#123 または GitHub の issue／PR の URL を受け取り、リポジトリを指定することもできます。--pr、--issue、--github は相互に排他的です。任意の --path は、これらのいずれとも組み合わせられます。
各ショットには、前後への移動機能と「全 N 件中の 1 件目」という件数表示がある /c/<id>/<item> も用意されています。管理対象の PR コメントを同期すると、必要に応じてその PR にスコープされたフィードが作成され（--pr と同じ冪等な作成処理）、各画像のクリック先がアイテムページに設定されます。<img src> は埋め込み URL のままです。単発の共有には、従来どおり /f/… ページを使用できます。
MCP（stdio およびホスト型）：feed_create では、上記のフラグに対応する repo と、pr／issue／github／path を指定します。feed_get には feedId を指定します。同じスコープで再度作成すると、既存の URL が返されます。
GitHub の PR または issue への埋め込み
永続的な URL、管理対象のコメント、またはその両方が必要かに応じて、2 つの方法があります。
オプション A — 安定した添付 URL（--pr / --issue）
ファイルに ハッシュを含まない安定したキー を割り当てるため、再アップロードすると同じ場所のファイルが上書きされます。また、後で編集する PR の本文に URL を直接記載しても安全です。
uploads put ./after.png --pr 123 --alt "Dashboard after"
# key: gh/<owner>/<repo>/pull/123/after.webp → stable public URL (PNG optimized to WebP)
--issue <num> は .../issues/<num>/ 配下で同じ処理を行います。<owner>/<repo> は --repo または Git リモートから取得します。--pr と --issue は --key、--ref、--prefix と併用できません（キーの構成が固定されているためです）。また、これらを相互に併用することもできません。
これらのキーは、意図的に予測しやすい構成になっています。オーナー、リポジトリ、PR または Issue の番号、ファイル名が含まれます。uploads.sh は GitHub の公開範囲を確認しないため、プライベートまたは内部リポジトリであっても、アップロードしたファイルが非公開になるわけではありません。このモードを使う前に、メディアを公開されても問題のない、推測可能な URL で共有できることを確認してください。問題がある場合は、内容を伏せるか、アップロードしないでください。
uploads GitHub App から対象リポジトリがプライベートだと確認できる場合、このキー構成は自動的に変更されます。派生可能な gh/<owner>/<repo>/... の代わりに、ブランチごと（Issue の場合はリポジトリごと）に発行されるランダムな ID を使った gh/private/<id>/... がキーになります。フラグは不要です。公開リポジトリと、App から確認できないリポジトリでは、派生可能な構成のままです。URL は引き続き認証なしでアクセスでき、長期間有効ですが、アクセス制御はありません。URL を知っている人は、uploads github rotate-prefix --branch <branch>（Issue／取り込み済みアセットの場合は --repo-level）で ID を変更するまでファイルを閲覧できます。脅威モデルの詳細は docs/private-attachments.md を参照してください。
gh で作成する PR／Issue の Markdown では、埋め込み用 URL を参照してください（CLI の --format markdown と MCP の markdown は、すでにこちらを使用します）。説明は任意です。投稿内容に含めるビジュアルがあればここに記載し、それ以外はすでに管理対象のコメントにあります。
<img width="700" alt="Dashboard after" src="https://embed.uploads.sh/default/gh/myorg/myapp/pull/123/after.webp">
GitHub 以外で長期間使える共有リンクが必要な場合は、url（ストレージホスト）を使用してください。
put --pr／--issue（および以下の uploads attach）は、検索可能なメタデータとして gh.repo／gh.kind／gh.number／gh.ref を自動的に書き込みます。そのため、uploads find gh.ref=myorg/myapp#123 または uploads list --meta gh.repo=myorg/myapp を使えば、gh/... プレフィックスがなくても、その PR／Issue に添付されたすべてのファイルを検索できます。独自のキーと値の組み合わせを追加するには --meta k=v を指定してください。--meta gh.* で値を上書きしようとしても、対象の gh.* 値が優先されます。また、ローカルの gh で取得できる場合は、実際の PR／Issue タイトルを gh.title に記録します（ベストエフォートで処理し、gh でタイトルを取得できない場合は、アップロードを失敗させずに省略します）。
オプション B — 管理対象の添付コメント（--pr／--issue を指定する場合、または comment のデフォルト）
put --pr／--issue は（attach と同様に）、特別なフラグを追加しなくても、デフォルトでアップロードすると同時に、PR／issue にマーカーで管理されるコメントを 1 件作成または更新します。紐づく PR／issue に関連付けられた、個別の gh/... 添付ファイルとすべての公開ギャラリーを、明確に分けたセクションにまとめ、利用可能なギャラリー画像を最大 3 枚、コメント内に表示します。説明文に貼り付けていないステージ済みファイルも、ここに表示されます。コメント冒頭の非表示の HTML コメント（``）を使って以前のコメントを特定し、その場で編集します。説明文や他のコメントには一切手を加えません。Bot の投稿者は uploads-sh[bot] です。ローカルの gh を使ったフォールバックでは同じマーカーを使い、アプリのインストールを促すフッターを追加します。
uploads put ./after.png --pr 123
同期をスキップする（アップロードのみ）には --no-comment を指定します。これは attach --no-comment と同じ動作です。--comment は引き続き put で受け付けられますが、何もしません。同期がデフォルトになったため不要ですが、この変更前に作成されたスクリプトとの互換性のために残されています（#537）。
アップロードが正となり、コメントの更新はベストエフォートです。gh が見つからない場合や認証されていない場合でも、アップロードは成功し、警告が表示されます。何もアップロードせずにコメントを（再）同期するには（たとえば、--pr を指定して複数回アップロードした後や、ギャラリーのリンクを追加した後）、次のスタンドアロンコマンドを使います。
uploads comment --pr 123
uploads comment --issue 45 --repo buildinternet/uploads
間違ったスクリーンショットを削除しましたか？ 対象のオブジェクトを delete してください。gh/…/pull/ または gh/…/issues/ キーを削除すると、Bot が投稿できる場合は管理対象のコメントを更新します。投稿できない場合は、uploads comment --pr <n>（または --issue）を実行するよう表示します。引き続き更新が必要な場合は、自分で comment を再実行してください。最後の添付ファイルとギャラリーがなくなると、管理対象のコメントはその場で中立的な空の状態に書き換えられます（No attachments are currently associated with this pull request.）。コメントが削除されることはなく（後からアップロードすると内容が再度表示されます）、空であることを伝えるためだけにコメントが作成されることもありません。
uploads delete gh/owner/name/pull/123/after.png # remove the asset
uploads comment --pr 123 # comment now shows the empty state
インライン画像が 16 枚を超えると、コメントでは残りが <details> のリンク一覧にまとめられるため、スクリーンショットが大量にある PR も読みやすく保たれます。共有リポジトリでは、各ワークスペースにそれぞれ専用の管理対象コメントが作成されるため（内部的に名前空間で分離されます）、別のワークスペースのコメントを上書きしません。リポジトリがどのワークスペースに紐付けられているか確認または設定するには、uploads github link（以下）を使います。
リポジトリのバインド（uploads github link／unlink／doctor）
管理コメントと Webhook による自動プロモーションでは、リポジトリとワークスペースの間で先着優先のバインドを使用します。通常、最初の comment／put --comment／プロモートの呼び出し時に暗黙的に作成されます。バインドの確認、取得、解除を行います。
uploads github link # claim the current repo for this workspace
uploads github link --repo owner/name # claim a specific repo
uploads github link --status # read-only: show the current binding, don't claim
uploads github unlink --repo owner/name # release a binding this workspace owns
uploads github doctor # check the App itself (config + webhook events)
すでにバインドされているリポジトリを取得しようとしても、既存の所有者から奪うことはできません。コマンドは既存の所有者を報告します。unlink で解除できるのは、このワークスペースが所有するバインドだけです。他のワークスペースが所有している場合は 403 を返します（代わりに、オペレーターが管理パネルから再割り当てまたは削除できます）。これらのルートがない古いサーバー／セルフホストサーバーでは、「server does not support repo bindings/GitHub App health check yet」という明確なメッセージとともに失敗します。
_バインドされていない_リポジトリの取得は、単なる先着順ではなく、認可が必要です（issue #297）。サーバーがワークスペースによる最初の取得を許可するのは、リンク済みの GitHub アカウントがリポジトリへの push 以上のアクセス権を持ち、App のインストールトークンを通じて GitHub にライブで確認できた場合に限られます。リンク済みの GitHub アイデンティティを持たないトークン（default のものを含む、レガシー／登録用／共有トークン）では、新しいリポジトリを取得できません。ただし、そのトークンにすでにバインドされているリポジトリでは、引き続き通常どおり動作します。この確認に失敗すると、取得時に claimed: false, reason: "not_authorized" が報告されます。リポジトリへの push アクセス権を持つ GitHub アカウントをリンクするか、オペレーターに管理パネルから明示的にバインドするよう依頼してください。
comment／attach --comment での not_authorized は、リポジトリが別のワークスペースにバインドされているか、バインドされておらず、このワークスペースが取得権限を持つことを確認できなかったことを意味します（上記を参照）。いずれの場合もこれは確定的な拒否であり、機能を縮退させて続行するわけではありません。この場合、他のボット投稿の失敗とは異なり、CLI はローカルの gh を使った投稿にフォールバックしません。uploads github link --status を実行して現在のバインド（存在する場合）を確認し、アクセス権を持つ GitHub アカウントがリンク済みのワークスペースに切り替えるか、オペレーターにリポジトリを明示的にバインドするよう依頼してください。
uploads github doctor は、App 独自の設定と Webhook イベントのサブスクリプションを確認します（issues と pull_request が必要です。issue_comment も推奨します。これにより、削除されたり壊れたりしたボットコメントが次の PR の push を待たずに自動修復されます）。Webhook による動作（自動プロモーション、タイトル更新、自動修復）が何も起きていないように見えるときに役立ちます。
GitHub ネイティブ添付ファイルのミラーリング（uploads ingest）
PR／issue に直接ドロップされた github.com/user-attachments/… の画像は、GitHub 独自の認証付きホスティングの背後にのみ存在し、公開 URL にはなりません。同じコマンドで、公開されている Cursor クラウドエージェントの書き換え URL（cursor.com/artifacts/c/art-*）もコピーします。Viewer（/artifacts/v/）およびログインが必要なエージェントページのリンクはスキップされます。PR に公開 /c/ URL を付けるには、Allow posting artifacts to GitHub を有効にしてください。uploads ingest --pr <n>（または --issue <n>）は説明とコメントをスキャンして該当するメディアを探し、新しいものをワークスペースにミラーリングします（インデックスに追加されますが、管理コメントには追加されません）。参照されなくなったものは切り離され、再び添付された場合は再取得せずに切り離しが解除されます。
uploads ingest --pr 123
uploads ingest --issue 45 --repo owner/name --json
リポジトリがワークスペースにリンクされていること（uploads github link）と、GitHub App がインストールされていることが必要です。そうでない場合、推測で処理せず、明確なエラーを返して失敗します。これは手動実行／バックフィルのためのエントリーポイントです。App の Webhook は、リンク済みリポジトリの本文またはコメントが作成・編集されると、同じインポートを自動で実行します。本文に公開 cursor.com/artifacts/c/art-* URL だけが含まれる場合も対象です。.uploads.yml の ingestGithubAttachments 設定は Webhook 経由の処理だけを制御し、ingest の直接実行には影響しません。
埋め込みのベストプラクティス
- 意味のある代替テキストを必ず付けてください。画像を表示しない読者や検索エンジンが参照します。
- 大きなスクリーンショットには
--widthで幅を制限し、ページを占有しないようにしてください。 - 変更前／変更後は表に並べると見やすくなります。
| Before | After | | ------------------------------------ | ----------------------------------- | | <img width="380" src="…/before.png"> | <img width="380" src="…/after.png"> | - インラインのHEREDOCよりも、本文をファイルに書き込み、
gh pr edit --body-file／gh issue comment --body-fileを使う方法をおすすめします。 - ホストは問いません。同じURLをイシュー、PRコメント、ディスカッション、通常のMarkdownドキュメントで使用できます。
- PRに添付する場合、大きな未加工の動画ファイルより、短く圧縮したクリップ（またはアニメーションキャプチャ）をおすすめします。ファイル単位およびワークスペース単位のストレージ上限が適用されます。また、数分間の非圧縮録画は、どのみちPRへの埋め込みには適しません。関連する数秒間だけにトリミングし、アップロード前に圧縮してください。
アップロードの管理
uploads list --prefix screenshots/ # list objects (key + url)
uploads list --pr 123 # everything attached to a PR
uploads list --meta app=myapp # filter by metadata (repeatable, ANDed)
uploads list --name hero --meta app=web # filename substring (+ optional meta)
uploads find app=myapp path=/settings # same filter, human-friendly positional pairs
uploads find hero # filename substring alone
uploads list --all --json # paginate fully, machine-readable
uploads meta get <key> # show an object's metadata
uploads meta set <key> k=v [k=v…] [--delete k]… # merge-set / delete metadata pairs
uploads meta set <key> --meta k=v # same, in put/list's flag spelling
uploads meta keys # discover workspace metadata keys
uploads meta values <meta-key> # distinct values for one key
uploads delete <key> # remove an object
uploads delete <key> --dry-run # show what would be deleted
uploads usage # storage / monthly upload counters (+ limits)
uploads reconcile # rebuild ledger from storage
uploads purge-expired # delete past retentionDays (if set)
uploads health # API liveness (no auth)
uploads doctor # version + health + auth + workspace + usage
uploads changelog # recent product updates + link to uploads.sh/changelog
uploads changelog --json
uploads docs # catalog of public docs
uploads docs "stage before a PR" # search
uploads docs attach # fetch one page as markdown
uploads docs --json
uploads --version
問題が発生したときは、まずdoctorを実行してください。インストール済みのCLIバージョンを報告し、APIの停止／無効なトークン／ワークスペースの不一致／ローカルURLと本番URLの違いを判別して、状況に応じたヒントを表示します。
破壊的操作のプレビュー：deleteは--dry-runをサポートしています。purge-expiredはまだサポートしていません（#78）。list／usageと保持設定でプレビューしてください。
設定コマンド
毎回フラグを渡す代わりに、共通のデフォルト値を一度設定します。
uploads config show # effective settings (token redacted)
uploads config path # resolved config file path
uploads config set UPLOADS_DEFAULT_REPO myorg/myapp
uploads config set UPLOADS_DEFAULT_WIDTH 700
uploads config init --api-url http://localhost:8787 --workspace acme --token up_acme_…
initは、渡されたキーのみを書き込みます。フラグを指定しない場合は、UPLOADS_API_URLのみを設定し、ワークスペースは意図的に設定しません。設定ファイル内のUPLOADS_WORKSPACEは、トークンに含まれるワークスペースより優先されるため、設定すると、その後のすべてのuploads loginがそのワークスペースに固定されてしまいます。固定したい場合は--workspaceを渡してください。
認識されるキー：UPLOADS_API_URL、UPLOADS_WORKSPACE、UPLOADS_TOKEN、UPLOADS_DEFAULT_PREFIX、UPLOADS_DEFAULT_REPO、UPLOADS_DEFAULT_REF、UPLOADS_DEFAULT_WIDTH、UPLOADS_NO_GIT、UPLOADS_NO_OPTIMIZE、UPLOADS_KEEP_EXIF、UPLOADS_NO_AUTO_META、UPLOADS_SCREENSHOT_VIA、UPLOADS_NO_NUDGE。
また、次の値も読み込まれます（環境変数のみ。設定ファイルのキーではありません）：UPLOADS_EMBED_PUBLIC_BASE_URL、UPLOADS_OVERWRITE。
ローカル開発
ローカルで実行中のAPIを指定します（pnpm devで:8787で起動します）。workspace:add --localで発行したトークンはlocalhostでのみ使用できます。本番トークンにはUPLOADS_API_URL=https://api.uploads.shが必要です。doctorがこの不一致を検出します。
uploads --api-url http://localhost:8787 doctor
注意事項と警告
-
アップロードしたファイルは、削除するまで公開され、事実上永久に残ります。 GitHub リポジトリの公開範囲はアクセス制御になりません。非公開／内部向けの PR や Issue の添付ファイルも公開され、
gh/<owner>/<repo>/pull|issues/<num>/<filename>のキーは予測可能です。シークレット、トークン、機密データを含む内部ダッシュボード、スクリーンショットに写った顧客の個人識別情報は、絶対にアップロードしないでください。先にトリミングまたはマスキングしてください。 -
エッジキャッシュ／デュアルホスト： 安定した
urlのレスポンスにはCache-Control: max-age=60が設定されています。GitHub ではembedUrl（キャッシュしないホスト）を使用すると、上書き内容が Camo に反映されます。PR 本文にストレージ URL を手作業で組み込むのではなく、CLI／MCP のmarkdownを使用してください。リポジトリのdocs/ops.md（デュアルパブリックホスト）を参照してください。 -
終了コード：
2は使用方法／トークン／ファイル、3は認証／ポリシー、4はネットワーク、1はその他です。--jsonは{error,code,status}を出力します。codeに基づいて分岐してください。スクリプト向けの形式（json|url|markdown）でも、失敗は標準出力に出力されます。使用方法のエラー：hint: uploads <cmd> --help。 -
エラーは短く（標準エラー出力に）表示されるため、出力を切り詰めても見失うことはありません。 引数が不足している場合は、
error:の1行、実行可能な例（uploads put ./shot.png --pr 123）、およびヒントが表示されます。コマンドのヘルプは表示されません。--jsonでは、例はexampleとして含まれます。コマンドを間違えると、エラー、did you mean: uploads <cmd>の行、ヘルプへの案内が表示されます。--jsonでは、標準出力に{error,code:"USAGE",didYouMean}が返されます。最初の行を確認し、詳細なヘルプはuploads <cmd> --helpを実行してください。 -
更新のヒント（標準エラー出力）： 成功した対話形式での実行時に、新しい npm リリースがあることが通知される場合があります（毎日確認）。
--quiet／--json／UPLOADS_NO_UPDATE=1で通知を抑制できます。 -
テレメトリー： コマンド名のみを匿名で送信します（パスやトークンは含みません）。
UPLOADS_TELEMETRY_DISABLED=1、DO_NOT_TRACK=1、またはuploads telemetry disableでオプトアウトできます。 -
レポート： ユーザーから求められた場合に限り、
uploads report "what broke"または--file ./trace.logを使用します。ログを自動送信することはありません。MCP ツール：report。 -
MCP：
uploads mcp（stdio）は CLI ツールを反映します。ホスト型 MCP はhttps://agents.uploads.sh/mcpです。ローカルファイルシステムや Git チェックアウトがなく、シェルコマンドを実行できないエージェントには、こちらを使用してください（base64 コンテンツを送信するか、ファイルがすでにパブリック HTTPS URL にある場合はcontentUrlを送信します）。ID の確認：whoami（ワークスペースとスコープを確認し、サーバーが稼働中であることも確認します）。製品の更新情報：changelog（uploads changelogと同じ。認証不要）。公開ドキュメント：search_docs（uploads docsと同じ。認証不要）。変更フィード：feed_create／feed_get（uploads feed create／feed showと同じ）。リポジトリ全体のフィードにはrepoを指定します。同じフィードを1件のプルリクエストに絞り込むには、repoとpr（またはowner/repo#123形式か GitHub URL のgithub）を指定します。Issue の場合はissueを指定します。メタデータ：get_metadata／set_metadata／find_files／list_metadata_keys（meta get／meta set／find／meta keys|meta valuesと同じ）。find_filesでは、filtersの有無にかかわらず、任意でname（ファイル名の部分文字列）を指定できます。ホスト型 MCP には、ローカルのuploads mcpサーバーにはないlist_activityとlist_repo_filesもあります。list_activityは、GitHub タグ付きの最近のアクティビティを一覧表示します。byはpull（デフォルト）またはrepoです。プル行にはgh.kind=pullタグの付いたメディアを受け取ったプルリクエストが含まれ、last_media_atの新しい順に並びます。allが true でない限り、過去90日間が対象です。プルのtitleが表示されるのは、そのリポジトリがこのワークスペースにリンクされている場合のみです。リポジトリ行には、異なるgh.repo値が含まれ、メタデータのupdated_atの新しい順に並びます。list_repo_filesには必須のrepoと、任意のpr、path、type（screenshot、video、other。PDF はother）を指定します。そのリポジトリのタグ付きファイルが、メタデータのupdated_atの新しい順に返され、urlとembedUrlも含まれます。これらの時刻はオブジェクトのuploaded-atではありません。タグのないアップロードは含まれません。どちらのツールも/c/<id>フィードを公開しません。その公開ページが必要な場合はfeed_createを使用してください。 Stdio とホスト型のputは、どちらも1回の呼び出しで複数のファイルを受け付けます。Stdio ではfilesにパスを指定します。ホスト型ではfiles: [{ filename?, contentBase64 | contentUrl, alt? }]を指定します（1回あたり最大20件）。contentBase64の場合はファイル名が必須で、contentUrlの場合は URL パスの末尾にファイル名が含まれていれば省略できます。 各項目のaltはトップレベルの値より優先されます。 結果は項目ごとの結果を含む{ uploads, failures }です。ホスト型のcontentUrlは HTTPS のみを受け付け、認証情報を転送せず、 プライベートホストや内部ホストを拒否します。GitHub のuser-attachmentsURL は公開されていないため、 フェッチに失敗します。uploads installはこのスキルとホスト型 MCP （Claude Code、Codex、Grok。CLI がないものはスキップ）および Grok/Cursor のフックをセットアップします（進捗は簡潔に表示。--verbose/--dry-runが利用可能です）。 Claude と Codex には、同じ PR 前のリマインダーがプラグイン経由で同梱されています （uploads hook pre-pr-screenshot）。CLI がPATHにない場合、フックは何もせずに終了します。ホスト型 MCP の
putにおけるコメントの同等性。 ホスト型のputツールは、pr/issue（CLI の--pr/--issueに対応し、相互排他）と、repo（owner/name。ホスト型サーバーには推測に使える git コンテキストがないため必須）を受け付け、 CLI と同じ安定したgh/…キーを取得します。pr/issueを指定すると、CLI のput --prと同様に、 管理対象のuploads-sh[bot]添付ファイルコメントがデフォルトで投稿または更新されます（#537）。 スキップするにはcomment: falseを渡します。このサーバーではボットのみが対応し、ローカルのghへの フォールバックはありません。デフォルトの同期にはfiles:readスコープが必要で、 書き込み専用トークンでは通知なしでスキップされます（comment: trueを明示するとエラーになります）。 呼び出し元が結果を PR / issue に貼り付ける場合は、生のurl/embedUrlを返すだけでなく、pr/issueを指定してください。上書きして使える安定したキーが得られ、呼び出し元が手動で埋め込む必要がある 単発のリンクではなく、収集された添付ファイルのコメントに直接追加されます。コメントの失敗によって アップロードが失敗することはありません。結果のcommentフィールドにnot_installed（リポジトリに App がインストールされていない）、not_authorized（リポジトリが別のワークスペースに紐付けられている、または紐付けがなく、このワークスペースにその権限がない）、forbidden（App はインストール済みだが、Issues/PR への書き込みアクセスがまだ承認されていない。組織の権限確認ページへのfixUrlを含む） のいずれかとして、実際の状況が返されます。ツールエラーとしてスローされることはありません。 想定外のエラーは別途commentErrorに表示されます。ホスト型 MCP の単独
commentツール。 ホスト型サーバーには、 再アップロードせずに管理対象のコメントを更新するcommentツール（{ repo, pr | issue }。git コンテキストがない同じ理由でrepoは必須）もあります。これは CLI のuploads commentに相当します。 アセットを削除した後に再同期するには、gh/…キーをdeleteしてからcommentを呼び出します。 最後の添付ファイルとギャラリーがなくなると、コメントは削除されず、空のまま新規作成されることもなく、 その場で中立的な空の状態に書き換えられます。このツールはボットのみが対応し、putのコメントフィールドと同様に、 権限がない場合はその理由を明示して処理を見送ります。このツールとpr/issueを指定したputはどちらも、 対象リポジトリの.uploads.ymlに従います（ボットの経路と同じ設定で、MCP 用の個別設定はありません。詳しくは https://uploads.sh/docs/comment-config を参照してください）。Stdio MCP の
attachにおける昇格の同等性。 Stdio のattachツールは CLI のuploads attachに対応します。prを指定すると、現在のブランチにステージされたファイルの昇格をベストエフォートで試みます。これはattach --prと同じです （結果はpromotion/promoteErrorに格納され、putのホスト型コメントフィールドと同じ形式です）。fromBranchはソースブランチを上書きし、--from-branchに対応します。noPromoteは昇格を無効にし、--no-promoteに対応します。ホスト型 MCP：ブランチのステージングと昇格。 ホスト型サーバーには ファイルシステムのパスを扱えないため
attachツールはありません。代わりにputを使用してください。# Stage pre-PR (CLI attach --branch parity). repo + branch required. put { contentBase64, filename, repo: "owner/name", branch: "feature/x", state: "after" } put { contentUrl: "https://cdn.example/after.png", repo: "owner/name", branch: "feature/x", state: "after" } # → key gh/owner/name/branch/feature-x/<filename>, gh.status=staged # Drop staged files without deleting them (CLI uploads unstage). unstage { repo: "owner/name", branch: "feature/x" } unstage { keys: ["gh/owner/name/branch/feature-x/after.png"], dryRun: true } # Promote staged files into a PR once it exists (CLI attach --promote). promote { repo: "owner/name", pr: 123, branch: "feature/x" } # optional comment: false to skip the managed comment refresh (default on) # Or attach a new file to the PR and promote that branch in one call: put { contentBase64, filename, repo: "owner/name", pr: 123, branch: "feature/x" }ホステッド MCP：ステージ済みの内容を確認する。 ホステッドサーバーには専用の
stagedツールはありません。デフォルトのbranchを設定するためのローカルな git コンテキストがないため、 呼び出し元が指定するrepo／branchが常に必要です。list_activityとlist_repo_filesは最新のタグ付きファイルを表示するものであり、 ステージ済みブランチの表示ではありません。「ステージ済みの内容は？」という質問には、既存の ツールを使って次のように答えます。list { prefix: "gh/<owner>/<repo>/branch/<branch>/" } # or find_files { filters: { "gh.branch": "<branch>" } }find_filesは各一致結果のメタデータをインラインで返すため、gh.staged-atを使えば 2 回目の呼び出しなしで新しさを確認できます。作業中のリポジトリ間でブランチ名が重複する場合は、 フィルターに"gh.repo": "<owner>/<repo>"を追加してください。バインドに関する質問（「これらは自動で添付されますか？」）には、ホステッドのrepo_link_statusツール（issue #422）を使います。repo_link_status { repo: "<owner>/<repo>" }{ binding: "self" | "other" | "none" }が返されます。"self"はこの リポジトリがこのワークスペースにバインドされており、ステージ済みファイルが自動で添付されることを意味します。"other"は別のワークスペースにバインドされており、ファイルは添付されないことを意味します。 そのワークスペース名が示されることは決してありません。"none"は リポジトリがバインドされていないことを意味します。 -
Worker 側のエージェント： このパッケージは、Worker 内でアップロード／一覧表示／削除を AI-SDK ツールとして公開するための
@buildinternet/uploads/agentのcreateUploadsWorkerFileTools()もエクスポートします。これは、日常的な PR への埋め込みではなく、サーバー上で動作するエージェント用ツールを構築する場合にのみ関係します。