uploads CLI or its MCP tools (including the hosted MCP at\nagents.uploads.sh for agents without local filesystem/git access), when you\nneed a public URL for a local file (\"upload this\", \"host this image\", \"give\nme a public URL for this file\"), when the CLI itself prints a hint or nudge\nyou need to act on (a hint field in --format json, or the stderr note\nsuggesting --pr/attach --branch), or when you need exact flags, key\nlayouts, or setup and auth details. For the when-and-how of getting a\nscreenshot or recording into a GitHub PR or issue, start with the\ngithub-screenshots skill — it defers here for CLI detail.GitHub's native image hosting (github.com/user-attachments/…) is only reachable\nthrough an authenticated browser session — there is no gh CLI or REST endpoint\nfor it. So any image URL you put in a PR/issue body written with gh … --body-file\nmust already point at something publicly hosted.
This skill covers both transports: the uploads CLI (local files, git,\nlocalhost) and the hosted MCP at https://agents.uploads.sh/mcp (bytes you\nalready have, no checkout). Both PUT to the uploads.sh API and return a stable\npublic URL plus ready-to-paste markdown. For PRs and issues the managed\nattachments comment is available on both — CLI via local gh as a fallback,\nhosted MCP bot-only.
Same product, two transports. Skills do not install a binary.
\n| Need | \nUse | \nWhy | \n
|---|---|---|
| Bytes already in context (ChatGPT attachment, base64) | \nHosted MCP put | \nfiles: [{ filename, contentBase64 }]. Pass repo + (pr | branch). No git inference. | \n
| List, find, metadata, comment, promote | \nEither | \nHosted: list, find_files, get_metadata / set_metadata, comment, promote. CLI: uploads list / find / meta / comment / attach --promote. | \n
| Local path or current-branch attach | \nCLI | \nHosted server has no filesystem and no attach tool. Use put instead. | \n
localhost / private-network screenshot | \nCLI uploads screenshot --via local | \nRemote render cannot reach your machine. | \n
| Selector annotate on a live page | \nCLI uploads screenshot --annotate --via local | \nRemote backend rejects selector-bearing specs. | \n
| Neither transport | \nStop | \nDo not treat npm install -g as the ChatGPT path. OAuth on https://agents.uploads.sh/mcp is the published remote path. | \n
CLI examples in the rest of this skill assume a checkout and the uploads\nbinary. Hosted tool contracts live under Notes and cautions (the MCP\nbullet) below.
For the common case, use uploads attach <file...>. It infers the current branch's\nPR, uploads every file under stable attachment keys (in parallel), and maintains\nthe comment by default. One bad file does not block the rest — JSON includes\nuploads and failures (exit 1 when any failed):
uploads attach ./before.png ./after.png\nuploads attach ./shot.png --issue 45 --repo buildinternet/uploads\nPass --no-comment when only stable URLs are wanted. Use put for lower-level\nnaming and output control.
Attach an already-uploaded object (issue #702). An attach argument that\ndoesn't exist on disk but resolves as a workspace object key (e.g.\nf/AbC123/shot.webp) or an uploads.sh URL (storage host, embed host, or\n/f/ page) attaches via a server-side copy instead of erroring\nfile not found — no re-download/re-upload round trip. The source's own\nderived metadata (path/url/viewport/state/…) rides along; gh.repo/\ngh.kind/gh.number/gh.ref are stamped fresh. Copy by default; --move\ndeletes the source after a successful copy. A path that exists on disk always\nwins as a local file, even if it would also parse as a key.
uploads attach f/AbC123/shot.webp --pr 123\nuploads attach https://storage.uploads.sh/<workspace>/f/AbC123/shot.webp --pr 123 --move\nStage as you go, before a PR exists. uploads attach ./shot.png --branch [name] stages files under gh/<owner>/<repo>/branch/<branch>/<filename>\ninstead of a PR/issue number — same upload path, no target flags, no comment\n(there's nothing to comment on yet). With no value, --branch resolves the\ncurrent git branch; / in the name sanitizes to -. Attach this way at every\nvisual milestone during the work, not just once at the end. Staged files carry\ngh.status=staged until promotion flips them to promoted, so\nuploads find gh.status=staged (add gh.branch=<name> to narrow) lists what's\nstill in flight. The server also stamps gh.uploader/gh.uploader-id (from\nthe token's minting user) on gh.*-tagged uploads, so\nuploads find gh.status=staged gh.uploader=<login> narrows to one\ncontributor's in-flight files.
Check what's staged: uploads staged. A dedicated read-only view —\n\"what's staged for this branch, and will it auto-attach?\" — instead of\nhand-building the find/list query above:
uploads staged # current branch, repo from gh/git remote\nuploads staged --branch feature/thing --repo owner/name\nuploads staged --format json\nSame branch/repo resolution as attach --branch (current git branch by\ndefault, worktree-safe). Human mode prints one compact line per staged file\n(filename, size, gh.staged-at, public URL), then a binding: line and\nonce the PR exists: uploads attach --promote (the promote line is omitted\nfor binding: other — promoting from a non-owning workspace would be\nrejected by the cross-tenant gate). Nothing staged prints a\nsingle zero-state line. --format json (or global --json) always emits a\nvalid document — { repo, branch, files, binding } — even with zero files;\nfiles is [], never empty stdout.
binding folds in the same repo↔workspace check the stage-time warning uses\n(see \"Repo binding\" below), so you don't have to separately reason about it:
binding.state | \nbinding.autoAttach | \nMeaning | \n
|---|---|---|
self | \ntrue | \nRepo is bound to this workspace — staged files auto-attach on PR open. | \n
none | \nfalse | \nRepo isn't linked yet — link it (uploads github link) or nothing auto-attaches. | \n
other | \nfalse | \nRepo is linked to a different workspace — these files won't auto-attach from here. | \n
unknown | \nfalse | \nBinding check failed (offline, or an older server without the route) — advisory only, never blocks the view. | \n
The none/other wording is the exact same advisory text as the\nattach --branch stage-time warning (issue #398) — one source of truth, so\nthe two surfaces never drift.
Local stdio MCP mirrors this as the staged tool (branch/repo args,\nsame { repo, branch, files, binding } shape). The hosted MCP has no\ndedicated staged tool (no git defaults) — list/find_files recipes and\nhosted put/promote with explicit repo/branch are under Notes and\ncautions (the MCP bullet) below.
Getting those files into the PR's attachments comment needs no extra step\nonce a PR exists for that branch:
\nuploads attach targeting that PR\nauto-promotes those staged files into the PR's attachment prefix before\nthe comment refresh. If that first attach has nothing new to upload, run\nuploads attach --promote (zero file arguments) to promote and refresh the\ncomment on its own; it exits 0 even when nothing was staged. Skip\nauto-promotion on a given call with --no-promote.Promotion only applies to PRs, never issues, and both paths degrade silently\n(no error) if the workspace's server doesn't support promotion yet.
\nPromotion needs the repo already bound to the workspace. Both the webhook\nand the CLI-triggered path above rely on the same repo↔workspace binding used\nby the managed comment (see \"Repo binding\" below) — any earlier successful\nattach/comment/promote call against that repo binds it implicitly, or\nuploads github link claims it explicitly. A repo that has never been\nbound and is only ever staged with --branch sees no error and no comment —\npromotion is a silent no-op at PR-open time. If you can't confirm the repo is\nalready bound, don't promise auto-attach; the zero-setup fallback that works\nregardless of binding history is running uploads attach --promote (or any\ntargeted uploads attach) once the PR exists.
Comment missing? First, give it a moment — if the App is installed and\nsubscribed to issue_comment, a deleted or mangled bot comment self-heals on\nthe next webhook delivery; don't panic-repost. If it's still missing, check\nthe repo↔workspace binding — uploads github link --status (read-only, shows\nthe binding without claiming it). See \"Repo binding\" below.
The killer feature for GitHub: --pr/--issue produce hash-free, stable keys\n(gh/<owner>/<repo>/pull/<num>/<name>), so re-uploading the same filename overwrites\nin place and the URL never changes. There is no confirmation prompt — hot-swap is\nintentional for agents and re-runs. Human mode prints\n>> replaced existing object (same URL) after overwrite; JSON has\n\"replaced\": true|false. Use --dry-run to preview: it prints\n>> would replace existing object (same URL) when the key already exists,\nwithout writing.
Every other key is strict (issue #174): an explicit --key, or the\ndefault put path with no --pr/--issue, refuses to overwrite an existing\nobject — the CLI error names the existing object's URL and tells you to add\n--replace (MCP: replace: true). Set UPLOADS_OVERWRITE=1 to restore\nalways-overwrite for those paths. --dry-run previews the refusal too:\n>> would refuse: key already exists. This never applies to --pr/--issue\nkeys, which always hot-swap regardless.
Responses include two public URLs when the\nshared dual-host setup applies:
\n| Field | \nHost (default) | \nUse for | \n
|---|---|---|
url | \nstorage.uploads.sh | \nDurable link, click-through, non-GitHub embeds | \n
embedUrl | \nembed.uploads.sh | \nGitHub PR/issue markdown (<img src> / ![]()) | \n
embedUrl is the same object with badge-style no-cache headers so GitHub Camo\nrevalidates after an overwrite. CLI/MCP markdown and the managed attachments\ncomment already prefer embedUrl. Override with UPLOADS_EMBED_PUBLIC_BASE_URL\n(empty disables; self-host set your no-cache CDN base).
https://agents.uploads.sh/mcp) and the table above. Do not install the CLI.npx:\nnpm install --global @buildinternet/uploads\nnpx @buildinternet/uploads --help\nuploads --version\nuploads … binary (as after\ninstall). Inside the uploads monorepo only, pnpm uploads … builds from\nlocal source first — do not write product/PR examples that way.\nPrefer --json or --quiet for scripted steps (keeps stderr clean and skips\noptional update-available hints).uploads doctor.gh CLI, authenticated — only for the --comment / comment features that\nwrite to a PR/issue. Plain uploads don't need it.Config lives in a user-owned file so it survives skill reinstalls:
\n~/.config/buildinternet/config # or $XDG_CONFIG_HOME/buildinternet/config\nResolution is per key, first match wins: CLI flags (--api-url, --token,\n--workspace) → UPLOADS_* environment vars → --env-file <path> →\n$BUILDINTERNET_CONFIG → the shared config file. For a one-off against a different\nAPI or workspace, just export the var or pass --env-file.
The fastest path is uploads login. Have a workspace admin invite your\nemail to a workspace first, then run it once, interactively, to sign in:
uploads login # opens a browser to approve sign-in, saves config, runs doctor\nuploads login --workspace acme # only needed if your account can access more than one\nIf the account has no workspace yet, login prompts for a name and offers one\nderived from your GitHub login as a bracketed default — press Enter to take it,\nor type your own. Nothing is prefilled when no valid, unclaimed name can be\nderived. --workspace <name> --create skips the prompt entirely, which is the\nform to use in scripts.
That's a one-time, human-in-the-loop step (device sign-in needs a browser); once the\nconfig file is written, every later uploads invocation — including from a\nnon-interactive agent — just reads the saved token. Routine agents never need\nADMIN_TOKEN.
Inviting a teammate (workspace admin/owner only): open the people tab under\n/account/workspaces/<name>/people in the browser (invite, revoke pending\ninvites, promote members to admin), or:
uploads invite create --email teammate@example.com --workspace acme\nDevice login as you (not ADMIN_TOKEN / not a workspace token). The CLI prints an\naccept URL to share if email isn’t configured. Invitee accepts, then uploads login.\nWorkspace admins can promote existing members to admin on that people tab; only the\nworkspace owner can demote or remove other admins.
For headless machines with no browser at all, an operator can mint a token directly\n(/admin/tokens, ADMIN_TOKEN-gated — see docs/admin-tokens.md) and hand it to the\nagent as UPLOADS_TOKEN, or an enrollment code (upe_…, an alternative invite-link/code path — useful\nwhen you don't have the recipient's email) can be exchanged with uploads login --code.\nNeither is the normal path for new setups.
The resulting token defaults to 90 days and files:read plus files:write; it cannot\ndelete files unless an administrator explicitly grants files:delete. Verify or inspect\nsetup at any time:
uploads setup # shows effective configuration\nuploads doctor # version + health + auth + workspace\nuploads doctor --json\nWorkspace tokens encode their workspace (up_<workspace>_…), so the CLI infers\n--workspace when you don't set it. /account/developers mints the same\ntoken shape and can skip expiry (revoke is then the only off switch). Legacy\nadministrator-minted tokens remain valid.\nSee \"Config commands\" for setting put defaults (default repo, prefix, image\nwidth) once instead of per-command.
uploads putUpload one or more files and get back URL(s) plus ready-to-paste markdown.\nMultiple paths upload in parallel; multi-file JSON is { uploads, failures }\n(exit 1 when any failed). Single-file JSON stays a flat object.
uploads put ./shot.png --repo myorg/myapp --ref 1722 --alt \"New live feed cards\" --width 700\nuploads put ./before.png ./after.png\nHuman output goes to stderr; the URL and markdown to stdout, so you can pipe or\ncapture them. Use - as the file to read from stdin.
Key options (uploads put --help for all):
| Flag | \nPurpose | \n
|---|---|
--alt <text> | \nAlt text for the markdown (default: filename). Always write meaningful alt text. | \n
--width <px> | \nEmit sized <img width=…> HTML instead of ![]() (markdown can't size images). | \n
--repo <owner/repo> | \nRepo segment of the auto key (default: git remote, or UPLOADS_DEFAULT_REPO). | \n
--ref <id> | \nPR/issue/branch/date segment (default: today, or UPLOADS_DEFAULT_REF). | \n
--destination <id> | \nTyped root: screenshots | gh | f (sets key prefix). | \n
--prefix <path> | \nKey prefix (default: screenshots, or UPLOADS_DEFAULT_PREFIX). | \n
--key <key> | \nSet the object key explicitly; skips the auto-naming below. | \n
--name <leaf> | \nClean filename for the key's leaf + default alt (no /); keeps the --pr/default path. Not with --key. | \n
--replace | \nAllow overwriting an existing object on a strict key (--key/default path). No effect on --pr/--issue (or UPLOADS_OVERWRITE=1). | \n
--dry-run | \nResolve + print the key and final public URL without uploading; reports if the key would replace (or, on a strict key, be refused). Not with --gallery; skips the managed comment sync even with --pr/--issue. | \n
--content-type <mime> | \nOverride the content type (else inferred from extension; ignored when optimize rewrites the body). | \n
--frame <id> | \nOpt-in chrome before optimize: phone, browser, iphone-16-pro. | \n
--frame-url <url> | \nAddress bar text for --frame browser. | \n
--frame-fit cover\\|contain | \nHow the shot fills the screen (default: cover). | \n
--no-optimize | \nSkip client-side image optimization (default: still images → WebP). Or UPLOADS_NO_OPTIMIZE=1. | \n
--optimize-max-edge <px> | \nMax long edge when optimizing (default: 2400). | \n
--optimize-quality <1-100> | \nWebP quality when optimizing (default: 85). | \n
--keep-exif | \nKeep EXIF/XMP/ICC when optimizing (default: strip for privacy). Or UPLOADS_KEEP_EXIF=1. | \n
--no-git | \nDon't derive --repo from the git remote (or UPLOADS_NO_GIT=1). | \n
--format human\\|url\\|markdown\\|json | \nControl stdout. --json (global) forces json. | \n
-w, --workspace <name> | \nOverride workspace (wins over env and token inference). | \n
Image optimization (default on): PNG/JPEG and similar still images are re-encoded to\nWebP (long edge capped at 2400px, quality 85) before upload so PR/issue embeds stay\nlean. The object key/filename extension follows the output (e.g. shot.png →\n…/shot.webp). EXIF/XMP is stripped by default (public URLs + privacy); pass\n--keep-exif when the discussion needs the embedded image metadata. Animated GIF,\nSVG, video, and non-images are left alone; if the optimized payload is not smaller,\nthe original is uploaded. Use --no-optimize when you need lossless originals.
Frames (opt-in): --frame phone (generic bezel), --frame browser, or\n--frame iphone-16-pro (community device art, cached under\n~/.cache/uploads/frames). Default is no frame.
How keys work — three paths, no extra naming modes:
\n| Intent | \nCommand | \n
|---|---|
| Just upload it, give me a URL | \nuploads put ./file.png | \n
| Explicit typed destination | \nuploads put ./file.png --destination screenshots | \n
| Stable GitHub embed I might re-upload | \nuploads put ./file.png --pr <num> | \n
Stable --pr path but a clean leaf | \nuploads put ./capture-2026-…Z.png --pr <num> --name hero.png | \n
| I know exactly where it goes | \nuploads put ./file.png --key screenshots/…/x.png | \n
Timestamped captures break stable --pr keys — pass --name hero.webp to keep a\nclean leaf. Use --dry-run to preview the exact public URL before uploading.
Default put is the fast path; you don't need --key, --prefix, or --repo.\nInside a git repo, on a non-default branch, a bare put now stages\nautomatically — same key/metadata as attach --branch\n(gh/<owner>/<repo>/branch/<branch>/<filename>), so it auto-attaches to that\nbranch's PR when one opens. This fires whenever none of\n--pr/--issue/--key/--ref/--prefix/--destination is set and\n--no-git isn't passed; any of those flags (or the default branch, detached\nHEAD, not being in a git repo, or --no-git) falls back to the classic\ndated layout:\n<prefix>/<repo-name>/<ref-or-date>/<basename>-<shorthash>.<ext> — the short\nhash prevents collisions without random names or a separate \"preserve name\"\nflag. Prefer --destination screenshots (or gh with --pr/--issue) over\ninventing roots — workspaces may allowlist only those destinations. Override\nwith --key only when you have a reason, and keep the key under an allowed\nroot. Pass --ref/--prefix/--destination explicitly for a plain dated\nupload on a branch (the opt-out).
Output formats — pick what you'll consume:
\nuploads put ./shot.png --format url # just the URL, for scripting\nuploads put ./shot.png --format markdown # just the ![]()/<img> snippet\nuploads put ./shot.png --json # {workspace,key,url,size,markdown}\nThe bare-put staging note. Since a bare put on a\nnon-default branch now stages by default (see above), it prints a one-line\nnote confirming that instead of nudging you to do it yourself — human mode\nwrites it to stderr, --format json adds it as an additive optional hint\nfield on the same response:
note: staged for branch fix-header — auto-comments to pull request when opened\n(or run: uploads attach --promote once it exists). Use --ref/--prefix for a\nplain dated upload.\nIf the same call also trips the stage-time binding warning (issue #398/#400\n— the repo isn't bound to this workspace), that warning takes the hint\nslot instead (it's the more actionable of the two); both still print on\nstderr in human mode. Suppress the note (not the staging itself) with\n--quiet, UPLOADS_NO_NUDGE=1 (env), or UPLOADS_NO_NUDGE=1 in the config\nfile (uploads config set UPLOADS_NO_NUDGE 1).
The old \"rerun with --pr\" nudge (issue #393) still fires, unchanged, for\nthe narrower case a bare put still lands on the dated layout with a\ndetectable PR — in practice, an explicit --ref/--prefix opting out of\nstaging while a PR is open for that branch:
note: on branch fix-header (PR #142 open) — rerun with --pr 142 for a stable\nkey plus a managed comment that collects this PR's media, or stage pre-PR\nfiles with: uploads attach <file> --branch\nIt's best-effort (a quick gh pr view lookup, bounded to 3s) — no open PR\njust widens the wording to a generic --pr <num>. Same suppression as above.
uploads screenshotCapture a URL or a local .html file and host it — no separate screenshot\ntool needed, and no browser install required for the default path:
uploads screenshot https://uploads.sh --pr 128\nuploads screenshot ./card.html --out ./card.png\nuploads screenshot ./card.html --no-upload --out ./card.png\nAfter capture, a screenshot shares the exact put upload pipeline described\nabove: optional --frame, optimize-by-default, --pr/--issue attachment +\n--comment, --gallery, --meta, and the same output formats. It also\nships as an MCP tool (screenshot) alongside the CLI command.
Two capture backends, selected with --via:
| Backend | \nWhat it is | \nNeeds | \n
|---|---|---|
local | \nDrives an already-installed Chrome/Chromium via playwright-core | \nA discoverable browser on disk, or --cdp | \n
remote | \nRenders server-side via the uploads.sh render endpoint | \nNothing local; counts against the workspace's monthly upload budget | \n
--via auto (the default) prefers local when a usable browser is found,\nelse falls back to remote. Set a persistent default with\nUPLOADS_SCREENSHOT_VIA=auto|local|remote (env, --env-file, or the user\nconfig file — see \"Config commands\"); the --via flag always wins.
localhost/private-network targets are local-only. With --via remote\n(or auto falling back to remote) these fail fast with a clear error instead\nof sending a request that could never work. Local .html files work on both\nbackends — the remote backend receives the file's contents inline (≤ 2 MiB),\nso anything the page references via file:// or relative paths only resolves\nwith --via local. A numeric\n--wait <ms> (fixed settle delay after load) is also local-only; use\n--wait load|domcontentloaded|networkidle for a backend-agnostic wait.
Use --cdp <endpoint> to attach to a Chrome that's already running\n(http://host:port or ws://…) instead of launching a new one — handy when\nan agent already has a Playwright MCP or agent-browser session open.\n--browser <path> (or UPLOADS_CHROME_PATH / CHROME_PATH) points at an\nexplicit executable.
Key options (uploads screenshot --help for all):
| Flag | \nPurpose | \n
|---|---|
--via auto\\|local\\|remote | \nCapture backend (default: auto, or UPLOADS_SCREENSHOT_VIA). | \n
--browser <path> | \nExplicit local browser executable (or UPLOADS_CHROME_PATH / CHROME_PATH). | \n
--cdp <endpoint> | \nAttach to a running Chrome via CDP instead of launching one (local backend only). | \n
--viewport <WxH[@Sx]> | \nSize + device scale factor (default: 1280x800@2). | \n
--selector <css> | \nCapture one element instead of the viewport. | \n
--full-page | \nCapture the full scrollable page. | \n
--max-height <px> | \nCap on --full-page capture height in CSS px (default: 5000; 0 = uncapped). A page over the cap is clipped, with a note to stderr and a --format json hint. Requires --full-page; applies on both --via local and --via remote. | \n
--dark / --light | \nEmulate prefers-color-scheme (full media-query emulation on --via local only — --via remote only sets the CSS color-scheme property, so a page's own prefers-color-scheme queries won't flip). | \n
--wait <load\\|domcontentloaded\\|networkidle\\|ms> | \nSettle strategy (default: load); a millisecond count is local-only. | \n
--wait-for <js> | \nPoll this JS expression in the page until truthy before --eval and capture (local backend only). Bridges framework hydration — load/networkidle settle before React/Next attach handlers, so a synthetic click in --eval hits the inert SSR DOM. Express the app's own signal, e.g. --wait-for 'window.__hydrated===true'. Times out with the capture timeout. | \n
--eval <js> / --init-script <file> | \nRun setup JS after settle / inject a script before navigation (local backend only). Synthetic events (el.click()) won't reach framework handlers until the app hydrates — pair --eval with --wait-for on React/Next apps. | \n
--out <file> | \nAlso write the PNG to a local file, plus a sidecar manifest (<file>.uploads.json) with this capture's derived metadata (path/url/env/viewport, plus --state if given) and a content hash. A later put/attach of that exact file picks the metadata back up automatically — explicit --meta/--state still win. See --no-sidecar. | \n
--no-sidecar | \nDon't write the <file>.uploads.json sidecar alongside --out. | \n
--no-upload | \nSkip hosting; requires --out (local file only). | \n
--key / --pr / --issue / --comment | \nSame destination and attachment options as put (see above); --pr/--issue also give a stable, hash-free key. | \n
--branch [name] | \nStage against a branch, pre-PR — same key as attach --branch (see below); this is also what a bare screenshot on a non-default branch does automatically. | \n
--frame / --no-optimize / --gallery / --meta | \nSame as put — reused from the shared upload pipeline. | \n
Inside a git repo, on a non-default branch, a bare screenshot now stages\nautomatically too — same\nkey/metadata as --branch/attach --branch\n(gh/<owner>/<repo>/branch/<branch>/<filename>), carrying every derived fact\n(path/url/env/viewport, plus --state) through to the PR once it\nopens. This is what closes the gap a coding agent hits capturing before the PR\nexists: capture early with a plain uploads screenshot <url> --out shot.png,\nand the metadata rides along instead of being re-stated (or lost) at\nattach --pr <num> time. Fires whenever none of\n--pr/--issue/--branch/--key/--ref/--prefix/--destination is set\nand --no-git isn't passed; the same set of flags (or the default branch,\ndetached HEAD, not being in a git repo, or --no-git) falls back to the\nclassic dated screenshots/<repo>/<date>/... layout. Prints the same\nstaging note as bare put (see above) — same stderr wording, same JSON\nhint field, same --quiet/UPLOADS_NO_NUDGE suppression.
Errors and hints: a local capture with no usable browser fails with\nBROWSER_NOT_FOUND (exit 2) — hint: try --via remote, or install a\nbrowser (npx playwright install chromium). A remote render that the server\ncan't complete returns RENDER_FAILED. A burst rate limit on the render\nendpoint returns RATE_LIMITED (exit 4) — hint: wait ~60s and retry. A\nremote render over the workspace's monthly upload budget surfaces the usual\nUPLOAD_BUDGET code and hint (uploads usage, then delete objects or raise\nlimits) — renders and puts share one monthly counter.
uploads doctor reports which local browser (if any) was detected and which\nbackend --via auto would currently pick.
Key derivation and --state. Whenever the object's filename is\nauto-derived from the captured URL (host + path) — the default dated\nlayout, or the --pr/--issue leaf name — passing --state folds it into\nthat derived filename stem —\nlocalhost-docs-mcp.webp becomes localhost-docs-mcp-before.webp /\nlocalhost-docs-mcp-after.webp — so capturing the same URL twice with\n--state before then --state after produces two distinct objects instead\nof the second silently overwriting the first. Re-capturing the same URL with\nthe same state still replaces the existing object in place (idempotent\nre-capture). An explicit --key is unaffected by --state folding. On\noverwrite, human mode prints >> replaced existing object (same URL) to\nstderr (same wording as put's hot-swap note, above) and --format json\nadds \"replaced\": true, plus a hint field when a --state capture\nreplaced an existing object.
--annotate--annotate <file|-> bakes hand-drawn boxes, arrows, labels, freeform\nstrokes, and redactions onto the capture before it's uploaded (JSON spec, a\nfile path or - for stdin). Selectors resolve against the live page — the\nlocal backend only in v1, so a selector-bearing spec on --via remote is\nrejected up front:
uploads screenshot http://localhost:3000 --via local --annotate ./callouts.json\nFor the spec format and an existing-image equivalent (uploads annotate <image> --spec <file|->, pixel-only, no selectors), see the\nannotate-screenshots skill.
Every object can carry queryable key-value metadata (distinct from optimize/frame\nprovenance) — tag uploads at put time, then find them later.
\nMetadata is only useful if it is spelled the same way every time. These ten keys\nare the agreed vocabulary; most are derived for you, so the main job is not\nto fight them by inventing a different spelling.
\n| Key | \nSource | \nExample | \n
|---|---|---|
url | \nauto — screenshot target | \nhttps://app.example/settings | \n
path | \nauto — pathname | \n/settings | \n
env | \nauto — local only | \nlocal | \n
theme | \nauto — only when forced | \ndark | \n
viewport | \nauto — capture opts / EXIF | \n1280x800@2x | \n
device | \nauto — image EXIF | \nApple iPhone 16 Pro | \n
software | \nauto — image EXIF | \nFigma | \n
captured | \nauto — image EXIF | \n2026-07-20T20:35:39 | \n
state | \nyou — --state | \nbefore | after | \n
app | \nyou — --app | \nweb | ios | \n
path and state are the two highest-value keys — pass both, every time,\nas a habit. path is the key most worth getting right (the one agents most\noften misspell as route, page, or screen — a near-miss warns on stderr\nand suggests the canonical spelling, but is never rewritten for you, so fix it\nat the source) and state captures the before/after pattern that dominates\nPR screenshots — nothing can infer either one from the image alone. state is\na closed set: before, after, empty, error, loading (a near-miss like\n--state post fails fast and suggests after).
uploads screenshot derives path automatically from the captured URL, so\nyou only need to add --state. uploads put/uploads attach of an\nalready-existing file have nothing to derive path from, so pass it\nexplicitly with --meta path=/route — and attach/put --pr/put --issue\nprint a tip: add --meta path=/route so this shot is findable by page on\nstderr (plus a JSON hint field) when an image lands with no path meta, as\na reminder (respects --quiet).
uploads screenshot https://app.example/settings --state before\n# → stamps url, path=/settings, viewport, state=before\n\nuploads put ./after.png --pr 123 --meta path=/settings --state after --app web\nuploads find path=/settings state=after # what it was all for\nuploads screenshot knows its own target, so it stamps url, path\n(query stripped), viewport, env=local for a local target, and theme\nwhen --dark/--light forced one.uploads put/attach read the image's own EXIF before the optimizer\nstrips it, promoting an allowlist: viewport (from pixel dimensions and DPI),\ndevice, software, captured.uploads put/attach also read a sidecar manifest left by a prior\nscreenshot --out of that exact file (<file>.uploads.json, content-hash\nguarded — a regenerated/edited file silently loses it) and merge in its\nderived metadata. This closes the capture-then-attach gap where a shot is\ntaken before a PR exists: uploads screenshot ... --out shot.png --state after\nnow, uploads attach shot.png --pr 123 later, still gets path/url/env/\nviewport/state on the PR-keyed object. Disable writing it with\n--no-sidecar.env is only ever local. It is never set to prod — inferring that from \"not\nlocalhost\" would mislabel every staging and preview URL, and wrong metadata is\nworse than none.
Never promoted from EXIF, regardless of --keep-exif: all GPS tags, body and\nlens serial numbers, Artist/Copyright/OwnerName, and free-form user\ncomments. Note the flip side: device and software were previously discarded\nand now become queryable metadata that renders on the public /f/ page.
Precedence: explicit --meta/--state/--app > screenshot capture facts >\nsidecar manifest > EXIF > unset. Derived keys are also dropped first if the\n24-key cap is reached — your own keys are never dropped, and a full key\nbudget never fails an upload.
Turn the whole derived tier off with --no-auto or UPLOADS_NO_AUTO_META=1.
Validated client-side, fail-fast, before uploading: key\n^[a-z][a-z0-9._-]{0,63}$ (lowercase, dot-namespacing allowed, e.g. gh.repo);\nvalue 1–512 printable ASCII characters; --meta k=v may repeat up to 24 times per\nrequest; a value may itself contain = (only the first = splits key from value).\ncontent-sha256 and visibility are reserved (server-computed / the real R2\nvisibility gate, respectively). uploads attach writes its own gh.*\nreserved-by-convention keys automatically — see below.
meta set on a gh/…-keyed object also refreshes the managed PR/issue comment\nwhenever the write touches a rendered key (path/state) — best-effort, after\nthe metadata write already lands. On success it prints\nrefreshed the managed comment on <repo>#<num> to stderr; if the bot endpoint\nis unavailable it prints tip: run \\uploads comment --pr
uploads meta get screenshots/myapp/42/settings.webp\nuploads meta set screenshots/myapp/42/settings.webp path=/onboarding --delete url\nuploads meta set screenshots/myapp/42/settings.webp --meta path=/onboarding # same thing\nuploads list --meta app=web --meta path=/settings # ANDed, repeatable\nuploads find app=web path=/settings # same filter, positional pairs\nuploads find --meta app=web # --meta works here too\nuploads find hero # bare name = filename substring\nuploads find --name hero --meta app=web # name + meta, either order\nuploads meta keys # which meta keys exist here\nuploads meta values app # values (with counts) for one key\nmeta set and find accept pairs in either spelling: positional k=v, or the\nrepeatable --meta k=v that put, attach, screenshot, and list use. Both\nforms can appear in one call. find also takes a case-insensitive filename\nsubstring (--name <term>, or a bare positional without =). When you don't\nknow which keys exist, start with meta keys / meta values <key> (or the MCP\nlist_metadata_keys tool) — keys are user/agent-defined, not a fixed schema.
On the default screenshots/… path, put also auto-derives GitHub context and\nstamps gh.repo/gh.kind/gh.number/gh.ref from the current branch's PR (or\na numeric --ref), so the file's /f/ page shows an \"Attached to\" link. This is\non by default and best-effort; disable it with --no-auto, --no-git, or UPLOADS_NO_AUTO_META=1.\nOn this auto path an explicit --meta gh.* overrides the auto-derived value — the\nopposite of the --pr/--issue precedence below, where the target's own gh.* always wins.\nBoth paths also stamp gh.title with the resolved PR/issue title when local gh\ncan resolve one — best-effort, never blocks the upload if it can't.
Re-upload semantics: re-uploading to an existing key with metadata replaces\nthat file's entire metadata set (delete-then-set, not a merge); re-uploading with\nno metadata at all preserves the existing metadata untouched. Derived keys\ncount as metadata here, so a re-upload that derives anything replaces the set —\npass --no-auto when re-uploading a key whose metadata you curated with\nuploads meta set.
Non-gh.* metadata values supplied via --meta (CLI) or metadata (MCP) render\non the object's public /f/<key> file page. Treat them like the URL itself:\ndon't put internal notes, secrets, tokens, IDs, or private paths in them.
Use galleries when several existing public uploads should be shared as one ordered collection.\nA gallery has an opaque, API-returned public URL; do not derive one in scripts. Anyone who\nknows the URL can view the gallery and its media. GitHub repository visibility does not make\nit private, and a gallery does not pin objects against retention.
\nuploads gallery create --title \"Settings redesign\"\nuploads gallery add gal_example screenshots/app/settings-before.webp screenshots/app/settings-after.webp\nuploads put ./after.png --gallery gal_example --alt \"Updated settings page\"\nuploads gallery show gal_example\nuploads gallery link gal_example --github buildinternet/uploads#58\nuploads gallery list --github https://github.com/buildinternet/uploads/pull/58\ngallery add processes keys sequentially so it obtains a current optimistic version before\neach mutation. With --json, its stable added and failures arrays make partial failures\nsafe for agents to inspect. A workspace may have up to 100 active galleries; each gallery permits up to 100 items and 20 linked external references. Deleting a gallery removes only its gallery record—not the objects.
Optionally link a gallery to a GitHub issue or PR with uploads gallery link <gallery-id> --github <owner/repo#number>. The CLI also accepts strict https://github.com/<owner>/<repo>/issues|pull/<number> URLs. Use uploads gallery list --github <coordinate-or-url> for the authenticated reverse lookup. This is metadata only: it does not make a gallery private or change its opaque identity.
Two ways, depending on whether you want a durable URL, a managed comment, or both.
\n--pr / --issue)Gives the file a hash-free, stable key so re-uploads overwrite in place and the\nURL is safe to hard-code in a PR body you'll edit later:
\nuploads put ./after.png --pr 123 --alt \"Dashboard after\"\n# key: gh/<owner>/<repo>/pull/123/after.webp → stable public URL (PNG optimized to WebP)\n--issue <num> does the same under .../issues/<num>/. The <owner>/<repo> comes\nfrom --repo or the git remote. --pr/--issue can't be combined with --key,\n--ref, or --prefix (the key layout is fixed), and are mutually exclusive.
These keys are deliberately predictable: they include the owner, repository, PR or\nissue number, and filename. uploads.sh does not check GitHub visibility, so a private\nor internal repository does not make the uploaded file private. Before using this\nmode, confirm the media is safe for a public, guessable URL; otherwise redact it or do\nnot upload it.
\nIf the uploads GitHub App can see that the target repo is private, this key layout\nchanges automatically: the key becomes gh/private/<id>/..., where <id> is a random\nid minted per branch (or per repo, for issues), instead of the derivable\ngh/<owner>/<repo>/.... No flag needed — public repos, and repos the App can't see,\nkeep the derivable layout. The URL is still unauthenticated and durable, not\naccess-controlled — anyone who obtains it can read it until you rotate the id with\nuploads github rotate-prefix --branch <branch> (or --repo-level for issues/ingested\nassets). See docs/private-attachments.md for the full threat model.
Then reference the embed URL in the PR/issue markdown you write with gh\n(CLI --format markdown / MCP markdown already do this):
<img width=\"700\" alt=\"Dashboard after\" src=\"https://embed.uploads.sh/default/gh/myorg/myapp/pull/123/after.webp\">\nKeep url (storage host) when you need a durable share link outside GitHub.
put --pr/--issue (and uploads attach, below) writes gh.repo/gh.kind/\ngh.number/gh.ref as queryable metadata automatically, so uploads find gh.ref=myorg/myapp#123 or uploads list --meta gh.repo=myorg/myapp finds\neverything attached to that PR/issue without needing the gh/... prefix. Add\n--meta k=v extras for your own pairs on top — a --meta gh.* override loses\nto the target's own gh.* values. It also stamps gh.title with the real\nPR/issue title when resolvable via local gh (best-effort; omitted rather\nthan failing the upload if gh can't resolve one).
--pr/--issue, or comment)put --pr/--issue (like attach) uploads and creates/updates a single marker-owned comment on the PR/issue by default — no separate flag needed. It keeps loose gh/... attachments and every public gallery linked to that PR/issue in clearly separate sections, with up to three available gallery images inline. It finds its own prior comment via a hidden marker and edits it in place — it never touches the description or other comments:
uploads put ./after.png --pr 123\nPass --no-comment to skip the sync (upload only), matching attach --no-comment. --comment is still accepted on put as a no-op — it's redundant now that the sync is the default, kept only for scripts written before this changed (#537).
The upload is authoritative; the comment is best-effort — if gh is missing or\nunauthenticated, the upload still succeeds and you get a warning. To (re)sync the\ncomment without uploading anything (e.g. after several --pr uploads or gallery links), use the standalone command:
uploads comment --pr 123\nuploads comment --issue 45 --repo buildinternet/uploads\nRemoved the wrong screenshots? delete the object(s) and re-run comment to\nre-sync. When the last attachment and gallery are gone, the managed comment\nis rewritten in place to a neutral empty state (No attachments are currently associated with this pull request.) — it is never deleted (a later upload\nrepopulates it) and never created just to say it's empty:
uploads delete gh/owner/name/pull/123/after.png # remove the asset\nuploads comment --pr 123 # comment now shows the empty state\nPast 16 inline images, the comment collapses the rest into a <details> link\nlist so a heavily-screenshotted PR stays readable. Each workspace gets its own\nmanaged comment on a shared repo (namespaced under the hood) instead of\nclobbering another workspace's — use uploads github link (below) to see or\nset which workspace a repo is bound to.
uploads github link / unlink / doctor)The managed comment and webhook auto-promotion use a first-claim-wins binding\nbetween a repo and a workspace, normally created implicitly by your first\ncomment/put --comment/promote call. Inspect, claim, or release it:
uploads github link # claim the current repo for this workspace\nuploads github link --repo owner/name # claim a specific repo\nuploads github link --status # read-only: show the current binding, don't claim\nuploads github unlink --repo owner/name # release a binding this workspace owns\nuploads github doctor # check the App itself (config + webhook events)\nClaiming an already-bound repo never steals it — the command reports the\nexisting owner instead. unlink only releases a binding this workspace owns;\nit 403s if another workspace owns it (an operator can reassign or remove it\nfrom the admin panel instead). On an older/self-hosted server without these\nroutes they fail with a clear \"server does not support repo bindings/GitHub\nApp health check yet\" message.
Claiming an unbound repo is authorized, not just first-come (issue #297):\nthe server only lets a workspace make that first claim when its linked\nGitHub account has push (or higher) access to the repo, checked live against\nGitHub via the App's installation token. A token with no linked GitHub\nidentity — a legacy/enrollment/shared token, including default's — can\nnever claim a new repo, though it keeps working normally on any repo already\nbound to it. Claiming reports claimed: false, reason: \"not_authorized\" when\nthis check fails; link a GitHub account with push access to the repo, or ask\nan operator to bind it explicitly from the admin panel.
not_authorized on comment/attach --comment means either the repo is\nbound to a different workspace, or it's unbound and this workspace couldn't\nbe verified as entitled to claim it (see above). Either way it's a hard\ndecline, not a degrade — the CLI does not fall back to posting via local\ngh in this case, unlike other bot-post failures. Run uploads github link --status to see the current binding (if any), switch to a workspace with a\nlinked GitHub account that has access, or ask an operator to bind the repo\nexplicitly.
uploads github doctor checks the App's own configuration and webhook event\nsubscriptions (needs issues + pull_request; issue_comment is\nrecommended so a deleted/mangled bot comment self-heals instead of waiting\nfor the next PR push) — useful when webhook-driven behavior (auto-promotion,\ntitle updates, self-healing) seems to be silently doing nothing.
uploads ingest)Images someone drops straight into a PR/issue via github.com/user-attachments/…\nonly exist behind GitHub's own authenticated hosting — they're never public\nURLs. uploads ingest --pr <n> (or --issue <n>) scans the description and\ncomments for that media, mirrors any new ones into the workspace (indexed,\nnot added to the managed comment), and detaches ones no longer referenced —\na reattached one un-detaches without a re-fetch:
uploads ingest --pr 123\nuploads ingest --issue 45 --repo owner/name --json\nRequires the repo be linked to the workspace (uploads github link) and the\nGitHub App installed — otherwise it fails with a clear error rather than\nguessing. This is the manual/backfill entry point; the .uploads.yml\ningestGithubAttachments knob only gates the automatic webhook path and has\nno effect on running ingest directly.