traycer. It is used for host control, authentication, workspace/worktree operations, and agent automation.
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. |
~/.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. |
| 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. |
~/.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. |
~/.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. |
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. |
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. |