Command line

Commands reach the app over a socket of its own, $XDG_STATE_HOME/herdr/gpui/control.sock (default ~/.local/state/), which only your user can open; on Windows, over a named pipe (see Windows). An agent on an SSH host has no path to it; there, the app's shim at ~/.local/state/herdr/gpui/bin/sheprd offers browser open and browser reload through Herdr workspace metadata (see remote agents), and every other command exits 8. A few commands work from files alone and need no running app; they say so below.

On Windows, sheprd.exe is a console program, so a shell waits for it and sees its exit code; the installers put its directory on PATH. The Start menu opens sheprd-launcher.exe instead, which starts it without a console window.

sheprd --help              # every command
sheprd COMMAND --help      # one command

Options and output

Every command accepts:

• --json: print one JSON document instead of text. Errors become {"error": {"code", "message"}} on standard output.
• --window ID: act in that window (IDs come from window list). By default a command acts in the window showing the caller's workspace (HERDR_WORKSPACE_ID, which Herdr sets in every pane). In a Herdr 2 (herdr-core) terminal the caller is that terminal (HC_TERMINAL_ID, which herdr-core sets in every terminal): the command acts in the window and workspace of the tab holding it, and pages it opens and their notes belong to it as they would to a Herdr pane. When no window shows it, as for a session the app does not show, the command exits 5 rather than act on another session's window. Outside both, it acts in the frontmost window. From a herdr-core terminal in a workspace Sheprd keeps for Herdr 2, work notes, checkpoint restore, and host pr act on that workspace's checkout; mutes, scripts, and fan-out, which keep Herdr 1's workspace state, exit 8 there for now, as every work command does from a terminal in no workspace the window keeps. Teleport works from a workspace the app keeps for Herdr 2 on this computer, as its menu does.

Commands

App and windows

open DIR checks the folder where you run it and resolves it to an absolute, canonical path. A path that does not exist exits 5; a file, or a folder in a device namespace (\\.\…, \\?\GLOBALROOT\…, and on Unix /dev, /proc, /sys), exits 1. The app then opens the command palette on its projects and opens the folder there, which focuses the workspace already rooted in it or starts one, on the window's local Herdr, and brings the window forward. A dialog open in the window refuses it (exit 6); the palette shows anything that goes wrong after that, such as the folder disappearing.

When no Sheprd is running and no --window is given, open starts the app, as a plain sheprd would, then asks again every quarter second until the window has connected to the local Herdr and accepts the folder. It waits at most 20 seconds after starting the app, then exits 7. Explorer's Open in Sheprd entry, which both Windows installers add, runs this command through sheprd-launcher.exe, so no console window appears.

The app's own tabs

px0 open reuses one editor tab per workspace. It discovers a local px0 workbench or starts an installed px0; config set px0.url http://127.0.0.1:7777/ selects an existing workbench, and config unset px0.url restores automatic discovery. --json returns the opened tab ID and workspace. Exit 0 means the tab opened; startup errors appear in that tab with Retry. Remote workspaces and builds without embedded pages return exit 8. See px0.

Worktrees and agents

Hosts

A focus asked for on a connected host the window is not showing, such as herdr --machine Homelab agent focus NAME, switches the window to that host when it moves the host to another tab. The daemon reports nothing when the target is already its focused tab, or when the focus only moves between panes of one tab, so a script that must end up on the host runs sheprd host select as well. A focus waits until you stop typing or composing, so keys meant for one host do not reach another, and choosing a host yourself in the meantime cancels it. It leaves the host restored at the next launch as it was. It does not take the window while a dialog is open, or from another window already showing the host. A tab or workspace opening on a background host does not take it either.

Settings and services

Boat's sandbox lifetime uses the existing config commands:

sheprd config set boat.auto_stop never
sheprd config set boat.auto_stop '"7200"'  # seconds, stored as a string
sheprd config get boat.auto_stop --json
sheprd cloud add                         # open Cloud devices, then choose Boat

never is the default: billing continues until the sandbox is stopped in Boat. Numeric deadlines are fixed, even during active SSH work; trials require at most 7200 seconds. The setting applies on create and resume. In Boat settings, Finish setup extends a running sandbox from now or disables its deadline.

Recover creation retries a persisted creation request with its original options and key; forgetting an unresolved request requires confirmation there.

What a new cloud machine installs and runs when it first connects is set the same way, and cloud setup runs it again on one already saved:

sheprd config set cloud.agents '["claude", "opencode"]'
sheprd config set cloud.setup '"git config --global pull.rebase true"'
sheprd config set cloud.coder.agents '[]'   # nothing extra on Coder
sheprd cloud setup herdr-tidy-lark-aa

An agent that needs machines of its own asks for them with cloud create, then follows the batch with cloud wait until each is ready:

