CLI - Traycer AI

The Traycer CLI is the traycer command. Use it to sign in, run and update the host on a machine, configure the shell Traycer uses, manage provider profiles and worktrees, and let agents work with other agents in a Task.

Installation

Traycer Desktop comes with the CLI, so you only need to install it yourself to use it on its own: on a remote machine, in scripts, or from your own terminal.

npm
Homebrew

Requires Node.js 22.13 or later.

npm install -g @traycerai/cli

The npm package is @traycerai/cli.

On macOS and Linux. Homebrew installs a standalone binary, so Node.js is not needed.

brew install traycerai/traycer/traycer

Check the install:

traycer --version

Use the CLI That Comes With Desktop

Traycer keeps a copy of the CLI at ~/.traycer/cli/bin/traycer (%USERPROFILE%\.traycer\cli\bin\traycer.exe on Windows). The agents and terminals that Traycer launches already have this directory on their PATH. Your own terminal does not. To run traycer there, add the directory to your PATH, or install the CLI with npm or Homebrew.

export PATH="$HOME/.traycer/cli/bin:$PATH"

Upgrading

Installed with	Upgrade with
npm	`npm install -g @traycerai/cli@latest`
Homebrew	`brew upgrade traycer`
Traycer Desktop, or by hand	`traycer cli upgrade`

traycer cli upgrade does not replace a CLI that a package manager installed. It prints that package manager’s upgrade command instead.

Global Flags

--json, --quiet, and --no-progress work with every command.

Flag	Purpose
`--json`	Write machine-readable NDJSON to stdout. See JSON Output.
`--quiet`	Hide non-essential human-readable output.
`--no-progress`	Hide progress output.
`-h`, `--help`	Show help for any command.
`-V`, `--version`	Print the CLI version.

Auth Commands

Command	Purpose
`traycer login`	Sign in with a device code. The CLI prints a URL and a short code, tries to open the URL in your browser, and waits until you approve. You can approve on any device, so this also works over SSH. If a host is already running on this machine and is not yet authorized, this authorizes it too.
`traycer logout`	Sign out. Removes the stored credentials, which also signs Traycer Desktop out on this machine, and clears the local cache of chat content. A host that is already running keeps its own credential until it stops.
`traycer whoami`	Check the stored sign-in with Traycer and print the signed-in user. This can refresh the stored credentials.
`traycer whoami --local`	Print the stored identity without contacting Traycer. It cannot tell whether the session has expired or been revoked.
`traycer link-phone`	Sign in the Traycer mobile app by scanning a code. Needs an existing sign-in and an interactive terminal. It waits until you approve or reject the phone that scanned the code.
`traycer link-phone --no-qr`	Print only the code to type, for terminals that garble the QR code.

CLI credentials are stored in cli/credentials inside the data folder, which Traycer Desktop shares.

Host Commands

The host is the background process that runs agents, terminals, and Tasks on a machine. Traycer Desktop manages it for you. Use these commands on a machine without Desktop, or to troubleshoot.

Check and Run

Command	Purpose
`traycer host status`	Show whether the host is running, with its process, address, recent activity, and how the last update ended. It only reads; it never installs or starts anything.
`traycer host doctor`	Diagnose the host and CLI install. For a problem it can name, it prints the command that fixes it.
`traycer host logs`	Print the last 200 lines of the host log.
`traycer host logs --tail <n>`	Print the last `n` lines.
`traycer host logs --follow`	Keep printing new lines as they are written. Ignored with `--json`.
`traycer host start`	Run the host in the foreground until you press Ctrl-C. To start it in the background instead, use `traycer host service start`.
`traycer host start --cwd <path>`	Run the host with a specific working directory. The default is the install directory.
`traycer host restart`	Restart the host service. If a CLI upgrade is waiting to be applied, the restart also tries to apply it, which can replace the `traycer` binary.
`traycer host stop`	Stop the host service.
`traycer host restart --force`, `traycer host stop --force`	Restart or stop even when the host is busy. Running terminal sessions and agent work are killed.
`traycer host free-port-and-restart --pid <pid> --port <port>`	Stop the process that holds the host’s port, then restart the host. This is the fix `host doctor` prints for a port conflict. Nothing is stopped if that process no longer holds the port.
`traycer host capabilities`	List the capabilities this CLI supports, as plain text or, with `--json`, a single JSON document.
`traycer host capabilities --has <capability>`	Exit 0 if this CLI supports the capability, and non-zero otherwise.

