Command reference¶
Every command line troupe takes, and every built-in command you type inside a session.
troupe --help prints the same two lists. Both are written from the tables the code
reads: the command lines from the one beside troupe's parser, and the commands inside a
session from the harness's, which the daemon serves to the terminal client and the
desktop app alike (commands.list). The two parts below are generated by
mix troupe.cli.reference in clients/tui, and the terminal client's suite fails when
they are not what the tables say, so edit the tables rather than this page.
On the command line¶
| command | what it does |
|---|---|
troupe |
open the TUI in the current directory |
troupe --workspace DIR |
open the TUI rooted at DIR, wherever it is started |
troupe --prompt "TEXT" [--workspace DIR] |
open the TUI with TEXT in its input, the cursor after it, not yet sent |
troupe --watch |
TUI with watch mode on |
troupe --no-mouse |
TUI without mouse reporting, so the terminal's own selection works |
troupe --full-send |
start with every budget/token limit lifted for the session |
troupe --private |
a private session, sealed to the plane you are signed in to |
troupe run [AGENT] "task" [--headless] [--worktree] [--auto-approve] [--full-send] [--private] [--workspace DIR] |
one task: in the TUI, or with --headless printed line by line until the agent rests |
troupe run [AGENT] "task" --profile NAME [--team TEAM] [--title "TITLE"] [--headless] |
the task on the platform, on that plane profile, as the TUI's /new would start it; a full profile is waited on, a line a wait; @profile #agent /local /platform in the task set those and are taken out of it; --team names whose session it is where more than one of your teams may use the profile |
troupe resume [SESSION_ID \| latest] [--private] |
no id: the newest session here, picker open; latest, or --private for the newest private one: straight in (troupe --resume is the same) |
troupe resume SESSION_ID\|latest\|--private --headless "message" |
one turn on that session, printed as run --headless prints it, then exit |
troupe resume SESSION_ID --repair [--headless "message"] |
wake a session on this computer whose agent cannot read its log, skipping each event it cannot read (the log keeps them), then open it or run the message |
troupe --remote [PLANE_URL] |
open HQ: teams, profiles and sessions on a plane |
troupe login PLANE_URL |
sign in to a plane with the device flow |
troupe logout [PLANE_URL] |
forget a plane's credentials and sign this machine's daemon out of it (--all: every plane); without a plane named, out of your own MCP servers too, revoked at their providers |
troupe whoami [PLANE_URL] |
print who the plane says you are, and your teams |
troupe plane-key [PLANE_URL] |
the key the plane signs what it tells clients with, as this machine pinned it at sign-in, and a new one it offers instead |
troupe plane-key accept FINGERPRINT [PLANE_URL] |
trust the plane's new signing key, by the fingerprint you checked with its administrators |
troupe setup |
set up the provider, its key, the models, a first project and the daemon at login, one screen at a time; Esc leaves with nothing written |
troupe config |
show the resolved providers and models (keys masked); with none, set them up |
troupe config --explain [KEY] [--json] |
every setting, or KEY's, and which file set it (secrets masked) |
troupe config --explain [KEY] [--json] --session SESSION_ID |
what is in force in a running session, here or on the platform you are signed in to, and where each part came from: its profile, the platform, its terms, its files |
troupe config validate [PATH] |
check the config files, or one; exits 1 on any problem |
troupe config migrate [--write] [PATH] |
show, or make, the rewrite to the current spellings |
troupe config trust [PATH] |
let a workspace's own files set the trusted keys; --list shows them |
troupe config untrust [PATH] |
take a workspace's trust back |
troupe config pull [PLANE_URL] |
fetch the organisation's defaults and limits from the plane now (a key only where it hands one to everybody) |
troupe config key |
paste a key for local sessions into your own settings, or {env:VAR} to read it from the environment; the organisation's word on where a key comes from is shown first |
troupe memory [--edit \| --clear \| --status \| --blame] |
your own memory on the plane, which every session of yours reads on every machine: show it, edit it in $EDITOR, or clear it; an agent of yours only ever adds to it. --status: which versions of the organisation's and your memory this machine holds, whether they are current, and what each session here read at its last turn. --blame: each line with who wrote it, and the agent and session of an agent's entry |
troupe artifacts list [--scope mine\|organisation\|team:NAME\|profile:NAME\|shared\|private] [--json] |
your artifacts on the plane, by who can see them, newest first; a version you have not opened here is new |
troupe artifacts open\|show ID [--version N] |
open one in the browser, through the plane's one-time address; show prints its text (a Markdown one's source) |
troupe artifacts publish FILE [--to SCOPE] [--title TITLE] [--owner me\|team] |
publish a file of this machine, as /publish does: for SCOPE (organisation, team:NAME, profile:NAME), only you without one; a team publication is the team's, every member its owner, unless --owner me |
troupe artifacts transfer ID --to team:NAME\|me |
hand one of yours to a team you are in, or take a team's back (its admins, or a platform admin); the listing says whose each is and transferable where you may |
troupe artifacts link ID |
a view link to one of your artifacts |
troupe profiles [--json] |
the profiles you may use on the plane, each with a summary: its agents, MCP servers, the hosts it reaches and its sessions |
troupe profiles NAME [--json] |
what NAME gives a session before you start one: agents (and those not here, with why), tools and MCP servers with whose access, the model, reach, limits and your teams; --json is the plane's answer as it came |
troupe models [--refresh] |
what each provider serves, its window and its price; asked again when stale, or now with --refresh |
troupe models --json [--workspace DIR] [--refresh] |
the same as one JSON object for a program: models, roles, catalog, providers; never a key |
troupe doctor [--json] |
check the setup: provider, key, models, daemon, PATH, plane; exits 1 on a failure |
troupe doctor --bench [--json] |
the same, then a turn of tool calls, a cut output, a compaction, a cancel, a replay, thinking made before a prompt change, four onboarded repositories and a memory whose command's file changed against a scripted model: offline, in seconds |
troupe instructions check [--workspace DIR] [--json] |
check the instruction files a session here reads: contradictions, missing paths and programs, repeats; and onboarded files whose source has changed, or a workspace onboarded under older rules; exits 1 on one |
troupe onboard [--workspace DIR] [--yes] [--json] [--all] |
bring other tools' instruction files, rules, agents and commands into AGENTS.md, .troupe/ and your config, each shown as a diff and written only if you say yes; a new AGENTS.md is its own question, never answered by --yes; --all asks again about what you left out |
troupe bench [--json [FILE]] [--md FILE] |
measure what a turn costs and does, offline, against the budgets CI holds; exits 1 past one |
troupe bench --live [--suite smoke\|standard] [--scenario NAME,...] [--repeat N] [--model M] [--yes] [--keep DIR] [--json [FILE]] [--md FILE] |
tasks against your own provider, under a cap it prints and asks about first; scored, and kept in a history |
troupe bench --compare [VERSION\|MODEL] |
the last live bench against the one before it, or against a version's or a model's |
troupe daemon [ARGS] |
the local daemon: run (default), status, open (the web app, connected to it), config, models, login on\|off, version |
troupe update [--check] [--recommended \| --latest \| --version X] |
install a release over this troupe and troupe-daemon, and over the desktop app and the VS Code extension where the installers put those: --recommended (the default) the version the plane you are signed in to recommends, or the latest release without one; --latest the newest release that says it supports that plane, never one the plane blocks or holds below its minimum; --version X that release. Its signature is checked against the release key this build carries, each file against the signed manifest, the daemon replaced between turns; --check says what is installed, the release and what an update would do |
troupe update --rollback |
put the troupe, troupe-daemon and desktop app (its AppImage or app bundle) from before the last update back |
troupe --version |
print the version |
troupe --help |
print the command lines and the commands inside a session |
troupe-daemon takes its own (the daemon), and
troupe daemon ... hands it everything after daemon. What a headless run's exit status
means is in the terminal client.
troupe run --profile dev "task" starts the task on the platform as /new's screen would,
titled --title or the task's first line; on a full profile it prints troupe: waiting for
a free place in dev; asking again in 2 s at each wait until the plane places it, and at the
administrator's limit it fails with the plane's sentence. The task's @profile, #agent,
/local and /platform win over the flags and are taken out before the agent reads it:
troupe run "@docs #plan write it up" --headless runs plan on docs with "write it up".
Inside a session¶
Every command starts with /. In the terminal client / on an empty line, Ctrl-K or
/help opens them as a palette, filtered as you type, and a command the session cannot
run right now is shown greyed with the reason; the desktop app's palette lists the same.
On the terminal client's main screen, with no window open, a line that is not a command
starts work rather than a chat: a branch on the default agent (build, or
default_agent) in the checkout, or on the agent and the worktree Ctrl-N picked. A
session on a pod runs one agent, and the line is said to it. In a window, /todo add
<text>, /todo complete <n> and /todo cancel <n> edit that window's task list.
The main screen also lists the worktrees of the workspace's repository, each with its
branch, how far it is from the checkout's and whether it has uncommitted work. With many
worktrees the list comes at once, and the daemon looks at as many as it can in about two
seconds, the checkout first; a worktree it did not reach shows no state rather than
clean. A workspace inside another repository follows git. In a folder the repository
tracks, the worktrees are the repository's, and /worktree makes one beside the
repository's checkout, with the agent in the same folder of it. A folder the repository
ignores (say one in its .gitignore) is a workspace of its own: it lists no worktrees,
/worktree <prompt> works in the folder itself, and /worktree name: … is refused
there.
A line that starts with ! is a shell command of your own. In the terminal client
!git status runs git status where the session runs, in its workspace (the pod's
working copy for a session on a plane), and shows what it printed and how it ended as your
command. The agent is given the command and its output before its next model call; !!
runs one without giving it to the agent. Esc or Ctrl-C kills one that runs, and the
session's shell_timeout_ms kills one that runs too long. There is no stdin and each
command is a fresh shell, so nothing interactive works and cd does not carry over to
the next. Only the session's owner may run one, and a platform that forbids the agent's
shell forbids this too (Decision 813).
Session¶
| command | what it does | needs |
|---|---|---|
/new [--private \| --remote PROFILE \| --branch] |
Start a fresh session here, without leaving the client. Opens the new-session screen and the session takes the screen; the one you left keeps running, stays in /sessions, and /back returns to it. The message comes first; under it one sentence says where it runs, the folder or the profile, and the agent, each a chip Tab and the arrows reach and Enter opens. The profile is the last used with room, else the first with room, and a line says why. @profile, #agent, /local and /platform in the message set those and are taken out of it. Enter starts (a full profile queues, and the wait is shown; Esc goes back to the form and the start goes on); Ctrl-J is a new line; Tab reaches the recent sessions, where Enter or 1-3 sets the chips like one. --private and --remote PROFILE set the chips, and --branch forks the one on screen at once: a session of its own that starts from this conversation as it stands. For example /new --branch. |
|
/cancel [window] |
Stop a branch mid-turn and remove its window. Stops the agent in the activated window, or in the one named by its tile number or path, and removes the window; a worktree Troupe made for it goes too. For example /cancel 2. |
a window: the activated one, or one named |
/dismiss [window] |
Let go of a window. Closes the activated window, or the one named: a branch's window closes for good and its session stays in the daemon, where /sessions still lists it. This session's own window stays; /back, /sessions or /new leave the session. For example /dismiss 3. |
a window: the activated one, or one named |
/merge [window] |
Land a worktree branch on the checkout. Commits whatever the branch left uncommitted, merges its branch into the checkout with a merge commit, and removes the worktree and the window. A merge git cannot complete is left for you to resolve. Tab completes the branches that have finished. For example /merge 2. |
a session on this machine |
/discard [window] |
Throw a worktree branch away. Removes the branch's worktree and deletes its branch, uncommitted work included, and closes the window. For example /discard 2. |
a session on this machine |
/compact |
Compact the conversation now, to make room. Summarises the older part of the session's conversation now, between turns, and keeps the last few messages as they are, as the session does on its own when the context window fills. Use it before a turn that will read a lot. Refused while a turn runs, and while there is too little to compact. | |
/goal [text \| clear] |
Set, show or clear the session's goal. Every later turn works towards the goal and the status line shows it. /goal alone shows it, /goal clear clears it. For example /goal make the suite green. |
|
/loop [n \| stop] |
Work towards the goal on its own. Runs turn after turn, up to n (the config's loop_max_iterations without one), until the agent says the goal is met or something stops it; the status line shows loop 2/10 and /loop stop stops it. Needs a goal. For example /loop 10. |
|
/steer [on [yes \| PERSON[:observe] ...] \| off] |
Offer this session to the plane, to steer it from another device. Offers the session to the plane you are signed in to: you can then follow and steer it from the desktop app or the console on another device, and so can each person named, by email, who may steer it, or only follow it with :observe. This computer keeps one connection to the plane while it is offered and nothing listens here; your rules and approvals hold for every prompt. /steer off withdraws it and ends every remote view at once; /steer alone says whether it is offered and who is steering. A private session is asked about first, since while it is offered what it says passes through the plane unsealed: /steer on yes offers it, to the people invited into it with control, and /steer off makes it sealed only again. For example /steer on bea@example.com cy@example.com:observe. |
a session on this machine |
/invite [PERSON [observe \| control]] |
Invite a person into this session by name. Invites a person, by email, to follow this session (observe, the default) or steer it (control): they see it in their list in the desktop app and in the console under Watch → Sessions, and act in it under its own rules. A pod session is invited at the plane, and only somebody its profile's teams cover may be; a private one from this computer, which puts its key in their own slot at the key manager, where the plane cannot read it, and somebody invited to steer it does so while you offer it (/steer on). /invite alone says whom it is shared with. A session on this computer alone is offered instead (/steer on). For example /invite bea@example.com control. |
|
/uninvite PERSON |
Take an invitation into this session back. Ends every way the invitation let them in: their open views close. A private session is sealed from then on under a new key they are never given; what they read before stays read, since an invitation cannot be taken back for what it already showed. For example /uninvite bea@example.com. |
|
/archive |
Archive this session: hide it from the session list, for everyone who sees it. Its owner's to do. The session goes to sleep and leaves the session list, yours and your team's, and is kept whole: its conversation, its workspace and its files. Anybody who could open it still can, from the archived sessions; working in it again does not bring it back. /unarchive does. For example /archive. |
|
/unarchive |
Unarchive this session: put it back in the session list. Its owner's to do. The session is back in the session list for everyone who sees it, where it was before it was archived. For example /unarchive. |
|
/rename <name> |
Rename this session: the name the session list shows. Its owner's to do. The name is the session's, for everyone who sees it, and at most 200 bytes. For example /rename Fix the parser. |
|
/keep [off], /pin |
Keep this session at the top of the session list. Its owner's to do. Kept, it is listed first, for everyone who sees it, and the platform does not clear it away when it is old. /keep off lets it go from the top. For example /keep. |
Navigate¶
| command | what it does | needs |
|---|---|---|
/sessions [archived \| n \| id], /resume |
Your sessions, newest first. Enter switches the window to one; /resume 2 or /resume <id> goes straight there. /sessions archived lists the archived ones: Enter opens one, u unarchives it. For example /resume 2. |
|
/back |
Go back to the session you were in before. Returns to the session you left with /new, /resume or HQ; /back again comes back here. One step: /sessions lists the rest. | |
/hq [plane], /remote |
HQ: a plane's teams, profiles and sessions. This machine's own sessions are listed alongside. Names a plane by URL; without one, the plane this machine is logged in to. For example /hq https://troupe.example. |
|
/observer, /agents-tree, /tree |
The agent tree: every branch and subagent. Each with its state, worktree and tokens; Enter opens the agent's transcript. | |
/files |
The session's files, live. Enter opens a file, ← goes up, r reloads; a change the session makes reloads the listing by itself. | |
/scratch [name] |
The documents an agent showed you beside the chat. Plans, reports and tables the agent put on the session's scratchpad with show; Enter opens one, and a newer version reads itself again. For example /scratch plan.md. |
|
/detail [quiet \| tools \| everything] |
How much of a transcript is open: quiet, tools or everything. Quiet shows a turn's answer with its working one strip above it; tools opens the tool calls; everything collapses nothing. For this session's screen; the transcript.detail setting is the default. For example /detail everything. |
Workspace¶
| command | what it does | needs |
|---|---|---|
/upload <path> |
Send a local file into the session's workspace. The file is read on this machine and written to session:/<name>, the directory the session works in. On the platform that is the session's own, gone when it is erased, and a worker never sees this machine's disk. In a local session it is the checkout: git sees the file, other sessions there see it, and erasing the session leaves it. For example /upload notes.md. |
|
/save <path> [to] |
Save a file of the session's workspace on this machine. The file is read where the session runs, a workspace on the platform as much as a local checkout, and written on this machine: at to, in it when it is a directory, or under its own name where the terminal started. What a file an agent made for you says to run when the session is on the platform. For example /save report.md ~/Documents. |
|
/publish <path> [private \| organisation \| team:<name> [me \| team] \| profile:<name>] |
Publish a page, a document or a file for others to read. The file is read on this machine and published on your Troupe plane as an artifact, as the person this computer's daemon is signed in as: a page (.html), a Markdown document (.md) or any other file. Yours alone unless you say otherwise, until you share a link to it; or the whole organisation reads it, a team you are in, or the people a profile is granted to, served from a host that can reach nothing of yours. A team you are not in is refused, naming yours. One published to a team is the team's, every member its owner, unless the third word is me. A page with stylesheets or scripts of its own is an agent's to publish, with publish_artifact. For example /publish report.html team:core. |
a plane |
/artifacts |
What is published for you, by who can see it. Everything published for you: for everyone at your organisation, your teams, shared with you through a link, and only you, newest first, a version you have not opened here marked new. Enter opens one in the browser, v another version of it, m reads a Markdown one here; p publishes a file of the workspace and l copies a view link to one of yours. For example /artifacts. |
a plane |
/profiles |
The profiles you may use, and what each gives a session. Every profile on your Troupe plane you may start a session on, one line each: how many agents it offers, its MCP servers, the hosts it reaches and how many sessions run on it of those it has room for. Enter opens what one gives a session, as /profile does. For example /profiles. |
a plane |
/profile <name> |
What a profile gives a session, before you start one. What the plane gives a session of yours on the profile: the agents it offers and those not there, with why; the tool rules and each MCP server, with whose access it runs (as you, once you connect it; as the profile; as the profile's own identity); the model; the hosts it reaches; its limits and budgets; and which of your teams it runs under. What the plane does not say is shown as not said. q or Esc closes it. For example /profile code. |
a plane |
/copy [window] |
Copy a transcript to the clipboard. The activated window's transcript, or tile n's; a mouse selection in the pane copies on release. For example /copy 2. |
a window: the activated one, or one named |
/memory [facts \| refresh \| forget] |
What the troupe remembers for you, and the project brief. /memory lists what every new session of yours starts knowing, entry by entry: in effect for each of your teams, and for everyone at your organisation, each team and only you, where you add, edit and forget your own. The project brief is made of facts, each anchored on the files it was read from; /memory facts lists them by kind and forgets one, /memory refresh asks the librarian to re-verify and rewrite them, /memory forget deletes the whole brief. For example /memory refresh. |
|
/context |
Every instruction file and rule, why each is in or left out, and its share of the budget. The files the next turn's system prompt is read from: your own AGENTS.md, the repository's, one in each directory down to the workspace and to the files the conversation worked on, the files they import with @path, the repository's rules in .troupe/rules (always, or once a matching file is read or edited), and the project brief, each with its scope, size and share of the budget; and every file left out, with why: another tool's file (CLAUDE.md, GEMINI.md, copilot-instructions.md, Cursor's rules), which troupe onboard brings in, a Copilot file below the root, a file outside the repository or one that can't be read, an import not followed, a rule whose files haven't been touched or that only describes itself. | |
/watch |
Toggle watch mode: act on AI! and AI? comments. A comment ending in AI! starts a quick branch in this checkout and AI? an answer one; their writes ask first. One session per workspace watches at a time. | a session on this machine |
Setup¶
| command | what it does | needs |
|---|---|---|
/settings |
Settings, and the keys and concepts worth knowing. Every tweakable setting with its value and what it does; a change is written to the config file that owns it. | |
/models, /model |
Pick the default model from every model Troupe detected. The settings page opened on the default model, with its menu up. | |
/unlink [yes] |
Stop using your account here: unlink this computer's daemon. Sessions started here are recorded under the account the daemon is linked to. /unlink says who that is and what unlinking drops: the link, the platform's token and the daemon's own sign-in, and its copy of your organisation's memory; private sessions stop being sealed until their owner links again. The sessions stay, and so does the key this computer trusts the platform's word by. /unlink yes does it, and whoever this terminal is signed in as, if somebody else, is linked instead: how a second person on this login takes the daemon over. For example /unlink yes. |
|
/mcp [import\|link\|remove\|check\|add\|try\|secret <target>] [--workspace] |
Your MCP servers: each one's layer, state, tools and errors. Servers from your mcp.json, the workspace's .troupe/mcp.json and the bundle. import copies a .mcp.json, link reads it in place, remove and check take a server name; add <name> writes one (flags such as --env K=V, --header K=V and --oauth, then a URL or a command and its arguments) and try runs it once without keeping it; secret <name> <KEY> asks for a value and keeps it in the keychain; --workspace writes the workspace's file. For example /mcp import .mcp.json. |
|
/skills [import\|link\|remove <target>] [--workspace] |
Your skills: each one's layer, description and source. Skills from your skills/ directory, the workspace's .troupe/skills/ and the bundle; import copies a directory of skills, link reads it in place. For example /skills link ~/.claude/skills. |
|
/help, /? |
Every command, what it does and how to type it. Type to filter by name, alias or description; ↑↓ move, Enter runs, Tab puts the command on the line, Esc closes. / on an empty line opens it too. |
Agents¶
| command | what it does | needs |
|---|---|---|
/agents |
Read, copy, create, edit and delete the agents. The agent picker that Ctrl-N and Tab open, with every agent, subagents too, each with where it comes from (Shipped, Your organisation's, Yours or This repository's), its mode, model and tools, whether it is read-only and what it stands in for; Enter reads its whole instruction and b starts a branch on it. An edit (e) opens your editor and is checked and saved by the daemon into your agents/ or the repository's .troupe/agents/; c copies one into a layer, n makes a new agent from the one selected (a built-in or your organisation's too), x deletes a copy. A save comes back to the picker on what was saved. Each is a command of its own, below, and Tab in a window switches the agent it runs. | |
/worktree [name:] <prompt> |
Run the default agent on a branch in a worktree of its own. /worktree <prompt> works in a fresh worktree, to /merge or /discard later; /worktree <name>: <prompt> in a Troupe worktree of that name, created the first time and reused after; /worktree <existing> <prompt> in one you checked out (Tab completes them). For example /worktree fix the flaky test. |
a session on this machine |
/workflow [name:] <task> |
Run a workflow's steps through subagents, in a worktree of its own. /workflow <task> runs the bundled pipeline (understand, plan, implement, test, document, verify) on orchestrate, which delegates each step to the subagent that owns it and edits nothing itself; /workflow <name>: <task> runs the steps of .troupe/workflows/<name>.json instead. The branch is to /merge or /discard later. For example /workflow release: cut 1.2. |
a session on this machine |
Quit¶
| command | what it does | needs |
|---|---|---|
/quit, /exit, /q |
Leave the terminal client; the session carries on. Sessions live in the daemon, so nothing stops; troupe resume comes back to this one. Ctrl-C twice does the same. |
Besides these, each agent is a command that starts a branch on it: /build <prompt>,
/plan <prompt>, and whichever agents your config, your team's bundle or the
repository's .troupe/agents/ add (/agents manages them). So is each command you or the
repository write as a markdown file, /<name> [arguments], under Custom in the palette
(your own commands).