CLI reference

Every command, every flag.

Installation

pipx install quayside-cli
quayside --help

Globals

The CLI caches state at ~/.config/quayside/. Override with QUAYSIDE_CLI_HOME=/path/to/dir.

The Quayside server URL is resolved in this order:

1. The --url flag on the command, if present
2. The url field of the cached token (set by quayside login)
3. The QUAYSIDE_URL environment variable
4. Default: http://localhost:8000

quayside login

Mint a dev token against a Quayside server and cache it locally.

quayside login \
  --principal-id alice@example.com \
  --class-slug eng/code-reviewer \
  --tenant dev \
  --url http://quayside.internal:8000

Flag	Required	Default	Notes
--principal-id, -p	yes	—	Who you are
--class-slug, -c	yes	—	Class this token authorizes
--tenant, -t	no	dev	Tenant id
--url, -u	no	from QUAYSIDE_URL or http://localhost:8000	Quayside server

Exits:

• 0 on success
• 1 if the server refused (e.g. dev_mode off in production)
• 2 if the server was unreachable

quayside whoami

Display the cached identity and remaining TTL.

$ quayside whoami
principal_id : alice@example.com
class_slug   : eng/code-reviewer
tenant       : dev
url          : http://quayside.internal:8000
expires_in   : 3527s
issuer       : quayside

Exits 1 if not logged in. Prints a yellow warning if the token has expired.

quayside run

Wrap a child process with Quayside identity injected as environment variables.

quayside run claude-code
quayside run -- python my_agent.py --flag arg
quayside run -- sh -c 'echo $ANTHROPIC_BASE_URL'

Sets in the child’s environment:

• ANTHROPIC_API_KEY=qsk_<JWT>
• ANTHROPIC_BASE_URL=<quayside_url>/api/v1/proxy/anthropic

Then execvpes the child. Child’s exit code is quayside’s exit code.

Exits before exec’ing:

• 1 if not logged in
• 1 if the cached token has expired
• 127 if the child command isn’t on PATH

quayside logout

Delete the cached token.

$ quayside logout
cleared /Users/alice/.config/quayside/token.json

If nothing was cached, prints no cached token to clear and exits 0.

quayside class list

List registered classes.

quayside class list
quayside class list --status draft
quayside class list --status deprecated

Flag	Notes
--status, -s	Filter by lifecycle (draft, active, deprecated, sunset, external)
--url, -u	Override server

Output is a hairline table: slug, name, status, owner.

quayside class show

Show details for one class by slug.

quayside class show eng/code-reviewer

Exits 1 if the slug doesn’t exist.

quayside class register

Register a new class.

quayside class register \
  --slug eng/code-reviewer \
  --name "Code Reviewer" \
  --purpose "Reviews PRs on the platform team; posts inline comments." \
  --owner alice@example.com \
  --status active

Flag	Required	Default	Notes
--slug, -s	yes	—	Must match [a-z0-9][a-z0-9._/-]*
--name, -n	yes	—
--purpose, -p	yes	—
--owner, -o	yes	—	A human principal id, not a team alias
--status	no	active	draft or active; external / sunset are rejected
--url, -u	no	cached

Exit codes match the server:

• 0 on 201
• 1 on 409 (duplicate slug) or 422 (invalid input)
• 2 on network failure

quayside class deprecate

Transition a class to deprecated.

quayside class deprecate eng/code-reviewer

Fails (1) if the slug doesn’t exist or the current lifecycle disallows the transition.

To un-deprecate, use the dashboard (or POST /api/v1/registry/classes/{id}/lifecycle directly).

Environment variables

Var	Effect
QUAYSIDE_CLI_HOME	Override the config directory (default ~/.config/quayside/)
QUAYSIDE_URL	Default server URL when none cached and no --url passed

What the CLI cannot (yet) do

• Run an OAuth/PKCE login flow against a real IdP — login only talks to /auth/dev/mint-token
• Edit policies — use the dashboard or HTTP
• Drill into audit — use the dashboard or HTTP