Install, Update, and Remove

Command	Purpose
`traycer host ensure`	Make sure the host is installed, registered as a service, and running, and install or start it if not. Safe to run repeatedly.
`traycer host install`	Install the latest host, register the OS service, and start the host. If you are signed out and the terminal can ask, it offers sign-in first.
`traycer host update`	Update to the latest compatible host, then check that the host comes back. Fails if the updated host does not answer.
`traycer host download [version]`	Download and stage a host version without touching the running host. Defaults to the latest.
`traycer host apply`	Install the staged version. It succeeds once the files are in place and does not check that the host came back; use `host update` for that.
`traycer host available`	List the host versions you can install. Prereleases are listed only when the installed host is a prerelease.
`traycer host available --include-pre-releases`	Include prereleases. `--no-include-pre-releases` leaves them out.
`traycer host uninstall`	Ask the running host to stop, then remove the installed and staged host files. The OS service stays registered.
`traycer host uninstall --all`	Deregister the OS service, ask the host to stop, then remove the host files. On Windows the host is stopped straight away, even when it is busy.

Neither form of host uninstall touches your data folder or credentials. If the host does not stop, the command fails and keeps the install. --force works with or without --all: it forces the stop and removes the install even if the host remains running. Running terminal sessions and in-flight agent work are killed. Options for these commands:

Option	Applies to	Purpose
`--release <version>`	`install`, `ensure`, `update`	Install this registry version instead of the default.
`--from <path>`	`install`, `ensure`	Install from a local host archive. Cannot be combined with `--release`.
`--allow-downgrade`	`update`	Let `--release` replace a newer installed host.
`--force`	`install`, `ensure`, `update`, `apply`	Go ahead even when the host is busy. Running terminal sessions and agent work are killed.
`--no-service-register`	`install`, `ensure`	Install the files only, without registering or starting the OS service. `host install` does not support it on Windows.
`--keep-installed`	`ensure`	Keep whichever host version is installed instead of moving to this CLI’s default.
`--no-linger`	`install`, `ensure`, `host service install`	Linux only: skip `loginctl enable-linger`.
`--accept-store-format-loss`	`install`, `ensure`, `update`, `apply`	Install a host even though chats or local tasks on this machine were saved in a newer format than it can read. Those chats and local tasks are unavailable while that host is installed.

The CLI reads the host’s connection details from host/ inside the selected data folder.

Background Service

The host service commands manage the OS registration that keeps the host running: launchd on macOS, a systemd user service on Linux, and a Scheduled Task on Windows.

Command	Purpose
`traycer host service install`	Register the OS service and start the host. If you are signed out and the terminal can ask, it offers sign-in first.
`traycer host service install --takeover`	macOS only: move host management from Traycer Desktop to the CLI. Stops the host Desktop runs, removes Desktop’s registration, and registers the CLI’s own.
`traycer host service start`	Start the registered service in the background and return.
`traycer host service status`	Show the registration and whether the host is running. It only reads.
`traycer host service uninstall`	Deregister the service, which also asks the host to stop. The host files stay installed; `traycer host uninstall` removes them.

Host Lifecycle

traycer host lifecycle get shows the current mode, whether Desktop is open, how the host was started, and whether its supervisor supports the chosen mode. traycer host lifecycle set <mode> accepts background, linked, ask, stop-if-idle, or none. See When you quit Traycer for the corresponding behavior. Setting a mode does not start or stop the host. Startup changes apply to the next automatic start. Quit behavior can update while Desktop is open, but a quit already in progress keeps its earlier choice. A running host with an older supervisor may need a restart; the command reports this. In particular, set none leaves a running host alone and switches Desktop to remote hosts on its next launch. This differs from choosing Don’t run a host in Settings, which can ask you to confirm stopping the local host. Manually started foreground hosts remain unaffected when Desktop quits.

CLI Commands

