> ## Documentation Index
> Fetch the complete documentation index at: https://docs.traycer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Reference for the traycer command: sign-in, running and updating the host, configuration, worktrees, and agent automation.

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.

<Tabs>
  <Tab title="npm">
    Requires Node.js 22.13 or later.

    ```bash theme={null}
    npm install -g @traycerai/cli
    ```

    The npm package is [`@traycerai/cli`](https://www.npmjs.com/package/@traycerai/cli).
  </Tab>

  <Tab title="Homebrew">
    On macOS and Linux. Homebrew installs a standalone binary, so Node.js is not needed.

    ```bash theme={null}
    brew install traycerai/traycer/traycer
    ```
  </Tab>
</Tabs>

Check the install:

```bash theme={null}
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.

```bash theme={null}
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](#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. |
| `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](/account/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 `~/.traycer/cli/credentials`, 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, and recent activity. 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` | Remove the installed and staged host files. The OS service stays registered, and a running host keeps running. |
| `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 or credentials under `~/.traycer`.

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 `~/.traycer/host/`.

### 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](/settings/general#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`. |
| `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>`. It does not install older versions. |
| `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. |

## Config Commands

The shell and environment settings apply when Traycer starts the host and opens terminals. They are the same settings as [Settings › Shell](/settings/shell), stored in `~/.traycer/cli/config.json`.

| 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](/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](/settings/providers#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](/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](#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](/concepts/worktrees) and [Setup and Teardown Scripts](/concepts/worktrees/scripts).

## Terminal and Comment Commands

These commands need [agent context](#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`. |

## Agent Commands

Agent commands are for agents that Traycer launches. They read the Task and the calling agent from the environment; see [Agent Context](#agent-context). For how agents coordinate, see [Agent-to-Agent](/concepts/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. |
| `traycer agent create` | Create a child agent of the calling agent. See [Create Options](#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](#fork-options). |
| `traycer agent configure` | Change the coding agent, model, and account a Chat-interface agent uses from its next turn. See [Configure Options](#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 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](/settings/agents). |
| `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](/panels/agents#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](/agents-and-models/coding-agents).

### 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`. |

<Warning>
  `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.
</Warning>

### Agent Roles

These commands exist only when **Agent roles** is turned on in [Settings › General](/settings/general), under **Experimental**.

| 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`, `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` |

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 stop`, `agent archive`, `agent send`, `agent role claim`, `agent role relinquish`, 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:

```json theme={null}
{"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. |

On Windows, the same paths are under `%USERPROFILE%\.traycer\`.

To change how much the CLI and the host log, use **CLI log level** and **Host log level** in [Settings › Host › Diagnostics](/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](#read-only-agents). |
| `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` | Where the CLI finds `~/.traycer`. |

Provider API keys and model credentials belong in [Settings › Providers](/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:

```bash theme={null}
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](/concepts/hosts/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:

```bash theme={null}
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.

### Send a Message and Get a Reply

```bash theme={null}
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

```bash theme={null}
traycer host doctor
traycer host logs --tail 500
traycer host logs --follow
```

### Clean Up Worktrees

```bash theme={null}
traycer worktree list --include-activity
traycer worktree delete --path <worktree-path>
```

To review and remove many worktrees at once from the app, see [Sweep](/concepts/sweep).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.