sheprd cloud create coder --count 10 --template dev --json
sheprd cloud wait 3 --timeout 600 --json   # again while it exits 4

The window asks once, saying how many machines of which provider, how they are made, and that the provider bills each until it is destroyed. Once confirmed, each machine is made on its own, saved as a device, given Herdr when it lacks it (unless --no-install), and has the [cloud] setup script run on it in a login shell from its home directory, without a terminal (unless --no-setup). Only then is it ready; cloud wait shows each machine's step meanwhile, and its device ID once saved. A failed setup script fails the machine with the end of its output, but the machine stays saved; destroy it like any other. Coder takes --template and --preset by name (without them, the deployment's only template and its default preset); Azure makes a Container Apps sandbox with --sandbox. Boat and Railway make their machines one at a time. Providers are named by key or name: azure, boat, boxd, coder, container, daytona, opensandbox, railway, sprites. The device list keeps at most 64 cloud devices, counting those being made.

cloud exec runs one command on a saved cloud machine, named as for cloud setup, through the same authenticated command the app connects with (coder ssh, a provider's SSH gateway, and so on), so the agent needs no credentials of its own. Everything after -- is the command, word for word; it gets no input. --cwd runs it in a directory, ~/ being the machine's home. --timeout (default 120 seconds, at most 600) counts everything, including waiting for a stopped machine to start; past it the command is stopped. Its stdout comes back on stdout and its stderr on stderr, each cut to its last 64 or 32 KiB and with terminal controls removed; --json gives {"device", "status", "stdout", "stderr", "truncated"}. It exits 0 when the command exited 0, and 1 otherwise. It asks nothing: like the agent's own shell, it acts on the user's machine at once. Git pushes from a machine need credentials there, such as Coder's external auth or a gh auth login in the [cloud] setup script.

sheprd cloud exec herdr-tidy-lark-aa --cwd ~/code -- git clone https://github.com/me/app
sheprd cloud exec herdr-tidy-lark-aa --cwd ~/code/app -- sh -c 'git switch -c fix && make test'

An agent that worked on cloud machines removes them with cloud destroy, naming each by its machine ID, host ID, or label (a label two machines share is refused), or with --batch every machine a batch named. The window asks once, listing each machine and what happens to it: Azure, Boat, boxd, Coder, Container, Daytona, OpenSandbox, and Sprites delete the machine with what goes with it and then forget it here; Railway VMs cannot be deleted from this app, so they are only forgotten and expire on their own. A dialog already open refuses the request (exit 6).

sheprd cloud destroy coder:5d1c… herdr-tidy-lark-aa --json
sheprd cloud wait 3 --timeout 600 --json

cloud wait exits 0 once every machine went as asked, 1 once the batch settled otherwise (a machine failed, with why, or the user said no), and 4 while it is still waiting for the user or running. A batch keeps going if the command or the window that asked goes away; the app keeps the last 32.

Focus-on-hover between split terminal panes is on by default. Disable it with sheprd config set focus_follows_mouse false. The change applies live; config get focus_follows_mouse reads it back.

An unnamed tab shows its number. To show its agent's terminal title instead, run sheprd config set tab_labels.agent_title true.

Remote control

Remote control is turned on in Settings > Remote control, or with config set remote.enabled true; the app then installs the sheprd-remote-control daemon as a user service and keeps it in line with the [remote] settings. While it is off, remote status says so and exits 0; pair, devices, revoke, and restart exit 1. A dialog already open in the window refuses pair and revoke (exit 6). --json gives {"enabled", "running", "status", "error"} for status, where status is the daemon's own report, and {"devices": [...]} for devices.

sheprd remote status --json
sheprd remote revoke d_6f1c

Mods

Mods are folders of sandboxed Luau in <config>/herdr/gpui-mods/ that add status bar items, sidebar sections, and palette commands; saving a file reloads its mod. See Mods. --json gives {"dir", "mods": [...]} for list, each with name, places, commands, drawn, and error, and {"name", "valid", "elements", "places", "hash", "log"} for check.

sheprd mod check ~/.config/herdr/gpui-mods/agents
sheprd mod logs agents --lines 20

Events

events prints what happened in the app: windows opening, closing, and gaining focus; the app's tabs opening and closing; notes kept for a pane; worktree notes changing; host status changes; and cloud batches moving on (cloud_batch, with the batch and its phase: confirming, running, done, or cancelled). Each event has a sequence number; pass back the INSTANCE:SEQ cursor a call prints with --after to get only newer events. A cursor from an earlier run of the app gets every event the new run has kept, so a restart never hides events.

sheprd events --follow --kind tab_closed
sheprd wait tab-closed 12 --timeout 600
sheprd wait window            # also waits for the app to start

What stays in the app

Commands never bypass a confirmation. Restoring a checkpoint, teleporting a worktree, fanning out a prompt, running a worktree script the app has not seen, creating or destroying cloud machines, adding a cloud machine, pairing a phone for remote control, and revoking one open the app's own dialog (archiving a worktree and approving a phone have no command at all), already pointed at your checkout, the machines, or the device named, and the user confirms there. cloud exec asks nothing because it confirms nothing: it is the agent's own work, run on a machine the user saved. Launching the app or requesting a new terminal can start the appropriate local daemon: installed Herdr 1, or a user-installed/bundled herdr-core. Existing Herdr 1 sessions are not migrated, and no command upgrades a personal daemon. update never installs the app; cloud create installs Herdr only on the machines the user confirmed, as creating them in Settings does.

Adding an SSH or local network device has no command: the Add Device dialog runs it. Its setup workspace runs sheprd __device-setup-attach SOCKET, an internal helper that shows the setup the app runs (see the Native Shell README's "Local Network access"); it is not a command to call yourself, and the socket it names is single use.

Herdr 1 scrollback search is not repeated here: herdr pane read covers it. Moving a window and capturing a whole window have no command because the app cannot do them.

Links

sheprd URL, with a herdr-gpui:// link as the only argument, hands the link to the running app, or starts the app and follows it once it is connected. On Windows the installer registers the scheme, so the shell runs this for jump list entries, notification clicks, and links in other apps.

A link is untrusted input, checked by the command and again by the app: only those shapes, each parameter once, bounded lengths, no control characters, and an absolute local path without .. (on Windows a drive path, never a UNC or \\?\ one). A link only ever shows something; it never runs a command. A refused link exits 2, an unknown device or notification 5, as for commands. The request is {"method": "link", "caller", "op": {"url"}}.

The protocol

One JSON request line, one JSON response line, then the socket closes. A request is {"method", "caller", "op"}, where caller carries the pane, workspace, daemon socket, and window, and op is tagged with "op". Browser requests keep their original flat form (browser.open, browser.reload, browser.feedback, notes.send). status reports the protocol version, currently 6. Requests and responses are bounded to 256 KiB, a request that waits says for how long (at most 600 seconds), and the app answers at most a few requests at a time.

Windows

On Windows the same lines travel over a named pipe, \\.\pipe\herdr-gpui-control-SID, where SID is your Windows user's security identifier. When XDG_STATE_HOME is set, a hash of the state directory is appended, so a test or side-by-side install gets a pipe of its own; without it, every shell of yours reaches the same app whatever HOME it has. Pipe names are shared by all users of the machine, so:

• The app creates the pipe owned by you, with a DACL that grants only your SID and inherits nothing, so no other user can connect or add an instance.
• It creates it as the first instance and rejects remote clients (PIPE_REJECT_REMOTE_CLIENTS), so it never joins a pipe someone else made and nothing off this machine can reach it. If another user made the name first, the app does not listen, and logs why.
• sheprd COMMAND opens the pipe at identification level, so the server can learn who called but cannot act as you, and checks that the pipe's owner is you before it sends anything. A pipe someone else owns is refused with exit 1.

A pipe has no receive or send timeout. Reads poll with PeekNamedPipe, as the daemon client does; writes have no deadline, so the app's out buffer holds a whole answer and the connection bound limits what a stalled caller can hold.

Chats on SSH hosts

Native chat views are on by default: turn off ACP chats in Settings > General (acp_chats = false under [features]) to go without them. While it is off, chat panes show their terminal and chat new exits 8.

Set the reading width with sheprd config set chat.max_width 1200, or use 0 for the full available width. Bounded widths range from 320 to 4000 logical pixels; the default is 800. Settings > General offers the same width slider and Full-width chat switch.

A chat on an SSH host shows in the native chat view like a local one. Sheprd runs sheprd-acp connect ID on the host over the same SSH connection it uses for Herdr, and the program there sees an ordinary client on its own socket. Starting a chat there (chat new, or the workspace menu) runs the host's own sheprd-acp, looked for in ~/.herdr/bin, ~/.cargo/bin, ~/.local/bin, and then the remote PATH. Install it on the host with:

cargo install --locked --git https://github.com/sheprd-labs/sheprd sheprd-acp --root ~/.herdr

The workspace menu offers only the agents whose own ACP command is installed on the host, as sheprd-acp agents lists them; an agent npx would have to download first is left out.

Files dropped on a remote chat are copied to the host first, into private temporary files under its ${TMPDIR:-/tmp}, and the copies are attached.

Existing agent rendering

Set chat.render_existing = true, with features.acp_chats left on, to render existing Linux Codex/Claude conversations automatically. The original terminal input remains interactive in the same pane. chat status --json reports input_mode (chat, terminal, or read_only) and session_id; blocked status means the running agent needs input. chat show/hide/toggle still switches the pane presentation, without starting or stopping its agent.