Command	Purpose
`traycer cli upgrade`	Download and install the CLI version Traycer currently publishes. For a CLI installed by npm, Homebrew, or another package manager, it prints that package manager’s upgrade command instead. If the binary is in use, usually because the host runs from it, the upgrade finishes on the next `traycer host restart`. If the published version is older than the one you have, as it is while you run a release candidate, nothing is changed.
`traycer cli upgrade --dry-run`	Show the version and download URL without installing anything.
`traycer cli upgrade --target <version>`	Fail unless the published version is exactly `<version>`.
`traycer cli upgrade --target <version> --allow-downgrade`	Install `<version>` even though it is older than the one you have. Both flags are needed, so a plain upgrade never moves you backwards.
`traycer cli re-anchor --binary-path <path> --installed-version <version>`	Point upgrade tracking at a CLI binary you installed or moved by hand. Use it when `cli upgrade` reports that there is no recorded install.

Data Folder

On Windows, choose a new data folder or move an existing installation to a fixed local NTFS drive. Use a new or empty folder that is not inside, or a parent of, the current data folder. Network drives, removable drives, links, junctions, and FAT/exFAT volumes are refused.

Command	Purpose
`traycer data status`	Show the selected folder, any move in progress, and what to do next. Changes nothing.
`traycer data init --to <folder>`	Windows only: choose the folder before a new installation has any Traycer data.
`traycer data migrate --to <folder> --dry-run`	Preview the paths, space, and installed-version checks without moving anything.
`traycer data migrate --to <folder>`	Windows only: stop the Hosts, copy and verify the data, and switch to the new folder.
`traycer data recover`	Continue an interrupted move.
`traycer data recover --rollback`	Return to the old folder before the move has taken effect.
`traycer data cleanup <migration-id>`	Permanently delete the unused copy after a successful move or rollback.

Status, dry-run, recovery, and cleanup commands work on all platforms. Each command accepts --json. Commands that change data ask for confirmation; --yes skips that question.

Move Existing Data on Windows

Preview with traycer data migrate --to "D:\TraycerData" --dry-run.
Quit Desktop, finish other Traycer commands, and close shells or editors using Traycer-managed worktrees.
Run traycer data migrate --to "D:\TraycerData". Review the session-impact report before confirming. Some agents may need a new provider session or be held; native provider-only state does not always carry over. A dry-run cannot check session impact.
Reopen Traycer and check your work. The old copy still uses disk space until you run traycer data cleanup <migration-id>. Cleanup refuses if recorded source content has changed.

In scripts, if session impact needs acceptance, rerun with the report’s --accept-session-impact <digest>; --yes alone does not accept it. Do not manually move the folder or run an older Traycer version after moving it: older versions can use the old copy and repeat queued work. The app, Desktop caches, and provider folders outside Traycer (such as ~/.claude) do not move. Windows read-only and hidden file attributes are not preserved. The selected location is recorded in ~/.traycer-bootstrap/location.json, which stays in your home folder. If the selected drive is missing, reconnect it; Traycer does not fall back to the default folder. For interrupted moves, see data folder recovery.

Config Commands

The shell and environment settings apply when Traycer starts the host and opens terminals. They are the same settings as Settings › Shell, stored in cli/config.json inside the selected data folder.

Command	Purpose
`traycer config shell get`	Show the shell settings in effect.
`traycer config shell list`	List the shells found on this machine.
`traycer config shell set --path <path>`	Select a shell. Its default flags apply.
`traycer config shell set --path <path> -- <args...>`	Select a shell and store its startup flags. Put flags after `--` so ones that start with a dash are not read as options.
`traycer config shell set -- <args...>`	Store startup flags for the selected shell.
`traycer config shell set --path <path> --clear-args`	Store an empty list of startup flags.
`traycer config shell add --path <path>`	Remember a shell (any executable) and select it. The file must exist and be executable.
`traycer config shell remove --path <path>`	Forget a shell you added. If it was selected, the system default shell is used.
`traycer config shell revert-args --path <path>`	Restore a remembered shell’s default flags.
`traycer config shell reset`	Go back to the system default shell. Remembered shells and their flags are kept.
`traycer config env list`	List environment variable overrides.
`traycer config env get --key <name>`	Show one override.
`traycer config env set --key <name> --value <value>`	Set an override. The name must start with a letter or underscore and contain only letters, digits, and underscores.
`traycer config env unset --key <name>`	Remove an inherited variable from the environment.
`traycer config env delete --key <name>`	Delete an override. Fails if it is not set.

