Getting Started

Install

Default to npx @zaks-io/agent-paste ... for one-shot Node.js 24+ runs. Use npm install -g @zaks-io/agent-paste for repeated npm use. Use the standalone installers only when Node/npm are unavailable. After installation, use the installed agent-paste ... command; all paths run the same CLI.

npx @zaks-io/agent-paste publish ./report
npm install -g @zaks-io/agent-paste

Standalone fallback when Node/npm are unavailable:

curl -fsSL https://agent-paste.sh/install.sh | sh

irm https://agent-paste.sh/install.ps1 | iex

The installers verify release checksums before placing agent-paste on your PATH. The macOS binary is codesigned and notarized.

Authenticate

For interactive use, run agent-paste login. It opens a browser OAuth flow and stores a scoped local credential in your OS keyring when available.

agent-paste login
agent-paste whoami

Agents should run agent-paste whoami --json before falling back to accountless publish. It exits 0 whether or not you are signed in, so check the JSON rather than the exit code: a signed-in response means use normal authenticated publish, not --ephemeral; "authenticated": false means no usable credential. If browser auth is possible, run agent-paste login before publishing. Use --ephemeral only when login is unavailable or explicitly skipped.

Publish

agent-paste publish ./report
agent-paste publish ./report --artifact-id art_01H...

A publish walks a file or folder, creates an Upload Session, uploads bytes to signed upload-worker URLs, finalizes a Revision, and publishes it. Publish is content-only and private. CLI publish prints the private_url (/v/<artifactId> clean viewer) as View; MCP publish returns the same private_url and omits management IDs. CLI JSON output carries diagnostic IDs and snapshot URLs for automation. Artifact lifetime comes from Workspace policy, not a CLI flag.

private_url is login-walled app navigation. A plain curl may receive the web app shell with a sign-in redirect state and HTTP 200; that does not make the Artifact publicly readable. For a no-login browser handoff, use a Share Link from agent-paste set-visibility <artifact-id> unlisted.

A publish path can be a file or directory. Directory publish preserves relative paths, so an HTML entrypoint can load sibling CSS, JS, JSON, images, and fonts. Folder entrypoint inference is exactly index.html, index.md, README.md, then the only file in the folder. If a multi-file folder has none of those, publish fails; pass --entrypoint <path>. Folder uploads exclude .git/, node_modules/, .DS_Store, .env, and .env.*.

For an authenticated unlisted no-login link that follows later publishes, run agent-paste set-visibility <artifact-id> unlisted on the CLI, or MCP set_visibility with visibility: "unlisted", to mint or reuse the Share Link and return unlisted_url. Accountless --ephemeral publish is the exception: it auto-creates that Share Link and returns unlisted_url immediately. The direct usercontent.agent-paste.sh/v/... URL points at one Revision, does not Live Update, and direct HTML opened there is inert raw byte delivery. The private_url clean viewer is the default Workspace view publish returns.

Ephemeral fallback

npx @zaks-io/agent-paste publish ./report --ephemeral

--ephemeral self-provisions a short-lived Ephemeral Workspace, publishes once, and leads human output with unlisted_url, a working no-login script-disabled Share Link. Relay unlisted_url for immediate viewing and claim_url when the human wants to keep, own, or unlock interactivity. There is no user-backed session before claim; the signed-in browser session that opens claim_url chooses the destination Workspace. If copied instructions include --claim-code <clm_...>, preserve it; the API embeds it in the Claim Token for attribution and the CLI never returns it separately. It ignores stored login, so use it only when auth is unavailable or explicitly skipped. Ephemeral is not the Free Plan: use it for non-interactive text, markdown, images, and static HTML/CSS. Unclaimed ephemeral HTML is script-disabled, so use authenticated publish for interactive work.