CLI reference

repose --help, repose help COMMAND and repose COMMAND --help print the same in your terminal. A mistyped command gets a suggestion and exit code 2:

$ repose lss
unknown command "lss" for "repose"
Did you mean `repose ls`?
`repose --help` shows its usage.

Words other CLIs use lead to the repose command: up, create, new and init to run, shell and connect to ssh, down to stop, port, forward and tunnel to open, env to secrets, undo to restore, clone to fork. A mistyped subcommand gets the same answer with --help after it. So does a mistyped flag, or another tool's spelling of one: docker's detach flag on run names -d, and a force flag on stop names -y.

#Which project

Commands that act on a project take it from the PROJECT argument, --project NAME, then REPOSE_PROJECT; an argument and a --project that disagree exit 2. Otherwise it's the folder you're in: the project with this checkout's git remote, or the machine last made there in a folder with no remote. A home folder belongs to no project, so a command there has to name one.

A command whose usage names the project takes it there or as --project. A few take other words in that place, so the project is --project alone: open, secrets set, secrets rm, secrets import, secrets choose, config add, config remove, config apply, mcp forward and mcp rm; cp names it in PROJECT:PATH or --project. ls, login, logout, notify, version and completion act on no project and exit 2 when given --project.

PROJECT:CHECKOUT names another checkout run --on added to the machine. run, attach, sync, exec, ssh, code, rm, mcp list, mcp forward and browser bridge take it; every other command refuses it with exit 2.

Global flags: --project NAME, -v/--verbose and --version. -v writes a line to stderr for each request, with its status, duration, request ID and the body of a refusal, and one for each ssh the command runs; never a token or a header.

#Working on a project

#repose run [PROJECT]

Create or start this checkout's machine and attach. PROJECT is the machine of that name, created if there is none: a second machine for this checkout, or one for a folder with no git remote. A new machine gets a copy of your checkout. One that already has it is left as it is, and run says when your laptop has work to send with repose sync. A changed repose.nix at the repository's root is applied in the background (repose.nix in your repository). run and attach write your CLI's version to ~/.repose/cli-version on the machine, so an agent there can tell when your CLI is older than these docs.

Starting a machine needs a plan. Without one, run opens the billing page, prints Waiting for a plan at https://repose.herakraft.co/billing... and waits up to 30 minutes for you to choose. Off a terminal it exits 7 with Choose a plan at https://repose.herakraft.co/billing first.

#repose attach [PROJECT[:CHECKOUT]] [WINDOW]

Attach to the project's session, on its current window, without syncing. WINDOW (or -w/--window NAME) opens on that window instead: a name or number as repose ps shows it, or on herdr an agent's name. If a project resolves, one word that names none of your projects is WINDOW. A window the session doesn't have exits 2.

A machine that isn't running comes up first, as repose start does. A machine being removed, or one stopped for running a miner, exits 5.

A herdr project attaches in three ways. --bridge bridges your Chrome to the machine for as long as you're attached; --bridge-allow HOST does that with an allowlist.

If the connection drops while you're attached, run and attach print repose: lost the connection to todo-app. Reconnecting; Ctrl-C stops. and come back on their own. Keys you type while it waits are dropped. With REPOSE_NO_INPUT_PROXY=1, the command ends with exit code 255 instead.

#repose sync [PROJECT]

Copy this checkout's current work over the machine's checkout, without attaching. It creates or starts the machine if needed. PROJECT works as on run: the machine of that name, created if there is none. It only sends; git fetch repose brings the machine's commits back.

It writes nothing and exits 6 when the machine changed files your laptop changed too, and names them, or when the machine's checkout is in the middle of a merge, rebase, am, cherry-pick, revert or bisect. Changes the machine made to any other file stay where they are (When the machine has changes of its own). In your home folder, and in a folder that isn't a git checkout, it exits 2.

--stash-machine and --discard-machine were --stash-remote and --discard-remote, which still work for one release. repose run given any of them exits 2 and names this command.

#repose ps [PROJECT] [WINDOW]

The project's windows, without attaching. Needs the machine running.

