What's new in uploads.sh — platform updates and CLI releases, newest first.
Atom feeduploads changelog prints the latest product updates in your terminal, then a
link to the full list at uploads.sh/changelog. Agents get the same
feed from --json or the MCP changelog tool.
uploads changelog
uploads changelog --limit 10
uploads changelog --json
put and attach accept non-media files: PDF, zip, gzip, MOV, and text (plain, markdown, CSV, JSON, logs). They upload as-is, skip image optimization, and appear in the managed comment as links. Requires the matching platform release.put and attach accept SVG and XML (image/svg+xml, application/xml, text/xml) on a storage lane once its public host is verified to serve them behind a sandboxing Content-Security-Policy. An unverified lane keeps 415ing these types. The managed comment embeds SVG as <img>. Requires the matching platform release.REGISTRY KV write once before giving up, so a stale prior-day ok: true record can't survive a one-off KV hiccup and keep the SVG/XML sandboxing gate open.containsActiveMarkup): event-handler attribute matching no longer false-positives on ordinary attributes like online=/once=, and entity-encoded evasions (javascript:, SMIL <set attributeName="onclick">) are now rejected. The actual security control remains the sandboxing CSP on the serving lane; this filter is defense in depth.put --help now says uploads are public and to scrub secrets out of logs, JSON, and other text before uploading.<svg> tag's width/height attributes (or viewBox as a fallback), so image.width/image.height server metadata — and the managed GitHub comment's sizing — now cover SVGs the same as other image types.The upload allowlist now covers PDF, zip, gzip, MOV, and text files (plain, markdown, CSV, JSON, logs) alongside images and video. Test reports, Lighthouse output, build logs, and bundles get the same stable URLs and appear in the PR's attachments comment as links. MOV uploads and plays on its file page. Size caps are the plan's file cap; MOV uses the video cap.
Uploads are public. The text families — logs, CI JSON, env dumps — are the ones that tend to carry secrets in practice, so scrub those before uploading.
SVG and HTML stay out: served inline, either can run script on our storage origin. SVG support is planned behind a sandboxing header.
424b343: Follow branch renames when promoting staged uploads. The CLI reads git branch -m steps from the branch reflog and registers them with the server, so attach --pr, attach --promote, and files staged by attach --branch, put, or screenshot are still found after a rename. Promote output notes when a rename was followed. --from-branch remains the manual fallback for a branch renamed or deleted without a later uploads run.
The stdio MCP attach tool now matches the CLI: with pr, it promotes the current branch's staged files and reports promotion/promoteError, with new fromBranch and noPromote arguments.
uploads attach --pr <num> --from-branch <old-name> to promote staged files after a branch is renamed or deleted.As of today, GitHub CLI supports attachments. gh 2.99 adds a repeatable
--attach flag for images and video on issues, pull requests, and comments.
Read GitHub's changelog.
Good news. If you have a PR open and a screenshot to drop on it, use gh.
We've updated our docs and agent skills to say so. Media attached with gh
still lands in Uploads: with the GitHub App
installed, attachments in PR and issue text are imported into the workspace,
so they show up in the Screenshots view next to CLI captures.
What it doesn't change:
uploads put
on a branch stages the file, and the PR gets one attachments comment the
moment it opens.--attach needs gh on a machine that has the file. The hosted MCP server
at agents.uploads.sh takes files as base64 or a URL and posts them to the
PR, so ChatGPT, Claude.ai, and cloud agents can attach too.uploads screenshot takes the shot, --annotate
marks it up, before/after pairs render side by side, and every capture
carries metadata you can search with uploads find or browse on the
Screenshots page across projects.image.width/image.height, small assets render at natural size instead of being upscaled into blurry tiles, and consecutive captionless icons flow on one line instead of stacking one per row.usage, reconcile, and purge_expired MCP tools failing with an output validation error. The two-lane storage work added sharedBytes, sharedObjects, and storageBudgetBasis to the usage payload, and the usage route separately stamps scopes, plan, and storage, but the MCP output schema didn't list them, so the strict (additionalProperties: false) schema rejected real responses.health ping with whoami.uploads put --url and MCP contentUrl fetch a file and upload it. Filename comes from the URL path when omitted. The CLI and stdio MCP also fetch http://localhost (hosted MCP does not).uploads mcp) and the hosted remote to the official MCP Registry as sh.uploads/mcp.uploads usage is BYO-bucket aware: when a workspace's own bucket is active, the storage meter counts only hosted-storage residue (the number the quota actually enforces) and a note explains that storage in your own bucket is unmetered.uploads doctor now reports the workspace's storage lanes: hosted storage vs your own bucket, how many previous lanes still serve old files, and whether the active lane is healthy — read from a new bearer-safe summary on the usage endpoint. Against older servers it keeps the honest "not checked from the CLI" line.findFiles now returns an opaque cursor and
accepts one back. The new findFilesAll follows that cursor, up to a page cap.
uploads find and uploads list --meta gained --cursor and --all. The
find_files MCP tool takes and returns the same cursor.list/listAll now skip the server's per-key metadata hydration when the
caller didn't request metadata: true, instead of fetching it and throwing
it away.mintWorkspaceToken now accepts an
optional idempotencyKey so a retried request replays the original one-time
token instead of minting a duplicate.put now accepts an optional idempotencyKey
so a retried request replays the original response instead of writing a
duplicate object.uploads.sh) instead of the retired auth.uploads.sh subdomain. Since #731 the auth endpoints are served at <origin>/api/auth, so an api.<domain> base now derives its parent (api.uploads.sh → uploads.sh). Explicit --auth-url / UPLOADS_AUTH_URL still override, and auth.uploads.sh continues to serve during the transition, so pinned configs keep working.
You can now point any workspace at your own storage bucket. Files upload straight to a bucket you own, serve from your own domain, and stay yours — uploads.sh keeps only encrypted credentials and a pointer, never a copy.
We're starting with Cloudflare R2; more S3-compatible providers are on the roadmap. Available to every workspace, on any plan, and storage in your own bucket is unmetered — the plan's storage limit only counts files on hosted storage.
Setup takes a few minutes from your workspace's Settings → Storage page: create an R2 bucket, scope an API token to it, give it a custom domain, and paste the three into one form. Verifying and saving never moves anything — your bucket sits ready until you click Use this bucket, and switching is instant and reversible either way: existing files keep serving from wherever they already are, only new uploads follow the active bucket.
The setup guide has the full walkthrough, the serving matrix (custom domain vs signed-only), and what's different on your own bucket. Plan limits are covered in Plans & limits.
X-Retry-After header (capped at ~10s) when present.uploads install registers the hosted MCP server with Claude Code, Codex, and Grok independently. A CLI that is not installed is skipped instead of failing the MCP step, so the rest of the install still completes.screenshot gains --wait-for <js> (local backend), a hydration-aware gate that polls a JS expression in the page until truthy before --eval and capture (issue #715). The load/networkidle settle strategies fire before a React/Next app hydrates, so a synthetic el.click() in --eval hit the still-inert server-rendered DOM with no handler attached — silently doing nothing. Expressing the app's own "interactive" signal (e.g. --wait-for 'window.__hydrated===true') closes that gap; a predicate that never becomes truthy fails with RENDER_FAILED instead of capturing the un-ready page. --wait-for is local-only (rejected up front on --via remote, like --eval). --eval/--wait-for help and the CLI docs now warn that synthetic events won't reach framework handlers until hydration.adoptLinkedFiles, issue #701) now also runs on the local-gh fallback comment path, not just the bot-managed one. uploads comment --pr/--issue (and the attach-time comment sync) scans the PR/issue body and comments for pasted uploads.sh URLs via local gh and adopts any that resolve to a file in the current workspace, before rendering the comment. Same semantics as the bot path: copy never move, additive metadata, idempotent re-adoption, no migration into private prefixes, and a lone adopted image with nothing else to consolidate doesn't trigger a fresh comment on its own (it still heals an existing one).faa961c: uploads attach --pr <num> <key-or-url>... now accepts already-uploaded objects, not just local paths: an argument that doesn't exist on disk but resolves as a workspace object key or an uploads.sh URL (storage host, embed host, or /f/ page) is attached via a server-side copy instead of erroring file not found. The source's own derived metadata (path/url/viewport/state/…) rides along; gh.repo/gh.kind/gh.number/gh.ref are stamped fresh. Copy by default; --move deletes the source after a successful copy. A path that exists on disk always wins as a local file. The hosted MCP promote tool gained a matching keys argument alongside its existing branch-staged sweep.
cdb6505: .uploads.yml gained an adoptLinkedFiles key (on by default for bound repos): when a PR body or comment references an uploads.sh file URL that was pasted in directly — rather than uploaded via --pr/attach --branch — the webhook now adopts it into that PR/issue's attachment context, so it gets pairing, dedupe, and screenshots-page grouping automatically. Only files already in the repo's own bound workspace are adopted; links to any other workspace's files are silently ignored. A lone adopted image with nothing else to consolidate doesn't trigger a managed comment on its own.
e62b445: Make bare put/screenshot PR-aware (issue #700). Three changes:
uploads attach --pr 1250 f/abc123.webp. It's now surfaced in the hint
field for --format json and in the local stdio MCP put/screenshot
tool responses, not only on stderr.put/screenshot on a git branch that
maps to exactly one open PR now behaves as if --pr <n> had been passed —
stable key, managed comment sync — instead of the previous branch-staging
default. Opt out per-call with --no-pr, or globally with
UPLOADS_NO_AUTO_PR=1 (env or config file). Never fires outside a git
checkout, on the default branch, with --no-git, when any explicit
destination flag is set, or when no single open PR can be resolved — those
cases fall back to the existing branch-staging/dated-layout behavior
unchanged.uploads hook pre-pr-screenshot now also suggests promoting
staged-but-unattached files (uploads attach --promote --pr <num>) when it
detects them ahead of gh pr create, alongside its existing "stage
screenshots first" advisory.uploads put <file> --pr 12) instead of a <N> placeholder.[bot] accounts and images under 200px on either side are skipped. A new .uploads.yml key, ingestBotAttachments: true, re-admits bot media on the webhook path; ingestGithubAttachments: false turns importing off per repo or per workspace as before.put and screenshot print an advisory stderr note when a path-tagged upload has no repo/app context and only a local origin — it would land in the screenshots page's "local dev" bucket. Suggests running from the project repo or passing --app. Suppressed by --quiet, --no-git, and the no-nudge config./account/developers. Tokens start with up_<workspace>_ and last 90 days by default (up to 1 year). The CLI reads the workspace from the token.uploads config help no longer mentions a separate API key. Workspace tokens are up_<workspace>_….POST /v1/tokens accepts ttlSeconds: null for a workspace token that does not expire. /account/developers offers that as No expiry. Revoke is the only off switch.--comment flag from help examples. Comment sync is already the default.uploads CLI is not on PATH.uploads screenshot --full-page now caps capture height at 5000px by default (both the local and remote backends). A page over the cap is clipped, with a note to stderr and a --format json hint. Add --max-height <px> to raise the cap, or --max-height 0 for the old uncapped behavior.endpoint override (files-sdk#133) and binding-path list() metadata (files-sdk#134).2697e69: Fix uploads completion zsh producing a script that could not complete anything.
The generated _arguments call was missing line continuations between its
option specs, so zsh ended the call after the first spec and tried to execute
the remaining ones as commands — Tab printed a wall of command not found
instead of completing. Short flags now also pair with their long form's
summary, so the menu no longer reads Show help (short).
uploads completion --help now also covers installation properly. Saving the
script into an fpath directory does nothing when compinit -C reuses a cached
dump, which is common under Oh My Zsh, so the help gives the compdef binding
that works regardless of startup order.
Regenerate an installed script after upgrading:
uploads completion zsh > ~/.zsh/completions/_uploads
085da59: Per-key file operations — upload PUT, head/metadata GET, metadata PATCH, and DELETE — now use the canonical /v1/workspaces/:workspace/files/<key> paths (#613). The server has shared identical handlers across both surfaces since #636, so behavior is unchanged; the legacy paths keep working.
List, find, and facets stay on the legacy /v1/:workspace/files wildcard until the bearer list/search response shape is reconciled with the canonical one.
47091c1: List, find, and facets complete the CLI's move to the canonical /v1/workspaces/:workspace/files surface (#613) — no legacy /v1/:workspace paths remain in the client. The client's own return shapes are unchanged: list adapts the canonical {files, prefixes, cursor} envelope back to {items, cursor} (and still honors metadata: true opt-in), and findFiles now calls files/search, which is non-paginated (server cap 100, narrowable with limit), so its cursor is always null.
f4de70a: Private GitHub repos get randomized, unguessable attachment URL prefixes (#631). Public repos are unchanged. Requires no flags; applies automatically when the uploads GitHub App can see the repo is private. uploads github rotate-prefix [--branch <b> | --repo-level] rotates a prefix on demand, moving its attachments to a new URL and re-syncing the managed comment.
8770eaa: CLI workspace-scoped github/comment, github/promote, github/link, github/repo-link, github/health, usage, and galleries requests now use the canonical /v1/workspaces/:workspace/... paths instead of the legacy /v1/:workspace/... wildcard (#613). The old paths keep working server-side, so this is a client-only move.
Files operations (get/set/list/facets/etc.) stay on the legacy wildcard for now — the canonical files vertical doesn't yet cover uploads, /sign, or :key metadata, and its list/search response shape differs from the bearer one.
Note: the canonical github/comment route requires the files:write scope, where the legacy path also accepted files:read. Default-minted CLI tokens carry read+write, so this is transparent for normal use; a manually-minted read-only token will now get a 403 from uploads comment.
eef5e70: Derive repo metadata (owner/name from the git remote) on put and screenshot, suppressed by --no-git.
Every screenshot the CLI captures now has a page of its own. Screenshots in your workspace groups captures by the page they came from — grouped by project, with before/after pairs kept together — so you can find last week's capture without scrolling a flat file list.
The CLI pitches in too: uploads screenshot derives a stable name from the
URL (plus --state for before/after variants), so re-capturing the same page
replaces the old shot instead of piling up near-duplicates.
screenshot now folds --state into the derived object name (e.g. app.example-settings-before.png / -after.png), so capturing the same URL with different states no longer silently overwrites the earlier capture (issue #618). Folding is skipped when an explicit --key is given. screenshot also now prints the same >> replaced existing object (same URL) note put prints when an upload replaces an existing object, in both human output and as a hint in --format json. markdown on workspaces without a public URL; the CLI now falls back to a plain-text note naming the uploaded key.actor_not_authorized managed-comment decline (issue #297 control 2, workspace opt-in actor-on-PR gate): like not_authorized, the CLI surfaces the server's guidance instead of falling back to a local gh post.uploads doctor now reports on bring-your-own-bucket storage status. Since
GET /me/workspaces/:name/storage requires a signed-in session and the CLI
only ever holds a workspace token, doctor honestly says it can't check
storage mode from the CLI today and points to the web settings page instead
of guessing.f259e69: Filename search and metadata facet discovery on the token-authed API, CLI, and both MCP tool sets (issue #528).
uploads find / list accept --name <term> (and a bare name on find) for case-insensitive substring matching on object keys, alone or with meta filters. uploads meta keys and uploads meta values <key> expose the workspace's actual metadata vocabulary. The stdio and hosted MCP tools mirror this with optional name on find_files and a new list_metadata_keys tool.
e2d9fd2: Adopt MCP spec 2026-07-28 by replacing the hand-rolled protocol core in
@buildinternet/uploads/mcp with @modelcontextprotocol/server. The stdio
server (uploads mcp) now speaks both the modern 2026-07-28 revision and
the legacy 2025-era initialize handshake, negotiated per session.
Breaking: the McpServer interface exported from the @buildinternet/uploads/mcp
subpath no longer has a handleLine(line) method — the SDK owns JSON-RPC
dispatch and transport, so a consumer driving handleLine directly must move
to the SDK's transport instead (e.g. serveStdio). createMcpServer also
gains a validator option for the injected JSON Schema validator; callers
outside this repo's own CLI and worker builds need to pass one explicitly.
uploads put
now answers error: put requires at least one file followed by
uploads put ./shot.png --pr 123, so the fix is copy-pasteable instead of one
--help away. Applies to put, attach, find, delete, meta, gallery, comment,
screenshot, annotate, and config set, plus the unknown-subcommand errors. With
--json the example comes back as an example field on the error payload.uploads put,
find, delete, meta, gallery, screenshot, annotate, and
config set all did this. Each now prints one error: line naming what is
missing, plus the uploads <cmd> --help hint, so trimmed output still carries
the reason and --json gets a real error payload. An unknown config
subcommand does the same instead of dumping the config help.meta set and find
now accept --meta k=v, the same spelling put, attach, screenshot, and
list use, alongside the positional k=v form. An unknown command answers
with a "did you mean" suggestion — uploads set-metadata points at
uploads meta set — instead of a help dump that never mentioned meta. That
output is also short now, so an agent that pipes through tail still sees the
error; with --json it comes back as { error, code, didYouMean } on stdout.put <file> --pr/--issue --format json now includes comment/commentError in the single-file JSON payload, matching the multi-file batch shape (#541).put --pr/--issue now syncs the managed attachments comment by default (same as attach), so uploads on a quiet PR show up without a webhook event or --comment. Opt out with --no-comment; --comment is kept as a no-op alias..uploads.yml (image width, inline cap, caption fields, note)gh (posted under your GitHub account instead of the uploads-sh bot), the comment footer notes that the GitHub App hasn't been installed for the repo yet, with a link to install it.uploads install handles missing or too-old Node tooling more clearly: one npx/npm preflight before skill steps, identical failures collapsed to a single skills: line, and install guidance (Node 22+ / npm 7+, Claude Code) instead of "run manually: npx …" when the binary is missing. On Windows, execFile retries via the shell so npm .cmd shims resolve instead of reporting ENOENT.ffe9ea7: uploads config init with no flags no longer seeds UPLOADS_WORKSPACE=default
into the config file. That entry outranked the workspace encoded in your token,
so it pinned every later uploads login to default no matter which workspace
the token was actually minted for. It now seeds only UPLOADS_API_URL; pass
--workspace <name> to set one explicitly.
uploads login on an account with no workspace yet now offers a name derived
from your GitHub login as a bracketed default (… (lowercase, hyphens) [octocat]:). Press Enter to accept it, or type anything else to override. When
no name can be derived — no linked GitHub account, or the derived name is
reserved or already taken — the prompt is exactly as before.
uploads admin invite create now requires --workspace. It previously defaulted
to the communal default workspace, so a forgotten flag issued an invite
granting files:read/files:write on the shared tenant — and because
enrollment redemption mints a token without creating an org membership, the
recipient would not have appeared in any member list while still reading and
writing that workspace's files. Pass the workspace explicitly; naming default
still works.uploads install no longer reports an already-registered MCP server as a
failure. claude mcp add refuses to overwrite an existing entry and exits
non-zero, so re-running install (or update, which re-runs it) ended with a
raw Command failed: … dump and exit 1 for anyone already set up. That case is
now reported as mcp: already configured, exits 0, and prints the
claude mcp remove <name> command needed to re-register with a new token —
the one thing the existing entry will not pick up on its own.uploads annotate and uploads screenshot --annotate for baking hand-drawn boxes, arrows, labels, freeform strokes, and redactions onto screenshots, plus the annotate-screenshots skill documenting the spec format and workflow.ffa1860: Put and head responses now name the two metadata bags apart. provenance
carries the object's R2 upload labels (client, source-name,
content-sha256) — the content that used to sit under metadata on these two
endpoints only. metadata now means the queryable tags everywhere, matching
what it already meant on getMetadata, patchMetadata, and
list({ metadata: true }).
A put echoes the tags it stored, including server-derived pairs the client
never sent such as gh.uploader, so confirming what landed no longer takes a
second round trip. The field is absent when the put wrote no tags of its own,
since that case leaves any existing tags untouched. A plain head returns no
queryable metadata at all — that tier is a separate store and takes a separate
read, so call getMetadata(key).
PutResult.provenance and HeadResult.provenance are new; HeadResult.metadata
is gone. Code reading metadata off a put or head for provenance must move to
provenance.
path was in fact
supplied. put --pr/put --issue and attach decided whether to nudge by
reading the API's put response metadata field, which echoes the object's R2
provenance bag (client, source-name, content-sha256) and never the
queryable tags — so the tip printed on every image, including ones uploaded
with an explicit --meta path=, and the same text landed in the hint field
of --format json. The check now reads the metadata each upload actually sent
(--meta pairs, a screenshot --out sidecar manifest, and derived image
facts), resolved per file.uploads hook pre-pr-screenshot for the shared pre-PR screenshot reminder. Claude and Codex plugins run it; uploads install hooks wires Grok and Cursor.uploads --help now lists every command the catalog marks essential.
Membership had two sources of truth — the essential flag in the command
catalog and a separate hardcoded array in the help renderer — and they had
drifted, so screenshot was flagged essential but never appeared. The catalog
is now the only source of truth; the array orders the list and nothing more,
and a mismatch in either direction fails loudly instead of silently hiding a
command.uploads update. It upgrades the globally installed CLI, then re-runs
uploads install so the agent skills and the MCP registration match the new
version. When the CLI is already current it still refreshes them, because they
drift on their own. The upgrade step detects npm, pnpm, and bun global
installs, and refuses to overwrite a workspace checkout or an npx cache. The
existing update hint and help banner now name uploads update.gh fallback for the managed attachments comment (used when the GitHub App bot path is unavailable or unauthorized) now collapses duplicate marker comments the same way the bot path does: it collects every comment carrying the workspace's exact namespaced marker, patches the oldest, and best-effort deletes the rest, swallowing delete failures. Previously this path only ever patched the first match it found, so a duplicate left by a concurrent-create race (two uploads attach runs racing before either found an existing comment) never healed. Legacy unnamespaced marker comments are still adopt-only and are never deleted.uploads comment (and the comment MCP tool) now always hunts for the managed comment's marker instead of patching its cached comment id, so a duplicate comment left by a create race is collapsed on the next explicit resync rather than surviving until the id cache expires. Attach and screenshot syncs keep the cached-id fast path.ee057cc: meta set refreshes the managed PR/issue comment when it changes path or state on a gh/…-keyed attachment, so backfilled metadata shows up without waiting for the next attach. If the bot endpoint is unavailable it prints a uploads comment hint instead of failing the write. The server side also self-heals duplicate managed comments left by a create race: the oldest is kept and updated, extras are deleted on the next sync (issue #470).
5fbf612: uploads screenshot (CLI and local MCP) now stages against the current git branch by default when run on a non-default branch with no --pr/--issue/--branch target — same key and metadata as attach --branch, so derived facts (path/url/env/viewport, plus --state) survive through to the PR once it opens instead of being lost at attach time. Opt out with --no-git, or an explicit --ref/--prefix/--destination.
attach and put --pr/put --issue now print a tip: add --meta path=/route so this shot is findable by page (stderr, plus a JSON hint field) when an uploaded image ends up with no path metadata. Respects --quiet.
5d29337: uploads screenshot --out now also writes a sidecar manifest (<file>.uploads.json) recording the capture's derived metadata (path/url/env/viewport, plus --state if given) with a content hash. A later uploads put/attach of that exact file automatically picks the metadata back up — explicit --meta/--state still win, and a regenerated or edited file silently loses its sidecar. Disable with --no-sidecar.
meta set
comment re-sync (path/state) added in #471, in the CLI README, the
uploads-cli skill, and the GitHub App docs page.uploads usage shows the workspace plan (Free or Pro) when the API reports it,
alongside storage/upload meters. Free is not unlimited — caps appear on the
meters. Additive plan field on the usage response.session.cliVersion fresh so
the account Sessions list can show your current CLI version after upgrades
without re-login.license
field and the repository LICENSE file now read Apache-2.0.uploads comment (or a put --comment) rewrites the existing comment in place to "No attachments are currently associated with this pull request." — it is never deleted (a later upload repopulates it) and is never created just to say it is empty. uploads comment reports this as a "cleared" message rather than "updated (0 files)".put on a non-default git branch now stages to the branch prefix by default — same key and gh.* metadata as attach --branch, so it auto-attaches to that branch's PR when one opens. Only applies when none of --pr/--issue/--key/--ref/--prefix/--destination is set and --no-git isn't passed; the default branch, detached HEAD, not being in a git repo, --no-git, or any of those explicit flags keeps the classic dated layout. Prints a one-line staging note (same suppression as the existing bare-put nudge), and the stage-time binding warning from attach --branch now fires on this path too. Local stdio MCP put mirrors the same default.attach --branch now warns at stage time when the repo won't auto-attach staged files at PR open — either because it isn't linked to your workspace yet, or because it's linked to a different workspace. Advisory only: staging always succeeds regardless. Suppressed by --quiet, UPLOADS_NO_NUDGE=1 (env or config), same as the bare-put nudge (#396).uploads staged [--branch <name>] [--repo <owner/name>] [--format json]: a read-only view of what's staged for a branch (attach --branch / bare put on a non-default branch) and whether it will auto-attach once a PR opens. One list call against the branch staging prefix plus the repo-binding check (files:read only, no new server surface); --format json always prints a valid document, even with nothing staged. Also available as the staged tool on the local stdio MCP server.put with no --pr/--issue/--key on a non-default git branch now prints a one-line nudge toward --pr <num> or attach --branch. Human mode writes it to stderr; --format json adds an additive hint field. Suppress with --quiet, UPLOADS_NO_NUDGE=1, or config UPLOADS_NO_NUDGE=1.uploads attach --branch now reminds you that staged files auto-attach to the branch's PR when it opens (or via uploads attach --promote), reinforcing the stage-as-you-go loop for agents./ path from managed attachment comment captions (still stored and searchable).path and state metadata — a screenshot tagged --state before on /settings renders as /settings · before beneath the image instead of just its filename. Attachments without that metadata render exactly as before.uploads login works with
no flags for every account — the approval page lists the workspaces you can use,
creates one if you have none, and refuses to approve a workspace your account
can't reach instead of reporting success and failing in the terminal.
--workspace becomes an optional preselect; --workspace <name> --create still
provisions by name.963ea12: Add a canonical metadata vocabulary for uploads. screenshot now derives
url, path, env, theme and viewport from the capture, and put
promotes an allowlist of image EXIF (viewport, device, software,
captured) into queryable metadata before stripping it from the bytes. New
--state and --app flags, and matching MCP params, cover what the CLI
cannot derive. uploads find path=/settings state=after is the payoff.
The MCP metadata description previously suggested page and resolution;
it now names the canonical keys and points at path as the one to search by.
Two behavior changes worth reading before upgrading:
device and software come from EXIF that was previously discarded, and
promoted metadata renders on the public file page. GPS coordinates, serial
numbers and personal-name tags are never promoted.--no-auto when re-uploading
a key whose metadata you curated with uploads meta set.Opt out of the whole derived tier with --no-auto or UPLOADS_NO_AUTO_META=1.
uploads github link) another org's GitHub repo the App is installed on, letting it post or deface the uploads-sh[bot] comment there. Claiming an unbound repo now requires the calling workspace's linked GitHub account to have push (or higher) access to that repo, verified live via the App's installation token. An unauthorized claim gets the same soft { posted: false, reason: "not_authorized" } / { claimed: false, reason: "not_authorized" } decline as posting to an already-bound repo — never a server error, and the CLI never falls back to gh for it. Repos bound before this check shipped keep working unchanged.stateProp, appProp,
canonicalMetaFromArgs, metadataArgWithCanonical) from the /mcp entry
point so the hosted MCP server can reuse them instead of keeping its own copy
of the metadata tool description.uploads login now mints a full-scope token by default (files:read, files:write, files:delete) so the CLI's own delete command works out of the box; pass --scopes to narrow it. uploads doctor now shows the token's scopes and hints when files:delete is missing.insufficient_scope API error surfaces as "token lacks the files:delete scope" with a hint to re-run uploads login (or mint with --scopes), instead of a bare "forbidden".gh.status=staged, and server-side promotion flips the staged original to gh.status=promoted. In-flight staged media becomes a plain equality query: uploads find gh.status=staged (narrow with gh.branch=<name> or gh.repo=<owner/name>).uploads github doctor now reports issue_comment as a recommended (non-gating) webhook event subscription. When the GitHub App is otherwise healthy but not subscribed to issue_comment, doctor prints a note: line and still exits 0 — required events (issues, pull_request) are unaffected. --json output gains recommendedEvents and missingRecommendedEvents; older servers whose health payload predates these fields are handled gracefully.9e06ef6: Warn on stderr when the linked dev CLI's dist/ predates src/ (or is missing), so testing a change against the linked uploads binary can no longer silently exercise stale compiled code — a false alarm that's bitten local debugging more than once. The check is a no-op for published npm installs (no src/ tree ships in the tarball) and costs at most a couple of directory walks.
Also update the put --comment MCP tool description and the comment MCP tool description, which still described posting "via local gh auth" as the primary path — both now match the CLI's own help text: the server-side bot comment (uploads-sh[bot]) is tried first, with local gh as a fallback.
c82a14d: Managed GitHub attachments comment now ends with a short "Add media" hint pointing readers at uploads put <file> --pr <N> --comment (or --issue <N>) and the docs, so anyone viewing the comment can learn how to contribute media themselves.
uploads github doctor to check whether the GitHub App is subscribed to the webhook events uploads.sh needs (issues, pull_request). A missing subscription previously failed silently — the App's ping stayed green while webhook auto-promotion and title-cache invalidation quietly did nothing.uploads github unlink to release a workspace's GitHub repo binding (self-serve counterpart to uploads github link), and point github link's already-bound-elsewhere output at the remedy.uploads attach --branch <name> now rejects a value that looks like a file
(an existing path on disk, or a name with a media/document extension like
.png/.pdf) instead of silently swallowing it as the branch name. Fixes
uploads attach --branch shot.png staging under a branch literally named
"shot.png" — use uploads attach shot.png --branch (auto-detect the current
branch) or uploads attach --branch <name> shot.png instead. Ordinary dotted
branch names like v1.2 or release/1.2 are unaffected.gh path when the server declines a comment post with not_authorized (cross-tenant repo binding) — surface the decline with a hint to uploads github link --status instead, since a silent gh fallback would just work around the server-side gate with the human's own credentials.uploads attach --branch [name] and uploads screenshot --branch [name] stage files against a git branch before a pull request exists — for coding agents working a branch that hasn't opened a PR yet. Keys land under gh/<owner>/<repo>/branch/<branch>/<filename> with gh.repo/gh.kind=branch/gh.branch/gh.staged-at metadata; no managed comment is created since there's no PR/issue to comment on yet.uploads attach now auto-promotes branch-staged attachments (attach --branch) into a PR's attachment prefix the first time you attach to that PR, before refreshing the managed comment — no extra step needed once a PR opens for a branch you staged files against. Use uploads attach --promote (no file arguments) to promote and refresh the comment without uploading anything new, or --no-promote to opt out of the automatic behavior. Promotion talks to a new server endpoint and degrades silently (never fails the attach) when that endpoint isn't available yet.<details> list) and use a per-workspace marker so two workspaces sharing a repo no longer clobber each other's comment (legacy comments are adopted and migrated automatically). Adds uploads github link to inspect or explicitly claim a workspace's binding to a repo.uploads comment (and --comment) now prints a short
note explaining that an admin must approve the added permissions — with a link
to do it — before falling back to the local gh path, instead of falling back
silently.b9955b2: uploads attach and put --pr/--issue now also stamp gh.title with the resolved PR/issue title (best-effort via local gh, never blocks the upload) so the connected-work label in the workspace rail can show the real title instead of the bare owner/repo#123 ref.
9b73337: Managed attachments comment can now be posted by the uploads.sh GitHub App as
uploads-sh[bot] when the App is installed on the target repo, so --comment /
uploads comment no longer require a locally authenticated gh. Falls back to
the existing gh-authored comment where the App is not installed.
Both paths now find and edit the existing managed comment on threads past 100
comments (the gh fallback paginates the lookup), so updating attachment media
edits the one comment in place instead of posting a duplicate.
"operator:read" and "operator:write" alongside the existing file scopes, so CLI/SDK callers can request operator scopes minted by an admin session (#257). No new commands or flags."workspace:invite" and "workspace:manage" alongside the existing file and operator scopes, so CLI/SDK callers can request org-admin-gated workspace-governance scopes minted via POST /v1/tokens (#262). No new commands or flags.a5c9a1a: Export mapBounded from the /mcp entry so runtime-agnostic MCP tool sets (like the hosted worker's multi-file put) can share the SDK's bounded-concurrency batch helper.
7fa7d06: Publish the uploads screenshot command (added in #202 but never released). Captures a URL or local HTML file and hosts it in one call, with local Chrome and server-side /v1/render backends. Supports --viewport WxH@Nx, --wait, --selector, --full-page, --dark/--light, --via local|remote, and --out <file> (with --no-upload for file-only).
Adds agent-friendly capture controls: --hide <css> (repeatable) hides overlays before capture and localhost/private targets auto-hide known framework dev toolbars (opt out with --no-hide-dev-tools); --reduced-motion settles animations; and --eval <js> / --init-script <file> run setup JS before capture (local backend only).
gh pr view --repo requires an explicit selector, so pass the current branch name. uploads attach/put from a branch with an open PR now resolve it instead of erroring.uploads screenshot <url|file.html> command: capture a URL or a local
.html file and host it in one step, sharing the put upload pipeline
(--frame, optimize-by-default, --pr/--issue attachment + --comment).
Two capture backends selected by --via auto|local|remote (default auto,
or UPLOADS_SCREENSHOT_VIA): local drives an already-installed
Chrome/Chromium via playwright-core (an optional dependency — no browser
download), while remote renders server-side through a new uploads.sh
render endpoint. auto prefers local when a browser is found, else falls
back to remote; localhost/private-network targets and .html files stay
local-only. Also available as an MCP tool and reported in uploads doctor.attach (CLI + MCP) with partial-failure uploads/failures resultsuploads install now prints a closing next-step hint when only some agent skills succeed (or all fail), instead of leaving a half-installed state with no guidance after the per-step failure lines.get_metadata (stdio + hosted) so agents can read an object's queryable custom metadata by key — same as uploads meta get.put (CLI + stdio MCP) with partial failures; MCP total-failure keeps structured failures[]41fb17b: Anonymous, opt-out usage telemetry for the CLI and MCP server (command name, version, OS/arch, exit code, duration, optional error code — never paths or tokens). Opt out with UPLOADS_TELEMETRY_DISABLED=1, DO_NOT_TRACK=1, or uploads telemetry disable.
Also adds explicit opt-in diagnostic reports: uploads report and the MCP report tool can send a short message plus an optional text log/trace (max 256 KiB) when the user asks — never automatic.
456f9f6: uploads install now installs two agent skills: the new github-screenshots
workflow skill (when and how to get screenshots, GIFs, and recordings into
GitHub PRs and issues) alongside the existing uploads-cli CLI reference.
Skill steps are reported separately in human and --json output.
uploads usage human-readable: formatted sizes/counts, local-timezone timestamps, and terminal progress bars (with web-matching % and high/full thresholds). Also shortens the first-run telemetry notice to a brief non-PII opt-out FYI.411.5 KB → 94.2 KB) instead of raw bytes, --pr example keys reflect
the WebP extension rewrite, and the README command list includes login,
whoami/status, logout, invite, and admin.help + completion, brand-token colors, half-block mark header, auth/update banners411.5 KB → 94.2 KB) and note when a put overwrites an existing object (replaced on the API/JSON, >> replaced existing object (same URL) in human mode). --dry-run reports would replace / "replaced": true when the key already exists, without writing.uploads invite create now says whether the invitation was emailed or whether the install has no email configured and the accept link must be shared by hand (emailConfigured also appears in --json output). Older auth workers that don't report the field keep the previous hedged copy.uploads login --workspace <name> --create provisions the workspace during login when the account doesn't have it yet, so scripted and agent logins can self-onboard without an interactive prompt (device approval in a browser is still required once). The zero-workspace non-interactive error now points at the flag.uploads login now says which auth host it is signing in to (with a self-hosting hint), includes the saved API URL in its success output and --json payload, and ends with a pointer to uploads install so agent users discover the skill + MCP setup command.uploads put now stamps the four gh.* metadata pairs whenever it has a
GitHub target, so screenshots hosted on the default screenshots/… path get an
"Attached to" link on their /f/ page. On by default: with --pr/--issue
the explicit target is used (previously the stable key was written without
metadata); otherwise put resolves the current branch's PR (or classifies a
numeric --ref as pull vs issue) via gh. Disable with --no-auto,
--no-git, or UPLOADS_NO_AUTO_META=1. Resolution is best-effort — a missing
gh, no PR, or an API error uploads normally without metadata.uploads find / list --meta now print each
match's matched metadata inline in human output (as LIST_HELP already
promised, previously only in --json); uploads meta get on an object with no
metadata prints a (no metadata) note to stderr instead of nothing; and
uploads attach prints a find these later: uploads find gh.ref=… hint so its
auto-written gh.* metadata is discoverable. README now lists the stdio MCP
set_metadata/find_files tools and the put/attach metadata param.c5b36a3: Return embedUrl alongside durable url for shared dual-host CDN (GitHub Camo–friendly). CLI/MCP markdown and managed attachment comments prefer the embed host; override with UPLOADS_EMBED_PUBLIC_BASE_URL.
46b6860: Add queryable custom metadata to the CLI: put --meta k=v (repeatable), attach
now writes gh.repo/gh.kind/gh.number/gh.ref automatically (plus its own
--meta extras), new meta get/meta set commands, list --meta k=v and the
find k=v... alias for filtering objects by metadata.
MCP parity: the local stdio MCP's put/attach tools gain a metadata param
(same gh.* auto-injection as attach), and two new tools — set_metadata
(merge-set/delete) and find_files (metadata filter) — mirror the CLI's
meta set/find. The hosted MCP's put tool also gains a metadata param.
meta get/meta set now hit GET /v1/:workspace/files/:key?metadata=1 and
PATCH /v1/:workspace/files/:key instead of a /:key/metadata sibling route
— the original suffix route 404'd on real (slash-containing) keys once
deployed.
b1c87d8: CLI onboarding and agent-friendly put:
uploads install — short progress, no child stdout unless --verbose/failure;
non-interactive skills (-g -y -a '*'); success next-steps; MCP without a token is
skipped with a login nudge (skill still installs).error: prefix); exit non-zero; --json
keeps MISSING_TOKEN. Rejected tokens stay UNAUTHORIZED with a re-login hint.put --name <leaf> — clean key leaf on the stable --pr/default path.put --dry-run — resolve key + public URL without writing (API ?dryRun=1).--format json|url|markdown also print on stdout.FILE_NOT_FOUND — distinct code (exit 2) for a missing local file.1c5a38b: Add uploads invite create so workspace admins/owners can invite teammates by email via device login (no ADMIN_TOKEN). Invitees accept in the browser and run uploads login.
uploads login) now sends a recognizable CLI User-Agent so the web account page can tell when you've already signed in from the terminal.uploads login now signs you in through a browser by default: it opens a device-authorization page, you approve the request, and the CLI mints and saves a workspace token — no enrollment code to copy. When your account can access more than one workspace, pass --workspace <name>. The one-time enrollment-code path still works via --code / --code-stdin.pageUrl pointing at their standalone web page
(/g/<gallery>/<item>), and gallery previews in the managed GitHub
attachments comment deep-link to those pages instead of the gallery root.uploads setup and uploads login --help now lead with uploads login (device authorization) as the recommended way to sign in. Enrollment codes (--code / --code-stdin) are still supported and are now clearly described as a fallback for pre-existing invites. No behavior changes.--quiet, UPLOADS_NO_UPDATE=1, or NO_UPDATE_NOTIFIER=1). Add --version/-V, include the CLI version on uploads doctor, add Examples to login/admin help, and point usage errors at layered uploads <cmd> --help instead of dumping the full root manual.uploads admin invite create --email <address> now delivers the invite magic link
by email instead of printing it. The API sends from invites@uploads.sh via
Cloudflare Email Sending; delivery is rate-limited per recipient and audit-logged
without the code or link. On success the CLI confirms delivery and does not print the
secret; if delivery fails the invite is still created and the CLI prints the link as a
fallback.uploads admin invite create now prints a single self-contained magic link by
default. The one-time code rides in the link's URL fragment (…/invite?id=…#code=…),
which browsers never send to a server, so the invite page can offer a one-click login
command while the code stays out of query strings, server logs, and referrers—and
opening the page neither logs nor consumes it. Pass --separate-code for the previous
two-channel output (a non-secret page URL plus a code you deliver separately). The
invite page also now shows which workspace the invitation is for.uploads admin invite create as the user-facing invitation command and return a separate, non-secret onboarding page URL alongside the one-time login code. Alternate deployments can derive the page origin from --api-url or set it explicitly with --web-url; the previous admin enrollment create spelling remains supported.error.code / error.message) while still accepting the legacy flat { error: string } shape.X-Uploads-Meta-*: client, version, optimize/frame flags, source name). Put/head return metadata, including server-computed content-sha256 of the stored body.sideEffects: false so Workers that import helpers from the main entry (e.g. the remote MCP worker) can tree-shake Node-only image code (sharp / optimize / frame) and deploy cleanly.--frame (phone/browser/iphone-16-pro) on put/attach before optimize, and link uploads.sh in the managed GitHub attachments comment footer.put/attach (and MCP) by default for leaner GitHub embeds (EXIF stripped unless --keep-exif), with --no-optimize / UPLOADS_NO_OPTIMIZE escape hatch.--destination screenshots|gh|f / MCP destination) and map API key-policy denials (key_prefix_not_allowed, key_too_deep) to a dedicated CLI error with an actionable hint.uploads usage and size policy flags).uploads install to register the agent skill and the hosted remote MCP server in one step. Prefer agents.uploads.sh (workspace inferred from the bearer token); mcp.uploads.sh remains an alternate hostname.uploads mcp — a stdio MCP server whose tools mirror the CLI (put, attach, list, delete, comment, health, doctor, and later usage tools) under the same config resolution, with an optional per-call workspace override.uploads usage, uploads reconcile, and uploads purge-expired (plus matching MCP tools and a usage line on uploads doctor). Surfaces storage counters, optional budget remaining, ledger rebuild from storage, and retention purge when configured on the workspace.