Provider credentials are not set here. Configure them in Settings › Providers.

Provider Profile Commands

A profile is an account a provider runs under. The provider’s own CLI login is the Terminal account, which these commands call ambient. Managed profiles are extra accounts next to it, available for Claude Code, Codex, Grok, and Antigravity. These commands change the same profiles as Profiles & Limits in Settings › Providers, on the host running on this machine.

Command	Purpose
`traycer profile list`	List every provider that has profiles, with each profile’s ID, name, account, whether it is enabled and signed in, and its last known usage-limit status.
`traycer profile list <provider>`	List one provider’s profiles.
`traycer profile add <provider>`	Create a managed profile and sign it in. The CLI prints a sign-in URL, and a code where the provider uses one, opens the page in your browser when it can, and waits until the sign-in finishes. The profile is named after the part of the account’s email before the `@`.
`traycer profile add <provider> --label <name>`	Create the profile with a name of your own, up to 64 characters.
`traycer profile login <provider> <profile>`	Sign an existing profile in again.
`traycer profile rename <provider> <profile> <label>`	Rename a profile.
`traycer profile disable <provider> <profile>`	Stop Traycer using a profile without removing it.
`traycer profile enable <provider> <profile>`	Let Traycer use the profile again.
`traycer profile remove <provider> <profile>`	Remove a managed profile and its stored sign-in, after asking you to confirm. The Terminal account cannot be removed.
`traycer profile remove <provider> <profile> --yes`	Remove without asking. Required with `--json` and when the terminal cannot ask.

<provider> is claude, codex, grok, or antigravity.
<profile> is ambient or a profile ID from traycer profile list.
add and login need a person at a terminal, so they are refused with --json and in CI. Claude Code is also refused when input is piped or redirected, because you may need to paste a code. Press Ctrl-C to cancel a sign-in; a profile that was being created is discarded.
For Claude Code, if the browser shows a code instead of finishing, paste it into the terminal and press Enter.
If the account you sign in to already belongs to another profile, add reports that profile and adds nothing.

Workspace and Worktree Commands

Command	Purpose
`traycer workspace list`	List the folders and worktrees bound to the current Task, and which agents hold each one. Needs agent context.
`traycer worktree list`	List every worktree Traycer manages on this machine.
`traycer worktree list --include-activity`	Also show when each worktree was last active and whether its branch is ahead, behind, or merged. Slower.
`traycer worktree list --limit <n> --cursor <path>`	Page through a long list: at most `n` worktrees, starting after `<path>`.
`traycer worktree create --workspace <path> --branch <name>`	Create a worktree on a new branch. The branch forks from the workspace’s current branch, or from `--source-branch <branch>`.
`traycer worktree create --workspace <path> --existing <branch>`	Check out an existing branch into a new worktree.
`traycer worktree create ... --carry-uncommitted`	Also bring tracked and untracked changes over from the source workspace. Best effort; check the new worktree.
`traycer worktree delete --path <path>`	Delete a worktree. Runs its teardown script and shows the output. A worktree that is in use is not deleted.

For worktree create:

--workspace is required.
Pass exactly one of --branch or --existing.
--source-branch and --carry-uncommitted work only with --branch.

worktree create prints the new worktree’s path. Pass it to traycer agent create --cwd to run an agent there. Traycer creates worktrees under ~/.traycer/worktrees/. See Worktrees and Setup and Teardown Scripts.

Terminal and Comment Commands

These commands need agent context.

Command	Purpose
`traycer terminal list`	List the Task’s terminals you can read, including ones whose process has exited.
`traycer terminal output <terminal-id>`	Write a terminal’s output to a file and print the file’s path. Run it again to refresh the file. An id prefix of 4 or more characters works.
`traycer comments list [artifact-path...]`	List comment threads on the artifacts you name, or on every artifact in the Task. Filter with `--status open`, `--status resolved`, or `--status all` (the default).
`traycer comments set-status --artifact <path> --status <status> <thread-id...>`	Set threads to `open` or `resolved`.

Task Commands