$ repose ps
WINDOW      COMMAND  STATE        TREE        ACTIVE
0:shell     bash     -            checkout    3h ago
1:claude*   claude   working      checkout    now
2:claude-2  claude   needs input  worktree-1  12m ago

WINDOW is the window's number and name, with * on the one attach opens on. COMMAND is the program in the window's active pane, its name and never its arguments. STATE is the agent's state; - is a window with no agent, or one whose agent exited or never reported. TREE is the folder the window works in, checkout, worktree-N, ~/PATH, or the path itself outside your home folder, as exec --workdir takes it. ACTIVE is how long since the window last printed. -q/--quiet prints the names alone, one per line.

A herdr project lists herdr's agents instead, under WORKSPACE, AGENT, NAME and STATE, with * on the focused one.

With WINDOW (or -w/--window NAME), it prints that window's last 20 lines instead, unwrapped; -n/--tail N for N lines, 1 to 10000. -n without a window prints every window's, each under a ==> 1:claude <== line. On herdr, WINDOW is an agent's name. Where a project resolves, one word that names none of your projects is WINDOW: repose ps claude-2 in the checkout.

--json gives one shape on tmux and herdr: name, agent, command, agent_state, tree, focused and idle_seconds, with null where the multiplexer can't say (command and idle_seconds on herdr; agent and agent_state for a window with no agent). agent_state spells needs input as needs_input, and reads unknown where an agent exited or never reported, which the table shows as -. state repeats agent_state, except on herdr, where it keeps herdr's own word (blocked, done) for this release. For this release it also keeps the old keys: index, current and activity on tmux, workspace on herdr.

#repose exec [PROJECT[:CHECKOUT]] [--] COMMAND [ARG...]

Run one command in the checkout on the machine, with your secrets and the project's dev shell, as an agent there has them. Output streams back and the exit code is the command's. Needs the machine running. The command is passed word for word, its own flags included, and no shell expands it; for a pipeline, run a shell yourself. If the first word names one of your projects, it is PROJECT; that name with no command after it exits 2. To run a command that has a project's name, put -- before it. Put exec's flags before the command.

$ repose exec npm test
$ repose exec todo-app git log --oneline -3
$ repose exec -it psql
$ repose exec sh -c "npm run build && npm test"

-i/--interactive passes your input to the command; -t/--tty gives it a terminal. Without either, the command reads nothing. Pass both for anything interactive.

--workdir DIR runs the command in DIR instead of the checkout: worktree-N for a --worktree agent's worktree, checkout, ~/PATH, /PATH, or a path inside the checkout, each of the first two with an optional /SUBDIR. A folder that isn't there exits 2 before the command runs.

$ repose exec --workdir worktree-1 npm test

#repose ssh [PROJECT[:CHECKOUT]]

Open a login shell in the checkout on the machine, outside the session attach opens; exit ends it. A machine that isn't running comes up first, without a sync, as with attach. A command after PROJECT exits 2 and names repose exec.

#repose code [PROJECT[:CHECKOUT]]

Open the project's checkout, /home/dev/<folder> (Where the checkout is), in an editor on your laptop, over SSH to <project>.repose. A machine that isn't running comes up first, as with attach. It uses VS Code (code) if it's installed, else Cursor (cursor), else Zed, whose command is zed or zeditor; on a Mac it also looks in /Applications and ~/Applications. A named editor that isn't installed exits 1, as does having none of the three. Under WSL it refuses an editor whose command is the Windows app, which would connect with Windows' ssh (Windows).

$ repose code todo-app
Opening todo-app.repose:/home/dev/todo-app in VS Code

#repose open [LOCAL:]PORT

Forward one port to your laptop and open it in the browser, until Ctrl-C. Needs the machine running. Works for servers on 127.0.0.1, 0.0.0.0 or ::1. With nothing listening on the port yet, open says Nothing on todo-app is listening on port 3000 yet; the forward reaches it once it listens on 127.0.0.1 or 0.0.0.0. and forwards to 127.0.0.1 anyway. The laptop port is PORT, or LOCAL with repose open 8080:3000; when it's taken, a free one, and open says which. The database ports 5432, 3306, 6379 and 27017 open no browser. If the connection drops, open reconnects on the same laptop port, for up to 2 minutes.

