Skip to content
agent-paste.sh
Docs

CLI Reference

The CLI is the primary publish surface for humans, agents, and CI.

Commands

CommandPurpose
agent-paste loginAuthenticate through the browser.
agent-paste login --device-codeAuthenticate from a sandbox; approve in your own browser.
agent-paste logoutRevoke and remove the stored credential.
agent-paste whoami --jsonReport authentication, Workspace, actor, and scopes.
agent-paste publish <path>Publish a file or folder and return url.
agent-paste pull <artifact-id> <path>Read one stored file.
agent-paste edit <artifact-id> <path>Apply literal edits and publish a Revision.
agent-paste versionPrint the CLI version.
agent-paste upgradeUpdate a standalone binary install.

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

Remote login

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

whoami exits 0 even when signed out, so check authenticated. 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 run whoami again. An AGENT_PASTE_API_KEY env var also authenticates and takes precedence over stored credentials.

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, and edit 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/

When login is unavailable, publish <path> --ephemeral --json publishes without an account. See Ephemeral.

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>. Pass --render-mode html|markdown|text|image|audio|video only when inference is wrong.