Command	Purpose
`traycer task create --message <text> --harness <id> --model <id>`	Start a Task on this machine and send its first message. The first agent starts working at once and uses your provider plan. Prints the Task id and the first agent’s id. See Task Create Options.

task create runs as the person signed in with traycer login, on this machine’s host, so the host must be running (traycer host ensure). The Task is yours and appears in your Task list like one you started in the app. It needs no agent context and is refused inside an agent session. Exit code 0 means the Task and its first agent exist and the host accepted the message, not that the first turn has started. With --json, the result is { "taskId", "agentId", "alreadyCreated" }.

Task Create Options

Option	Purpose
`--message <text>`	The first agent’s first message. Required.
`--harness <id>`	Coding agent for the first agent. `traycer agent list-harnesses` lists the ids. Required.
`--model <id>`	Model. `traycer agent list-harness-models <harness>` lists them. Required.
`--title <title>`	Task title. Without it, one is generated.
`--workspace <path>`	Absolute path of a folder on this machine the Task works in. Repeatable. Without it, the first agent has no folder.
`--repo <owner/repo>`	A repository the Task is about. Repeatable.
`--reasoning-effort <effort>`	Reasoning effort, for models that support it.
`--permission-mode <mode>`	`supervised`, `auto_accept_edits`, `auto`, or `full_access`. The default is `full_access`. With `supervised`, the first turn waits for an approval nobody may be there to give.
`--profile <profile>`	Account: `ambient` for the coding agent’s own CLI sign-in (the default), or a profile id from `traycer profile list`.
`--idempotency-key <key>`	Start at most one Task for this key within 24 hours. A rerun with the same key and options prints the first run’s ids with `alreadyCreated: true`; the same key with different options is refused. Build the key from the schedule slot, such as `nightly-$(date +%F)`.

If a run with a key sends the request and cannot tell whether the Task was created, it exits non-zero naming the Task id and the key’s record file, and later runs with that key refuse instead of starting a second Task. A sign-in that expires while the request is in flight is one such case: the run does not refresh it and send again. A sign-in that had already expired when the run started is refreshed, and the run creates as usual. Check your Task list, then delete that file to use the key again. A run that finds a run with the same key still creating its Task waits for it, and exits 75 having created nothing if that run takes too long. Run it again to read that run’s result.

Agent Commands

Agent commands are for agents that Traycer launches. They read the Task and the calling agent from the environment; see Agent Context. For how agents coordinate, see Agent-to-Agent.

Command	Purpose
`traycer agent list`	List your agents in the Task, with the settings each one runs with.
`traycer agent list --all`	Include other people’s agents in the Task.
`traycer agent list --live`	Leave archived agents out. If the host is too old to report which agents are archived, the command fails and says so; update the host, or run it without `--live`.
`traycer agent list --compact`	Print one short line per agent, without folders, model, or session detail.
`traycer agent list --json`	Each agent carries `archived`: `true`, `false`, or `null` when the host is too old to report it. Each agent also carries `profile` and `permissionMode`, the values `agent configure` takes as `--profile` and `--permission-mode`, or `null` when the host cannot say.
`traycer agent create`	Create a child agent of the calling agent. See Create Options.
`traycer agent fork --agent-id <id>`	Copy an agent on this host into a new agent, starting from its latest checkpoint. Works for Chat-interface agents and Claude Code Terminal agents. See Fork Options.
`traycer agent configure`	Change the coding agent, model, and account a Chat-interface agent uses from its next turn. See Configure Options.
`traycer agent stop --agent-id <id>`	Stop an agent’s current turn. The agent is not deleted; a later message wakes it again. Add `--cascade` to also stop the agents it delegated to.
`traycer agent archive --agent-id <id>`	Archive an agent. A working agent cannot be archived; stop it first. A later message to the agent unarchives it.
`traycer agent archive --agent-id <id> --unarchive`	Unarchive an agent.
`traycer agent rename <id> <name>`	Set an agent’s display name. It needs the full agent id, and the agent must run on this host.
`traycer agent send --to <id> --message <text>`	Send a message to another agent.
`traycer agent send ... --expect-reply`	Ask for a reply. Without it, the other agent never reports back.
`traycer agent send ... --response-id <id>`	Answer a request you received from that agent.
`traycer agent transcript --agent-id <id>`	Print another agent’s conversation.
`traycer agent inbox`	Print the messages recently delivered to this agent, in full. `--after <cursor>` continues from the previous page, and `--agent-id <id>` reads a different agent’s inbox.
`traycer monitor`	Stream this agent’s incoming messages as they arrive. It keeps running, and each message it prints is marked as delivered. `--agent-id <id>` monitors a different agent.
`traycer agent selection-guide`	Print the agent selection guide, which says which coding agent, model, and reasoning effort to use. See Settings › Agent selection.
`traycer agent list-harnesses`	List the coding agents enabled on this host, with the ids `--harness` accepts.
`traycer agent list-harness-models <harness>`	List a coding agent’s models and their options.
`traycer agent list-profiles <harness>`	List the accounts available for a coding agent, with their cached usage status.
`traycer agent profile-rate-limits <harness> --profile <profile>`	Read current usage limits for one account.