--local-port N, the old form of LOCAL:, still works.

#repose browser [PROJECT]

Watch the agents' browser on the machine and take it over. It starts the machine's desktop view, forwards it in the background to laptop port 6080, or a free one when that's taken, and opens the link in your browser. The view is the size of your tab and sleeps after 30 idle minutes; opening the page again wakes it. Needs the machine running.

repose open --desktop, and --no-open and --stop on repose browser, are old names and still work.

#repose browser stop [PROJECT]

Stop the view on the machine and the forward on your laptop. The agents' browser keeps running. On a stopped machine it clears the laptop's forward alone.

#repose browser bridge [PROJECT]

Let the agents on the machine browse in your laptop's Chrome, with your logins and extensions, until Ctrl-C: their browser tools drive it instead of the machine's own.

$ repose browser bridge
Chrome 144 → todo-app: the agents there browse in your Chrome now,
with your logins. Ctrl-C hands them back the machine's browser.
Chrome asks you to allow each new connection.
Pages the agents open are listed below (host and path only).
An agent on todo-app is in your Chrome.
14:03:21  admin.internal.example/signups

Needs the machine running, and Chrome 144 or newer with its remote debugging switch on.

Stop it has what ends a bridge, and why only one reaches a machine at a time.

#repose mcp forward NAME...

Let the agents on the machine use MCP servers that run on your laptop, until Ctrl-C. NAME is a server in your laptop's Claude Code config (this project's servers, then your user scope), Claude Desktop config (macOS), Codex config or Gemini CLI settings, or the command after --, which goes with one NAME. It runs on your laptop, with your apps, files and tokens. ${VAR} in its config comes from your laptop's environment, and a ${VAR} that environment lacks stops the forward before it starts. Only servers that start with a command can be forwarded; an HTTP server on your laptop can't be yet. Each agent session on the machine gets its own copy, and each call is printed here by agent and tool.

$ repose mcp forward apple-notes
apple-notes: forwarded to todo-app (12 tools). Agents already
running list it after a restart. Ctrl-C ends it.
claude called apple-notes.search_notes

$ repose mcp forward notes -- node ~/mcp/notes.js

Needs the machine running; a machine that stops ends the forward with exit code 5. The agents keep listing NAME after Ctrl-C; until the next forward, its tools answer that your laptop isn't connected. A laptop that goes to sleep brings the same answer within about 20 seconds. A dropped connection is named once and retried. A second forward of the same NAME takes over from the first. [mcp] forward in config.toml forwards servers whenever you're attached.

--remove is the old form of repose mcp rm NAME.

#repose mcp rm NAME...

Alias remove. Take forwarded servers off the machine's agents; they drop them at their next start. Needs the machine running. A NAME the machine has no forward for exits 1: todo-app has no forwarded MCP server named linear.

#repose mcp list [PROJECT]

Every MCP server the agents on the machine have, and the ones your laptop kept. Alias repose mcp ls, and repose mcp alone. It starts no server. Needs the machine running.

$ repose mcp list
NAME         FROM     AGENTS                           STATE
playwright   repose   claude codex gemini opencode pi
linear       laptop   claude codex gemini opencode pi  needs LIN_TOKEN
xcode        laptop   none                             an Apple app
notes-db     project  claude                           ~/todo-app
apple-notes  forward  claude codex gemini opencode pi
my-db        machine  claude

FROM is repose for the browser tools, laptop for a server copied from your laptop's Claude Code or kept there (AGENTS none, the reason in STATE), project for a checkout's .mcp.json (Claude Code only), forward for repose mcp forward, and machine for one you added on the machine. STATE is empty when the server needs nothing. It starts with the checkout for a server that belongs to one (~/todo-app), reads laptop not connected for a forwarded server whose laptop is away, and names each agent that lacks the server with why (codex: ~/.codex/config.toml is a link, which repose does not write). A file repose had to leave out, such as a laptop.json that doesn't parse, is named on stderr after the rows. Piped, each server is one tab-separated NAME FROM AGENTS STATE line with no header.

