Traycer Docs

The Traycer CLI binary is traycer. It is used for host control, authentication, workspace/worktree operations, and agent automation.

Installation

The desktop app bundles the CLI, so you only need to install it separately for standalone, automation, or CI use. Install with npm (requires Node.js 20.18+):

npm install -g @traycerai/cli

Or with Homebrew on macOS and Linux:

brew install traycerai/traycer/traycer

Verify the install:

traycer --version

The npm package is @traycerai/cli.

Global Flags

Flag	Purpose
`--json`	Print machine-readable output where supported.
`--quiet`	Reduce normal output.
`--no-progress`	Disable progress output.
`--no-bootstrap`	Skip automatic bootstrap behavior.

Auth Commands

Command	Purpose
`traycer login`	Authenticate the CLI.
`traycer login --token <token>`	Authenticate with a token.
`traycer login --token -`	Read the token from stdin.
`traycer logout`	Remove stored CLI credentials.
`traycer whoami`	Show the authenticated user.

CLI credentials are stored under ~/.traycer/cli/credentials.

Host Commands

Command	Purpose
`traycer host start`	Start the host.
`traycer host status`	Show host status.
`traycer host doctor`	Diagnose host setup.
`traycer host restart`	Restart the host.
`traycer host stop`	Stop the host.
`traycer host install`	Install the host.
`traycer host ensure`	Ensure the host is available.
`traycer host update`	Update the host.
`traycer host uninstall`	Uninstall the host.
`traycer host uninstall --all`	Remove all host installs.
`traycer host available`	List available host versions.
`traycer host logs`	Show host logs.
`traycer host logs --tail <n>`	Show the last `n` log lines.
`traycer host logs --follow`	Follow host logs.

Useful options:

Command	Purpose
`traycer host start --cwd <path>`	Start the host with a specific working directory.
`traycer host install --release <version>`	Install a specific registry release.
`traycer host install --from <path>`	Install from a local host archive.
`traycer host ensure --force`	Restart the host even if it reports active work.
`traycer host ensure --no-service-register`	Install the host without registering the OS service.

The CLI discovers host connection metadata under ~/.traycer/host/. host install and host ensure accept either --release or --from, not both.

Service Commands

Command	Purpose
`traycer service install`	Install the OS service integration.
`traycer service install --no-linger`	Linux only: skip `loginctl enable-linger`.
`traycer service install --allow-self-invocation`	Development only: register the current CLI as the service command.
`traycer service status`	Show service status.
`traycer service uninstall`	Remove the service integration.

CLI Commands

Command	Purpose
`traycer cli upgrade`	Upgrade the CLI.
`traycer cli upgrade --dry-run`	Show what would upgrade.
`traycer cli upgrade --target <version>`	Upgrade to a target version.
`traycer cli re-anchor`	Re-anchor the CLI install.
`traycer cli re-anchor --binary-path <path> --installed-version <version>`	Point upgrade tracking at a manually installed CLI binary.

Config Commands

Command	Purpose
`traycer config shell get`	Show shell config.
`traycer config shell list`	List shell config.
`traycer config shell set`	Set shell path or args.
`traycer config shell set --path <path>`	Set shell executable path.
`traycer config shell set --path <path> -- <args...>`	Store shell startup args. Pass args after `--` when they start with dashes.
`traycer config shell set --clear-args`	Clear shell startup args.
`traycer config shell reset`	Reset shell config.
`traycer config env list`	List configured environment overrides.
`traycer config env get --key <name>`	Show one env override.
`traycer config env set --key <name> --value <value>`	Set an env override.
`traycer config env unset --key <name>`	Explicitly unset an inherited environment variable.
`traycer config env delete --key <name>`	Delete a configured override entry.

CLI config is stored under ~/.traycer/cli/config.json. Provider credentials are not CLI env vars. Configure provider credentials in Settings → Providers.

Workspace and Worktree Commands

Command	Purpose
`traycer workspace list`	List known workspaces.
`traycer workspace list --epic-id <id>`	List workspaces for a specific Task id.
`traycer worktree create`	Create a worktree for agent work.
`traycer worktree create --workspace <path>`	Create from a workspace path.
`traycer worktree create --source-branch <branch>`	Choose the source branch.
`traycer worktree create --branch <branch>`	Choose the new worktree branch.
`traycer worktree create --existing <branch>`	Check out an existing branch into a fresh worktree.
`traycer worktree create --carry-uncommitted`	Carry uncommitted changes into the worktree.

Agent Commands

Command	Purpose
`traycer agent list`	List reachable agents.
`traycer agent create`	Create a child agent.
`traycer agent send`	Send a message to another agent.
`traycer agent transcript`	Read an agent transcript.
`traycer agent inbox`	Inspect pending agent messages.
`traycer agent selection-guide`	Read the agent selection guide.
`traycer agent list-harness-models`	List models for a harness.
`traycer monitor`	Stream this agent’s inter-agent inbox messages.

Supported harness ids include claude, codex, opencode, traycer, and cursor. Supported surfaces are gui and tui. Supported agent modes are regular and epic. Common agent options:

Option	Applies To	Purpose
`--epic-id <id>`	Most `agent` commands, `monitor`, `workspace list`	Task context. Defaults to `TRAYCER_EPIC_ID` when the command runs inside an agent.
`--sender-agent-id <id>`	`agent list`, `agent create`, `agent selection-guide`, `agent list-harness-models`, `agent send`	Calling agent. Defaults to `TRAYCER_AGENT_ID`.
`--all`	`agent list`	List all agents in the Task, not just agents belonging to the current user.
`--surface <surface>`	`agent create`	Child surface: `gui` or `tui`.
`--harness <id>`	`agent create`	Coding agent: `claude`, `codex`, `opencode`, `traycer`, or `cursor`.
`--model <id>`	`agent create`	Model id for the child agent.
`--agent-mode <mode>`	`agent create`	`regular` or `epic`.
`--reasoning-effort <effort>`	`agent create`	Reasoning effort for supported models.
`--fast`	`agent create`	Request fast mode for supported GUI models.
`--cwd <path>`	`agent create`	Primary working directory for the child agent.
`--workspace-path <path>`	`agent create`	Additional existing workspace path. Repeatable.
`--workspace-entry <workspace=path>`	`agent create`	Exact workspace binding. Repeatable.
`--to <agentId>` / `--message <text>`	`agent send`	Required receiver and message.
`--expect-reply` / `--response-id <id>`	`agent send`	Open a reply thread, or close one with the final reply.
`--agent-id <id>`	`agent transcript`, `agent inbox`, `monitor`	Target agent. `inbox` and `monitor` default to `TRAYCER_AGENT_ID`.

Provider hook commands such as agent title-from-hook, agent activity-from-hook, and agent turn-ended-from-hook are used by Traycer-launched Terminal Agents. They are not normal user workflows.

Environment Variables

The CLI uses runtime environment variables for noninteractive behavior and agent context.

Variable	Purpose
`CI`	Signals CI/noninteractive environments.
`TRAYCER_NONINTERACTIVE`	Forces noninteractive behavior.
`TRAYCER_CLI_VERSION`	Build-provided CLI version.
`TRAYCER_AGENT_ID`	Current agent id in agent-run contexts.
`TRAYCER_EPIC_ID`	Current Task id in agent-run contexts.
`HOME` / `USERPROFILE`	Used to resolve local Traycer paths.

Provider API keys and model credentials belong in provider setup, not in this CLI reference.

​Installation

​Global Flags

​Auth Commands

​Host Commands

​Service Commands

​CLI Commands

​Config Commands

​Workspace and Worktree Commands

​Agent Commands

​Environment Variables