CLI

TrayPage CLI is the command line client for publishing pages to TrayPage when MCP is unavailable or when you want a scriptable local workflow. An AI agent can run the CLI as a process, wait for a browser review to finish, and continue with the next revision from the CLI output.

When your AI tool supports MCP, use MCP integration. The CLI is best for environments without MCP, CI, local scripts, and review workflows where a WebSocket keeps the agent waiting until the user finishes reviewing in the browser.

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"

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.

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 an AI agent publishes a page, the user reviews it in the browser, and the agent should resume when the user clicks the finish button.

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.