#repose cp [-r] SRC... DST

Copy files with scp. One side names the machine: PROJECT:PATH, or :PATH for this checkout's project. A relative path on the machine starts in its checkout, or in /home/dev on a machine with no checkout. -r/--recursive copies directories. Several sources go into the directory DST, so a shell glob works: repose cp ./Fwd_* todo-app:/tmp/. Sources sit on one side and name one project; anything else exits 2. Needs the machine running.

#repose paste [PROJECT]

Copy the image on your clipboard, up to 50 MB, to /tmp/repose-paste/ on the machine and paste its path into the active pane on tmux, or herdr's focused pane. The path is pasted; you press Enter. Needs the machine running. It exits 1 with no image on the clipboard, and on Linux with no clipboard tool, where the message names wl-clipboard on Wayland or xclip on X11.

#repose scan [DIR]

List what the next repose run would install on the machine, and why. Installs nothing. DIR defaults to this checkout's root. The list comes in two halves: your laptop's global tools, and the commands the project's scripts call that neither the machine's base nor the project's own dependencies provide. The project half ends with the version pins it found: Node, Ruby and Java with the version the machine gets. A machine.nix or a repose.nix takes over a half; a skipped: line says which half and why. Logged out, or when the server doesn't answer, it reads ~/.config/repose/machine.nix and says the account wasn't checked. --json prints laptop, project, node, ruby, java and skipped.

#Projects

#repose ls

Every project in a table. * after a name marks the project a command run here with no PROJECT acts on (Which project). repose projects, the old name, still works.

STATE reads running frozen for a machine repose froze while idle.

AGENTS names the agent and its state, with how long one that needs input has waited: claude: needs input 4h. A ? means the machine's last report is two minutes or older, and never appears on a frozen machine, whose agents can't have moved on. Several agents are counted by state, needs input first, with the longest wait: 2 agents: 1 needs input (4h), 1 working.

LEFT is a column only while a temporary machine is listed: its time left, or up once that has run out (Temporary machines). DISK is a column only while a listed project's disk is 90 percent full or more, and reads 93% full.

A line under the table names each running project nobody has used for a day (Unused machines). The last line is your plan and how much of it is in use: memory running, the disk your projects hold, egress this month. Under it, a line for each limit in the way: disk over the plan (Projects), egress past the allowance (Egress), a payment that failed (If a payment fails).

--json prints the full records. --destroyed lists the destroyed projects repose restore can still bring back, one row per name with the earlier destroys counted; --all goes with --destroyed and lists every row, each with the ID that restores it. -q/--quiet prints the names alone, one per line:

repose stop $(repose ls -q)

#repose status [PROJECT]

One project in detail:

$ repose status
todo-app  running 2h14m  large
  agents     claude-2 needs input 4h, claude working
  checkout   main: 3 commits not on this laptop, 2 files not committed
             worktree-1: nothing new
  attached   nobody
  listening  node :5173 up 3d 410.0 MB
  disk       6.2 GB of 39.0 GB (40G disk), snapshot 11h08m ago
  last event 14m ago, claude finished "Added auth flow"

A machine repose froze while idle has frozen after the state in the header, before the size. status reads the machine itself for the checkout and the listening ports, so it wakes a frozen one; repose ls reads none of that and leaves it frozen.

checkout has a line for the machine's checkout and one for each git worktree beside it: the branch, its commits your laptop doesn't have (git fetch repose gets them), and the files git status lists. Your laptop's commits are read from every checkout of the project on it, wherever you run the command; with none, the line gives the last commit's age instead. A running machine that doesn't answer in 4 seconds gets one row instead: checkout unknown (no ssh answer in 4 s). A stopped project shows the rows its last stop from this laptop read, with when it read them: main: 3 commits not on this laptop (at the stop, 9h ago), or unknown at the stop, 9h ago (no ssh answer in 15 s) when that read failed.