agent stop and agent archive need the full agent id. agent fork accepts an unambiguous id prefix.

Create Options

The new agent’s parent is the calling agent. Settings you leave out are inherited from the calling agent where they apply, and the permission mode defaults to full_access.

Option	Purpose
`--surface <surface>`	`gui` for the Chat interface or `tui` for the Terminal interface. `tui` works only with `--harness claude`. Without `--surface`, the new agent uses the calling agent’s interface.
`--harness <id>`	Coding agent. `traycer agent list-harnesses` lists the ids. Without it, the new agent uses the calling agent’s coding agent.
`--model <id>`	Model. `traycer agent list-harness-models <harness>` lists them.
`--name <name>`	Display name.
`--reasoning-effort <effort>`	Reasoning effort, for models that support it.
`--fast`	Fast mode, for supported models on the Chat interface. It can use more credits.
`--profile <profile>`	Account: `ambient` for the coding agent’s own CLI sign-in, or a profile id from `traycer agent list-profiles`. Without it, the last-used account is used.
`--cwd <path>`	Absolute path of the working directory, such as a path from `traycer worktree create`.
`--workspace-path <path>`	Another existing folder the agent can use. Repeatable.
`--workspace-entry <source>=<run>`	Exact binding of a workspace to the worktree the agent runs in. A path on its own binds that folder as is. Repeatable.
`--permission-mode <mode>`	`supervised`, `auto_accept_edits`, `auto`, or `full_access`. The default is `full_access`.

auto is Auto mode, which is experimental: a judge approves routine commands and sends risky ones to you. Not every coding agent supports every mode; see Agents & Models.

Fork Options

Option	Purpose
`--agent-id <id>`	Required. The agent to fork.
`--name <name>`	Display name for the new agent.
`--permission-mode <mode>`	Permission mode for the new agent. The default is `full_access`.
`--profile <profile>`	Account for the new agent. Without it, the new agent keeps the source agent’s account.
`--cwd`, `--workspace-path`, `--workspace-entry`	Folders, as for `agent create`. Leave out all three to keep the source agent’s folders.

Configure Options

agent configure requires --agent-id, --harness, --model, and --profile. The changes apply from the agent’s next turn.

Option	Purpose
`--reasoning-effort <effort>`	Reasoning effort. Leaving it out sets no reasoning effort.
`--fast`	Fast mode. Leaving it out turns fast mode off.
`--permission-mode <mode>`	Permission mode. Leaving it out sets `full_access`.

agent configure does not keep the agent’s current optional settings. Any of these options you leave out is reset, so pass every one you want to keep.

Agent Roles

These commands exist only when Agent roles is turned on in Settings › General, under Agents.

Command	Purpose
`traycer agent role claim --role <name> --scope <scope>`	Claim a named role in the Task, so other agents can see who owns what.
`traycer agent role list`	List the roles your account’s live agents hold in the Task.
`traycer agent role relinquish --claim-id <id>`	Give up a role. `agent role list` shows the claim id.

Agent Context

Traycer sets two environment variables for every agent it launches:

TRAYCER_EPIC_ID is the Task the agent belongs to.
TRAYCER_AGENT_ID is the agent itself.

There is no flag for the Task. Commands that need these values read them from the environment, and a few accept --agent-id in place of TRAYCER_AGENT_ID:

