Truss CLI

The CLI is the direct command-line client and the runtime service host used by editor clients.

Install

npm install -g @truss-harness/cli

See the CLI package on npm  for the latest published version and package details.

Run truss-cli in a project folder. The first time, with no model configured, it walks you through setup and then opens the chat:

1. Choose a cloud provider (with your API key) or a local model server.
2. For a cloud provider, paste your API key. It is hidden as you type, checked by loading the provider’s model list, and saved in your system keyring (libsecret on Linux, the Keychain on macOS), never in a configuration file.
3. Pick a model from the list, typing part of a name to narrow long lists.
4. Choose the default mode and tool approval.

Run truss-cli setup any time to switch provider or model. Environment variables such as ANTHROPIC_API_KEY still take priority over a saved key. Where no keyring is available, setup prints the variable to set instead. truss-cli help shows the complete built-in reference without needing a model.

Commands

Managed agents

Use agents add to create a focused workspace-local profile from the current configuration, then pass its ID to agents run. Profiles can use different providers, models, modes, and approval policies; credentials remain in the host configuration rather than the profile file. The CLI keeps the newest 50 terminal summaries in .truss-harness/agents/runs.json for other control surfaces to inspect after restart. See Managed Agents for concurrency and Edit-run safety rules.

Workspace commands

Run truss-cli init to create or refresh generated repository context in AGENTS.md. Use truss-cli update [note] to record Git state and a handoff note in durable memory, truss-cli status to inspect it, and truss-cli clear-memory to reset it. These commands do not need a configured model. truss-cli commands prints the same slash-command help used by the TUI and VS Code panel.

Chat

chat with a prompt creates an in-memory one-shot session, streams output to standard output, and prints tool requests to standard error. Run truss-cli (or truss-cli chat) without a prompt in a terminal to open interactive chat.

truss-cli chat --profile ollama-coder --mode plan "Find the files that define the agent loop"

Direct CLI chat honors --permission ask|auto-read|auto-all. Ask is the default. Interactive approval uses the same terminal input as chat; Ctrl+C cancels a pending approval or run. Without a TTY, any tool needing approval fails promptly with instructions. Authorized automation can explicitly select --permission auto-all.

Review workspace configuration and run truss-cli config trust before using its authority-bearing settings. truss-cli config status shows the effective policy and provenance. Existing or manually edited managed-agent profiles require truss-cli agents trust <id> after review; locally created profiles receive individual receipts, and subsequent manual edits invalidate them.

Interactive chat

Interactive chat keeps a transcript in your terminal’s scrollback and a composer at the bottom. Replies stream as they arrive, with a status line showing the mode, model, permissions and skills mode. File edits show a diff and terminal commands show the command before you approve them with y or deny them with n (Esc also denies).

Type /help for every command. /mode, /permissions, /skills and /model open a menu: press a number, or use Up/Down and Enter, and Esc to cancel. /model lists your provider’s models (type to narrow long lists) and switches for this session. /setup changes provider, API key or default model without leaving the chat. You can still type the choice directly, as in /mode edit or /model <profile>. Other useful commands are /new, /status and /quit. The older :mode, :clear, :help and :exit forms still work, and prefixing a message with --mode edit switches mode and sends it. Start a message with // to send text that begins with a slash.

Conversations are saved after each reply in your user configuration directory, separately for each workspace. /resume lists them and /resume <number> continues one. If a saved conversation stopped partway through a tool call, that call is marked as having an unknown outcome instead of being run again.

To include images, press Ctrl+V to attach the image on your clipboard (this uses wl-paste on Wayland, xclip on X11, and the system clipboard on macOS), or paste or drop an image file’s path. Each image appears as [image 1], [image 2] and so on in your message, and is sent along with it when the model accepts images. Up to four images of 5 MB each go with one message. Saved conversations keep the image names but not the images themselves.

Start with truss-cli --resume <id> to reopen a saved conversation directly. The first eight characters of the ID, as shown by /status, are enough.

Herdr

When the CLI runs in a Herdr  pane, it reports its state there. Herdr shows Truss as working while a reply runs, blocked while a tool approval waits for you, and idle otherwise, so its notifications and herdr agent wait work with Truss. Truss also gives Herdr the command that reopens the current conversation, so the same conversation comes back in the same pane after a Herdr restart. Nothing needs configuring: this turns on only inside a Herdr pane, and a Herdr that does not respond never slows the chat down.

When standard input or output is not a terminal, truss-cli chat falls back to a simple line-based loop with the same history and : controls.

Add --internet-access to expose web_search and web_fetch for that run. Web tool calls still follow the selected approval policy. Use --no-internet-access to override an enabled profile.

When a Plan-mode run produces a checklist, the CLI prints the saved plan to standard error. The active plan is stored at .truss-harness/plans/active.json and is automatically included in later Edit-mode context.

Service mode

truss-cli serve --profile ollama-coder

Service mode uses newline-delimited JSON on standard input/output. Output is reserved for protocol messages; do not add logs to standard output. The VS Code extension starts this service automatically.

Model discovery

truss-cli models

This prints detected endpoints and model IDs for local servers.

Skills

truss-cli skills lists skills and the effective selection. skills add <folder> imports a skill, skills remove <id> removes one of yours, and skills mode automatic|manual|off, skills superpowers on|off, and skills select <id>... change what agents use. Add --workspace to save a choice for the current workspace only. See Skills.

MCP servers

The CLI reads mcpServers from the shared configuration system and reports each connection before an Agent run. Run truss-cli config path to locate the user and workspace files. Repository-provided MCP commands require content-bound local config trust authorization. See MCP Servers for the complete schema and safety behavior.