listening gives each listening process, its port, how long it's been up and its memory, and so which ports an attach forwards. A docker row counts the containers running. disk is the machine's filesystem, used over size, then the disk's size as repose resize names it; the filesystem keeps a few percent of the disk for itself. That figure comes from the machine, or from its last sample when it doesn't answer, and with neither the row is the disk's size alone. -v adds a host row with the server and the machine's address.

Above the rows, one line each for what needs you: the machine unused for a day or stopped for a miner, a temporary one's end. Then settings a new project wouldn't get (setup: agent codex, machine.nix off, base updates held, kept awake), an error or a new system that didn't boot, repose's service not answering, which makes the rows under it old, a disk 90 percent full with the repose resize that doubles it up to 320 GB, and the plan warnings repose ls prints.

#repose start [PROJECT]

Start a stopped machine, or restart one in error. Doesn't sync. One starting is waited for; one stopping or being restored is waited out and then started; one whose server is restarting waits for the server. A machine already running prints todo-app is already running., unless repose's service on it stopped answering, which restarts it. --json prints the project as JSON when done.

#repose stop [PROJECT...]

Stop the machine and snapshot its disk, several projects at once with one line each (Stop and start).

Before a machine goes it runs git fetch repose in every folder on this laptop whose repose remote is one of the machines being stopped, wherever you run it, and prints what came: Fetched 3 commits on repose/main., or Fetched 3 commits on repose/main in ~/code/api. for a folder other than the one you're in. A fetch that fails is one line on stderr and the stop goes ahead. The stop line ends with what stays on the machine: Stopping todo-app; 3 commits on main not fetched, 4 files not committed. Commits are counted only where this laptop has a checkout of the project. The read of the machine gets 15 seconds, and the clause says when it didn't answer: Stopping todo-app; checkout unknown (no ssh answer in 15 s)., or (ssh failed: Connection refused). A machine already stopping prints todo-app is already stopping., a stopped one todo-app is already stopped.

-w WINDOW closes that agent's window, a name or number as repose ps shows it, or on herdr an agent's name, where only its pane closes. It asks about a busy agent as a stop does. On tmux it also removes the window's worktree when nothing there would be lost, after the same fetch: Closed claude-2 on todo-app and removed its worktree ~/todo-app-worktree-2. The branch stays on the machine. Otherwise the worktree stays and the line names what kept it: Closed claude-2 on todo-app; its worktree ~/todo-app-worktree-2 stays: worktree-2 is not fetched to this laptop.

#repose rm [PROJECT...]

Delete the machine and disk; a final snapshot is kept 30 days, and a temporary machine keeps none. A running machine's commits are fetched first, as stop fetches them. Several projects get one question, which names any working or needs input agent. -y/--yes skips the question (required without a terminal), and the line then says until when the snapshot is kept. --wait waits for the destroy. Run in the project's checkout, it removes the repose git remote.

repose rm PROJECT:CHECKOUT removes only a checkout run --on added: its folder and its worktrees on the machine, and the link from your laptop folder. Needs the machine running. Nothing is fetched first, and the question names what goes: Remove ~/api from todo-app? It is deleted with its worktrees, uncommitted work and any commits you have not fetched or pushed. [y/N] It exits 6 while a process works in one of those folders, and 2 for a PROJECT:CHECKOUT passed beside any other name.

repose destroy, the old name, still works.

#repose keep [PROJECT] [DURATION]

Make a temporary machine a normal one, no longer destroyed when its time runs out. With DURATION it stays temporary and is destroyed that long from now instead: tmp-k3f9 is temporary until Sep 29 17:02. DURATION is 10m to 24h, such as 3h; 1d is 24h. One argument that is a number and a unit (s, m, h, d or w) is DURATION, so a project called 2fa is a project. It adds no git remote; reach it by name. On a project that isn't temporary it prints todo-app is not temporary. and does nothing.

#repose restore [NAME]