Needs	Commands
`TRAYCER_EPIC_ID`	`workspace list`, `terminal list`, `terminal output`, `comments list`, `comments set-status`, `agent stop`, `agent archive`, `agent transcript`, and `agent role list`
`TRAYCER_EPIC_ID` and `TRAYCER_AGENT_ID`	`agent list`, `create`, `fork`, `configure`, `rename`, `send`, `selection-guide`, `list-profiles`, and `profile-rate-limits`
`TRAYCER_EPIC_ID`, and `TRAYCER_AGENT_ID` or `--agent-id`	`agent inbox`, `agent role claim`, `agent role relinquish`, and `monitor`
Neither	`agent list-harnesses` and `agent list-harness-models`
Neither, and refused when either is set	`task create`

Run outside an agent, these commands fail with “epic id required - set TRAYCER_EPIC_ID.” or “sender agent id required - set TRAYCER_AGENT_ID.” monitor checks the agent first: “agent id required — pass —agent-id or set TRAYCER_AGENT_ID.”

Read-Only Agents

Traycer sets TRAYCER_AGENT_CLI_SURFACE=readonly for Codex and OpenCode agents on the Terminal interface. These agents can list agents and read transcripts, but these commands are hidden from their help and refused if they run them: agent create, agent fork, agent configure, agent rename, agent stop, agent archive, agent send, agent role claim, agent role relinquish, task create, and worktree delete. The profile commands that change a profile (add, login, rename, enable, disable, remove) are refused too; profile list still works.

JSON Output

With --json, the CLI writes NDJSON to stdout: one JSON object per line. A command writes zero or more progress lines, then exactly one result line.

Line	Fields
Progress	`type: "progress"`, `stage`, `message`, `percent`, `bytes`, `totalBytes`, `timestamp`
Success	`type: "result"`, `status: "ok"`, `data`, `timestamp`
Failure	`type: "result"`, `status: "error"`, `error` with `code`, `message`, and `details`, and `timestamp`

For example, an agent command run outside an agent ends with:

{"type":"result","status":"error","error":{"code":"E_INVALID_ARGUMENT","message":"traycer: epic id required - set TRAYCER_EPIC_ID.","details":null},"timestamp":"2026-09-27T10:00:00.000Z"}

--no-progress drops the progress lines. Setting CI or TRAYCER_NONINTERACTIVE does the same.
--help and --version with --json return one result line with the text in data.output.
A few commands differ: monitor ignores --json, link-phone, profile add, and profile login do not support it, host logs ignores --follow with it, and host capabilities --json prints a single JSON document instead of NDJSON.

Exit Codes

Code	Meaning
`0`	Success.
`1`	The command failed. With `--json`, the `result` line carries the error code.
`2`	The Traycer sign-in service could not be reached (`login`, `whoami`, `link-phone`).
`75`	Another Traycer command, such as a host install or update, is already in progress. Try again when it finishes.
`130`	You cancelled a `profile add` or `profile login` sign-in with Ctrl-C.

Paths and Logs

Path	Contents
`~/.traycer/cli/credentials`	Your sign-in, shared with Traycer Desktop.
`~/.traycer/cli/config.json`	Shell, environment, and log-level settings.
`~/.traycer/cli/cli.log`	The CLI log.
`~/.traycer/cli/bin/traycer`	The copy of the CLI that the host and its agents run.
`~/.traycer/host/`	The host’s install, state, and connection details.
`~/.traycer/host/host.log`	The host log, which `traycer host logs` prints. Older logs are kept as `host.log.1` and `host.log.2`.
`~/.traycer/worktrees/`	Worktrees that Traycer creates.

These are the default paths. On Windows they are under %USERPROFILE%\.traycer\. After a data-folder move, the same relative paths are inside the selected folder; traycer data status shows it. To change how much the CLI and the host log, use CLI log level and Host log level in Settings › Host › Diagnostics.

Environment Variables

