CLI Reference

Commands

--json writes one object to stdout with schema_version; progress and errors go to stderr. Exit codes: 0 success, 1 generic or transport failure, 2 authentication, 3 quota, 4 validation, 5 not found, 6 HTTP server failure. agent-paste help publish and help pull list flags and JSON fields.

API keys for CI and headless agents

Create a key at API Keys. Its secret is shown once. Inject it securely as AGENT_PASTE_API_KEY through your sandbox or CI secret configuration. An already injected key authenticates automatically, with no login. Keep the inherited environment; never print the key or pass it as a command argument.

agent-paste whoami --json
agent-paste publish ./report --json

A non-empty AGENT_PASTE_API_KEY takes precedence over saved login. Invalid, revoked, expired, or wrong-environment keys fail with exit 2; the CLI does not try saved credentials. Correct or remove the environment key before retrying. whoami exits 0 with authenticated: false only when no usable local credential exists. A successful response identifies the Workspace, actor, and scopes. CLI 0.2.6 and later add authenticated: true; 0.2.5 and earlier omit it on success. HTTP server failures exit 6; transport failures exit 1.

logout attempts to revoke the saved login credential, then removes it locally and reports any remote revocation failure. It leaves the environment key untouched, so that key can still authenticate. Revoke environment keys in the dashboard and remove them from secret configuration when no longer needed.

Remote login

agent-paste login --device-code
agent-paste whoami --json

Use login only when whoami --json reports authenticated: false. Run login with a browser on the same machine, or login --device-code in a sandbox or SSH session. Device login prints a URL and code on stderr and needs network access to WorkOS and the API but no local browser. Keep it running until the user approves, then check whoami again.

Publish

agent-paste publish ./report --json
agent-paste publish ./report --artifact-id 01234-56789-abcde-fghjd --json

The returned url opens without login and stays the same across updates. Its artifact ID is the first label of the hostname; --artifact-id, pull, edit, and download accept that ID, the art_... artifact_id from JSON output, or the full URL. Updates require Workspace access.

✓ Published "report"

  View      https://01234-56789-abcde-fghjd.agent-paste.link/
  Expires   <expiration date>

  Update    agent-paste publish ./report --artifact-id 01234-56789-abcde-fghjd

  → open https://01234-56789-abcde-fghjd.agent-paste.link/

Use publish <path> --ephemeral --json when no authenticated path is available and static output meets the task, or the user requests accountless publishing. It explicitly ignores both environment and saved credentials. Do not use it automatically after an authentication failure. See Ephemeral.

Feedback

agent-paste feedback "Upload retry failed" --json
cat report.txt | agent-paste feedback --json

Feedback accepts 1 to 10,000 characters and uses your current credential, including read-only credentials. The CLI attaches its version and the feedback command name. Confirmation does not echo your report. JSON output returns feedback_id and schema_version; validation errors exit 4 and transport failures exit 1.

Files and entrypoints

Directory publish keeps relative paths and skips .git, node_modules, .DS_Store, and .env*. The entrypoint is index.html, index.md, README.md, or the only file; otherwise pass --entrypoint <path>.