Bring back a project destroyed in the last 30 days (Destroy and restore). --as NEW-NAME restores under another name, --snapshot ID names the snapshot. With no NAME it takes the destroyed project whose git remote is this checkout's, and asks which one when several share that remote. It asks for a name when a live project holds this one, and exits 2 naming --as without a terminal. A destroy still running is waited out for up to 3 minutes, then exits 1. It ends with Restored todo-app from its 2.1 GB snapshot of 2026-10-08 21:37 in 1m12s; it is running (large).

#repose fork [PROJECT]

Copy the project's disk as it is now into new projects, each on its own machine. The project itself keeps running. Without --snapshot it has to be running or stopped: a stopping one is waited out, and any other state exits 5.

In a checkout whose repose remote is the project's machine, each copy gets a git remote of its own name; repose rm of a copy removes that remote again.

Each copy is a project, and counts toward the 100 an account can have and toward your plan's disk and memory. A fork that would pass any of those is refused before anything is copied and exits 7; the memory refusal names --no-start.

#repose resize [PROJECT] [DISK]

Grow the project's disk: repose resize 80G, or repose resize todo-app 80G for a project other than this checkout's. DISK needs a unit, M, G or T, all binary (80G, 80GB and 80GiB are one size); a bare number exits 2. Disks can't shrink: a smaller size exits 2 and names the disk's size, and a size it already has changes nothing. A grow ends with Resized todo-app's disk to 120G. One argument that reads as a size is DISK; anything else is PROJECT. A disk past your plan's ceiling for one project exits 7.

--size small|large|xl changes the project's size, for example repose resize --size xl when the machine keeps running out of memory. A running project has to be stopped for the change, so it asks first: todo-app is running. Changing it from large to xl stops it, which ends every process on it, agents included, then starts it again. Go ahead? [y/N]. -y/--yes skips the question and is required without a terminal. A size your plan can't run beside what runs now exits 7 before the question, and nothing is stopped. The change ends with Changed todo-app from large to xl: 4 cores, 16 GB memory; needs the Plus plan. Running again in 43s.; a stopped project's line ends It starts at the new size. instead of the time.

DISK and --size go in one command, the disk first: repose resize todo-app 160G --size xl. With neither, it exits 2. --json prints the project as JSON when done.

#repose logs [PROJECT]

One of the machine's logs: --kind console|build|ops, default console. Lines come oldest first. A stopped machine, or one in error, still has its logs.

console is what the machine printed during a boot that failed: the last 200 lines of each such boot, 16 KB at most, over its last 20 operations. A machine that booted cleanly has none. build is the last configuration build's log. ops is one line per operation: its kind, how it ended (done or failed) or that it hasn't (pending, running), how long it took, and a failed one's error code and message:

2026-10-08T21:38:02-04:00 stop done 4.2s

-n/--tail N keeps the last N lines of the first read; -f/--follow then prints each new line, polling every 2 seconds. --json prints one JSON object per line.

--since on logs and events takes a duration back from now (90m, 2d, 1w, 1d12h), a date (2026-10-01, from local midnight) or an RFC 3339 time (2026-10-01T08:00:00Z). Anything else exits 2. logs has no default; console and build hold only the last boots and build.

#repose events [PROJECT]

Every event in the window, oldest first, one per line: time, the agent and its window, what happened in the word its notification uses, the summary. Outside a checkout, with no PROJECT, it covers every project and adds a project column. --since 3d sets the window (default 24h); its forms are under repose logs. -f/--follow polls for new events every 10 seconds. --json prints one JSON object per line, with the event's kind and project. An empty window prints No events on todo-app in the last 24h. on stderr.

2026-10-08T20:58:30-04:00  -           snapshot  taken (stop)
2026-10-08T20:59:04-04:00  claude (1)  finished  Added tests
2026-10-08T21:12:40-04:00  claude (2)  asks      Drop old table?

#repose questions [PROJECT]

The questions agents are waiting on you to answer.

todo-app  claude-2 asked 12m ago, expires in 18m  (id 7f3a1c2d)
  Drop the legacy sessions table?
  options: yes|no