Variable	Purpose
`TRAYCER_EPIC_ID`	The current Task. Set by Traycer for the agents it launches.
`TRAYCER_AGENT_ID`	The current agent. Set by Traycer for the agents it launches.
`TRAYCER_AGENT_CLI_SURFACE`	Set to `readonly` by Traycer to limit an agent to read-only commands.
`CI`, `TRAYCER_NONINTERACTIVE`	Any value other than empty, `0`, or `false` turns on non-interactive mode: no progress output and no prompts.
`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`	Proxy settings for the CLI’s network requests. The lowercase names work too.
`NO_COLOR`	Turn off colored output.
`HOME` / `USERPROFILE`	Home folder containing the default data folder and `~/.traycer-bootstrap` location record.
`TRAYCER_DATA_DIR`	Default destination for `data init` and `data migrate` only. `--to` takes precedence. Setting it does not change the folder used at runtime.

Provider API keys and model credentials belong in Settings › Providers, not in the CLI’s environment.

Examples

Set Up a Host on Another Machine

On a machine without Traycer Desktop, such as a server you reach over SSH:

traycer login        # open the printed URL on any device and enter the code
traycer host ensure  # install, register, and start the host
traycer host status

Then connect to it from the app. See Remote hosts.

Start a Child Agent on a New Worktree

Inside an agent session, create a worktree on a new branch, then start a Codex agent there:

WORKTREE=$(traycer worktree create --workspace "$PWD" --branch fix/login --json \
  | jq -r 'select(.type == "result") | .data.entries[0].path')

traycer agent create --surface gui --harness codex --model <model-id> \
  --cwd "$WORKTREE" --name "login fix"

agent create prints the new agent’s id. Use traycer agent list-harness-models codex to find a model id.

Start a Task Every Night

On a machine where you ran traycer login, add this as one line in your crontab, replacing <model-id> with your model id. It starts one Task per day, even if the job runs twice:

0 6 * * * traycer host ensure && traycer task create --title "Nightly triage" --workspace /srv/app --harness codex --model <model-id> --message "Triage last night's failed CI runs and list the causes." --idempotency-key "nightly-$(date +\%F)"

The first agent spends your provider plan as soon as it starts. Without --idempotency-key, every run starts its own Task.

Send a Message and Get a Reply

traycer agent send --to <agent-id> \
  --message "Review the migration in db/ and list any blockers." --expect-reply

The reply arrives in the sending agent’s inbox. traycer monitor streams inbox messages as they arrive, and traycer agent inbox prints recent ones in full. To answer a request you received, pass its id with --response-id.

Diagnose the Host

traycer host doctor
traycer host logs --tail 500
traycer host logs --follow

Clean Up Worktrees

traycer worktree list --include-activity
traycer worktree delete --path <worktree-path>

To review and remove many worktrees at once from the app, see Sweep.

​Installation

​Use the CLI That Comes With Desktop

​Upgrading

​Global Flags

​Auth Commands

​Host Commands

​Check and Run

​Install, Update, and Remove

​Background Service

​Host Lifecycle

​CLI Commands

​Data Folder

​Move Existing Data on Windows

​Config Commands

​Provider Profile Commands

​Workspace and Worktree Commands

​Terminal and Comment Commands

​Task Commands

​Task Create Options

​Agent Commands

​Create Options

​Fork Options

​Configure Options

​Agent Roles

​Agent Context

​Read-Only Agents

​JSON Output

​Exit Codes

​Paths and Logs

​Environment Variables

​Examples

​Set Up a Host on Another Machine

​Start a Child Agent on a New Worktree

​Start a Task Every Night

​Send a Message and Get a Reply

​Diagnose the Host

​Clean Up Worktrees

Installation

Use the CLI That Comes With Desktop

Upgrading

Global Flags

Auth Commands

Host Commands

Check and Run

Install, Update, and Remove

Background Service

Host Lifecycle

CLI Commands

Data Folder

Move Existing Data on Windows

Config Commands

Provider Profile Commands

Workspace and Worktree Commands

Terminal and Comment Commands

Task Commands

Task Create Options

Agent Commands

Create Options

Fork Options

Configure Options

Agent Roles

Agent Context

Read-Only Agents

JSON Output

Exit Codes

Paths and Logs

Environment Variables

Examples

Set Up a Host on Another Machine

Start a Child Agent on a New Worktree

Start a Task Every Night

Send a Message and Get a Reply

Diagnose the Host

Clean Up Worktrees