CLI

TrayPage CLI connects a coding agent to browser-based review. An AI agent can publish a page, run traypage review start --watch, and wait while a reviewer works in the browser. When the reviewer finishes the review, the CLI returns the open comments, revision prompt, and next command, so the agent can continue by publishing the next version with the comments applied.

The CLI is also useful when MCP is unavailable, in CI, or from local scripts. When your AI tool supports MCP, MCP integration is the normal entry point, but CLI review sessions are the right fit when the agent should keep running and resume automatically after browser review completion.

Resume an AI agent after review

The typical loop is:

1. The AI agent creates HTML / Markdown and publishes a draft version to TrayPage with the CLI
2. The AI agent runs traypage review start --page page_xxx --version 1 --watch and waits for review completion
3. The reviewer checks the page in the browser, adds comments or a summary note, and marks the review complete
4. The CLI prints approved, the open comment count, the revision prompt, and the next command
5. The AI agent uses that output to publish a new version with the comments applied

In this flow, the reviewer only needs to finish the review in the browser. They do not need to copy a revision prompt back into chat by hand. The copyable revision prompt remains useful as a fallback when no CLI process is waiting or when you want to pass instructions manually.

Install

Use Node.js 22 or newer, then install the CLI from npm.

npm install -g @traypage/cli

Confirm the command is available:

traypage --help

For local development inside this repository, run the same CLI through pnpm instead of the published npm package.

pnpm traypage -- --help

Authenticate

Use OAuth for normal interactive CLI login. The CLI opens your browser and uses the same consent screen as MCP, where you choose the organization, accessible projects, and default project. You do not need to copy a token by hand.

traypage auth login
traypage auth status

The CLI stores a short-lived access token and refresh token in ~/.config/traypage/config.json. OAuth is recommended for human-operated CLI use because access is granted through consent and scoped to the selected organization and projects.

For CI or automation where no browser is available, you can still use a TrayPage API token, prefixed with tp_. API tokens are project-scoped. Create one from the target project's settings page under MCP / API access.

traypage auth token set tp_xxx

For one-off scripts, use an environment variable instead of writing a config file.

TRAYPAGE_API_TOKEN=tp_xxx traypage pages list

For local or staging environments, set the API base URL. The same flag works for OAuth and API token auth.

traypage auth login --api-base-url http://localhost:3000
traypage auth token set tp_xxx --api-base-url http://localhost:3000

Or override it per command:

TRAYPAGE_API_BASE_URL=http://localhost:3000 traypage pages list

Switch profiles

Create profiles when you work with multiple organizations or projects. A profile can store the default organization, default project, API base URL, and optionally its own OAuth login or API token.

traypage profiles set prod --organization acme --project reports --use
traypage auth login --profile prod

After that, prod is the current profile, so commands use acme / reports without repeating the target flags.

traypage publish ./report.html --title "Sales analysis report"

You can also pass a profile name for a single command.

traypage publish ./report.html --profile prod
traypage pages list --profile prod

In CI or separate terminal sessions, use an environment variable.

TRAYPAGE_PROFILE=prod traypage pages list

Inspect and switch profiles:

traypage profiles list
traypage profiles show prod
traypage profiles use prod
traypage profiles remove prod

Publish a page

Create a new page from an HTML or Markdown file.

traypage publish ./report.html \
  --title "Sales analysis report" \
  --organization acme \
  --project reports

The first version is created as a draft. The response includes a review URL and a share URL, but the share URL does not show the page body until a version is published.

To publish immediately, pass --publish.

traypage publish ./report.html --title "Sales analysis report" --publish

To add a new draft version to an existing page, pass --page.

traypage publish ./report-v2.html --page page_xxx --changelog "Applied review comments"

Organize pages

List pages in the current profile's or token's project. To inspect archived pages, pass --archived.

traypage pages list
traypage pages list --archived

Archiving hides a page from normal lists and frees an active page slot. Content and versions are not deleted.

traypage pages archive --page page_xxx
traypage pages unarchive --page page_xxx

Restoring consumes an active page slot, so it can fail when the organization is already at its plan limit.

Publish a version

Switch which version appears from the stable share URL. This does not change visibility.

traypage versions publish --page page_xxx --version 2

Use the visibility command to change who can open the share URL.

The values below are the exact CLI inputs. In the app, they appear as Project Members and Anyone with the link.

traypage visibility set --page page_xxx --visibility project_members
traypage visibility set --page page_xxx --visibility public_link

Read comments

Fetch open comments as JSON:

traypage comments list --page page_xxx --version 2 --json

To turn open comments into revision instructions for an AI agent, fetch the revision prompt.

traypage comments prompt --page page_xxx --version 2 --language en

The revision prompt does not treat every comment as a mechanical edit request. If a comment is a question or clarification where the right response is an answer rather than a file change, the prompt tells the AI agent that too.

Wait for review completion

Use a review session when the AI agent should automatically resume after the browser review is finished.

traypage review start --page page_xxx --version 2 --watch

With --watch, the CLI connects to TrayPage over WebSocket and waits for the browser review to finish. When the user finishes the review, the CLI prints a result containing approved, the open comment count, the revision prompt, and the next command. The AI agent can read that output and continue with the next revision.

For long waits, or when you want to close the terminal and resume later, create a session first and resume it later.

traypage review start --page page_xxx --version 2 --json
traypage review resume revs_xxx

On the same machine, the watch token is stored in the CLI config, so resume usually only needs the session ID. On another machine or in CI, pass --watch-token trs_xxx.

Finishing a review from the browser is separate from saving page content or comments. TrayPage sends the open comments and optional note to the AI agent, and the waiting AI agent receives the result and moves on to the next revision.

Common environment variables

Troubleshooting

• Authentication required — Run traypage auth status and confirm OAuth login is complete. On a human-operated machine, run traypage auth login. In CI, set TRAYPAGE_API_TOKEN.
• Project not found / project_restricted — API tokens are scoped to the project where they were issued. Create a token for the target project, or check --organization and --project.
• WebSocket cannot connect — traypage review start --watch uses WebSocket. If the connection fails, the CLI falls back to checking the result endpoint. You can also run traypage review resume revs_xxx later.
• Publishing works but comments fail — Check that the token scopes include comment:read and revision_prompt:read.
• Local development connects to production — Set TRAYPAGE_API_BASE_URL=http://localhost:3000, or save it with traypage auth token set ... --api-base-url http://localhost:3000.