The window is the one repose attach takes, or the agent's name where the window has none; the id is the question's last 8 characters. With no PROJECT it covers every project on your account. Only PROJECT or --project narrows that, not the checkout and not REPOSE_PROJECT.

Agents waiting at a prompt in their own terminal, such as a permission prompt, come after the questions, by window and project. repose reply can't answer those; repose run PROJECT -w WINDOW -p TEXT types into the window instead.

-q/--quiet prints only the question ids, whole. --json prints the questions alone; repose ls --json carries the agents at a terminal prompt, in each project's signals.agents with state needs_input.

#repose reply [PROJECT] [--] [ANSWER...]

Answer a waiting question: repose reply todo-app yes. The first word is the project when it names one of your projects; otherwise every word is the answer. Put -- before an answer that starts with a project's name: repose reply -- todo-app is fine. A project with no waiting question exits 1. With several waiting it lists them and exits 2; name the project, or pass --question ID, a whole id or its last characters as repose questions shows them. With no answer it asks for one in the terminal, and off a terminal exits 2. The answer to a question with options has to be one of them. A question answered or closed before your answer lands exits 1 and says how: Not sent: answered in the terminal. --json prints the answered question.

repose reply --dismiss [PROJECT] cancels the waiting question without an answer, chosen the same way. With no question waiting it exits 1, as reply does. One that closed before the dismiss landed exits 1 with Not dismissed: answered in the terminal.

#Snapshots

SNAPSHOT_ID is a whole id, or its last or first characters (4 or more) when only one snapshot has them. --as-new is the old name of --as.

#Secrets

An account secret is for every project, so --global beside a project exits 2.

#Configuration

With --global, the same commands act on your machine.nix instead of the project's file. --global takes no project; on and off take one, with or without it. add and remove edit the file's home.packages = with pkgs; [ ... ]; list and push it, edit opens the laptop's copy and pushes it on save, show prints the account's copy, revisions lists its saves, and apply [PATH] pushes a file over the account's copy, by default ~/.config/repose/machine.nix; an empty file removes it. repose config show --revisions is the old form of revisions.

The CLI's own settings are keys in config.toml; repose config set exits 2 and names the file.

#Account

#config.toml

~/.config/repose/config.toml is optional.

default_size = "small"
default_agent = "codex"
editor = "cursor"
default_multiplexer = "herdr"

[sync]
exclude = ["dist", "*.mp4"]

[logins]
skip = ["gh"]

[projects.todo-app.logins]
skip = ["gh", "env"]

[mcp]
forward = ["apple-notes"]

[projects.todo-app.mcp]
forward = ["figma"]

#Environment variables

#Other servers

The CLI talks to the hosted repose until you point it somewhere else with --api-url URL, REPOSE_API_URL or api_url in config.toml, first of those wins. --help leaves --api-url out. The URL carries a version prefix, as the hosted https://api.repose.herakraft.co/v1 does. logto_issuer picks the login server and logto_client_id the CLI's application there; it has to be a Logto, since the CLI reads OIDC discovery from /oidc under the issuer.

repose login --browser logs in through a browser on this computer instead of a code, and needs a login application that registers a loopback redirect URI. The hosted one registers none, so --browser there, where a browser can be opened, waits 5 minutes and exits 3 with Login failed: timed out waiting for the browser login (5 minutes).

#Files on your laptop

repose logout --purge removes all of these but the repose remotes and machine.nix, which is yours; git remote remove repose removes one remote.

#Output

Tables print local time to the minute (2026-10-08 21:37); logs and events print local RFC 3339; --json prints UTC. Progress lines go to stderr. Without a terminal each step prints a line when it starts, that line with its time every 30 seconds while it runs, and a ✓ line with its time when it ends, unless the command prints the step's result itself. Scripts should read --json or -q: the text of tables and messages can change between releases.

#Exit codes

Once run, attach or ssh has connected you, the exit code is ssh's; 255 means the connection dropped and the command could not reconnect. repose cp returns scp's. repose exec returns the command's code once the command has started, so a 4 from your test runner is the test runner's; the codes above come only from failures before it starts, and each prints a message first.