Reference
berthd CLI
Every command of berthd, the daemon on each box, and what agents on the box use.
berthd runs on each box. berthd serve is the daemon; most other commands
talk to it through its local socket, so tools and agents on the box (hooks,
flows, skills) can drive it directly. berthd help prints this list.
- Addressing. A location is
shop, a worktreeshop/checkout, a session by its name. From the laptop,berthtakes the same commands with the box in front:berth sessions devl,berth exec devl/shop/checkout -- …. - JSON. Every listing takes
--json. - State.
BERTH_HOMEoverrides the state directory. Hooks run from~/.berth/hooks.jsonand~/.berth/plugins.
The daemon
- #
berthd serve [--listen ADDR] - Serve paired laptops (default: the tailnet address only, port 7444)
- #
berthd install [--listen ADDR] [--keep-listen] [--no-integrations] [--no-tools] [--dry-run] - Run
serveas a user service (systemd, or launchd on macOS), and install hooks and skills for the agent CLIs found on the box (--no-integrationsskips that). First it installs tmux, and git if missing, when that needs no password (as root, with sudo that needs none, or with Homebrew), and otherwise stops with the command to run (--no-toolsskips this).--keep-listenkeeps an installed service's non-tailnet address;--dry-runchecks the box and prints what it would do - #
berthd uninstall - Remove that service
- #
berthd agents install [--integrations] [--markers] claude|codex|cursor|opencode ... - Install agent CLIs for this user into
~/.local/bin, without sudo, each skipped when it is already there: Claude Code with its native installer, Codex from its pinned GitHub release (sha256 checked), Cursor Agent and OpenCode with their own installers. Adds~/.local/binto the login shell'sPATHif it lacks it.--integrationsthen installs hooks and skills for every agent CLI here;--markersprints a::berth-stepline as each starts and ends. The guided install over SSH, a team setup'sagentsand Add agents… in the app run it - #
berthd agents list [--json] - Which agent CLIs are here, and how to add the others. An agent counts wherever your interactive shell finds it, an npm install under nvm too (agent CLIs you installed yourself), and
agents installskips it - #
berthd pair [--address HOST[:PORT]] [--ttl 10m] [--json] - Print a single-use pairing link;
--jsonprints{ link, address, fingerprint, expires }, which the laptop agent reads to pair with this computer's own berthd (Use this Mac) - #
berthd clients - List paired laptops
- #
berthd revoke <name|fingerprint> - Stop trusting a laptop
- #
berthd id - Print this box's fingerprint
- #
berthd doctor [--json] - Check this box's setup and how to fix it. It looks for the agent CLIs afresh, and names each one's version, path and how it was installed
- #
berthd version - Print this build's version
- #
berthd session attach NAME - Attach to a session in this terminal
- #
berthd mcp - A stdio MCP server of Shipyard's tools for agents on this box, talking to its socket;
integrations installadds it to Claude Code, Codex, Gemini CLI and oh-my-pi (runs) - #
berthd headless --agent A --out FILE.jsonl --prompt-file FILE [--read-only] [--add-dir D] - One non-interactive agent turn, as runs start in tmux for judges and reviewers
~/.berth/runs.json on the box sets max_concurrent_runs (10),
max_concurrent_agents (6) and triggers_listen ("tailnet" serves signed
webhook triggers on the tailnet
address, port 7482). Runs that were going when berthd stopped resume when it
starts.
Locations and worktrees
- #
berthd locations [--json] - Locations and their worktrees
- #
berthd location add NAME PATH - Register a repo or directory
- #
berthd location rm NAME - Forget a location (files are untouched)
- #
berthd location scripts NAME [--setup CMD] [--archive CMD] [--clear] - Worktree setup and archive scripts (default: the repo's
.berth/config.json) - #
berthd location config NAME [--json] [--trust HASH|--untrust] - The repo's, the box's and the effective config; trust the repo's to run it
- #
berthd services [--json] - Which worktree each running server belongs to
- #
berthd service list|start|stop|restart|log LOC/WORKTREE [SERVICE] - A worktree's services from the repo's config
- #
berthd preview [LOC/WORKTREE] [PORT] [--path /x] - Open a worktree's page in the Shipyard app
- #
berthd worktree new LOC/NAME [--branch B] [--base REF] [--pr N [--ref REF]] [--parent NAME] [--no-setup] - Create a git worktree and run its setup;
--prchecks out that pull request (pass its head branch as--branch; a fork's head comes from--ref, by defaultpull/N/head);--parentnests it under another worktree of the location;--no-setupskips setup and autostart services, and the worktree showssetup_pendinginlocations --json - #
berthd worktree setup LOC/NAME [--wait] - Run the location's setup script and autostart services in a worktree, for one made with
--no-setup.--waitblocks until setup finishes and exits non-zero if it fails - #
berthd worktree rm LOC/NAME [--force] - Remove a worktree
- #
berthd worktree rename LOC/NAME [TITLE] - Give a worktree a display name (no TITLE clears it)
- #
berthd reviews [--idle-days N] [--json] - The pull requests opened for review here;
--idle-dayssets how long one may sit unused before it is cleaned up (0: never; default 7) - #
berthd review-button [LOC/WT] [--as EMAIL] [--path /x] [--clear] [--json] - The Review in Shipyard button on the worktree's PR: whether the project has it on, and whether the PR has it.
--as(one of the project's login users) and--pathset what it opens with; berthd puts the new link in place on its next look.--cleardrops both - #
berthd login users [LOC[/WT]] [--json] - The users the project's worktrees can be logged in as, from its trusted login config: what a review link's
asmay name
berthd preview with no arguments uses the worktree it runs in (from
$BERTH_WORKTREE_PATH or the current directory) and its $BERTH_PORT. It
asks the app to open the page as a browser tab beside the agent; the
berth-preview skill teaches agents to use it.
Agent sessions
- #
berthd sessions [--json] - List sessions
- #
berthd agents [--json] - Agent CLIs this box can start
- #
berthd task new LOC/NAME [--agent ID] [--prompt TEXT] [--open split|tab] [--branch B] [--base REF] [--no-notify] [-- COMMAND...] - A worktree with an agent (or a command) running in it; from an agent's session, that agent hears back when its first turn ends, and the new worktree nests under that agent's
- #
berthd session new LOC[/WORKTREE] [--name N] [--agent ID [--prompt TEXT]] [--open split|tab] [-- COMMAND...] - Start an agent or a command (default: a shell) there
- #
berthd session screen NAME [--history N] - Print what the session shows
- #
berthd session send NAME TEXT [--when now|idle] [--force] [--idem KEY] [--no-enter] [--wait [--timeout 30m]] [--no-notify] - Type a prompt into a session (or hold it until the agent is idle), and wait for its turn; without
--wait, an agent sending it hears back when the turn ends - #
berthd session wait NAME [--turn ID] [--for finished,waiting] [--timeout 30m] - Wait for a turn (from
session send), or its agent's current one, to end - #
berthd session turns NAME [--limit 10] [--json] - List a session's turns: who prompted, how it ended, how long it took
- #
berthd exec LOC[/WORKTREE] [--timeout 10m] [--detach [--no-notify]] -- COMMAND... - Run a command there and print its output;
--detachruns it as a run, which reports back to an agent that started it - #
berthd loop SESSION --check CMD [--prompt TEXT] [--max 5] [--turn-timeout 30m] [--cancel-on-exit] [--detach] - Prompt, wait, check, and feed failures back, as a durable run
- #
berthd runs,berthd run start|get|logs|approve|reject|cancel|templates … - Runs, as
berth runwithout the box - #
berthd browser open|snapshot|click|fill|press|select|hover|check|wait|shot|console|network|eval|status|close [LOC/WT] … [--tab NAME] - The worktree's agent browser; inside a session, its own worktree.
--tab(or$BERTH_BROWSER_TAB) gives an agent a tab of its own - #
berthd browser tabs [LOC/WT] - The browser's tabs, what each shows, and which is busy
- #
berthd browser open [LOC/WT] --as EMAIL [--path /x] - Log the agent browser in as one of the project's dev users (the worktree's login script runs, its cookies go in for the worktree's address), then open the page:
--path, else where the login says - #
berthd browser list,berthd browser allow ORIGIN,berthd browser install - Browsers running; allow a public origin; download a Chromium
- #
berthd browser reap [--dry-run] [--json] - Close the agent-browser sessions (Vercel's CLI) that Shipyard sessions which have ended left running;
--dry-runonly lists them.berthd doctorreports them too - #
berthd shots compare [LOC/WT] [--pages / /login] [--sizes 375 768 1280] [--base main|turn-start|accepted|NAME] [--mask SEL]... [--color-scheme light|dark|both] [--as EMAIL] [--title T] [--note N] [--new] - Screenshot the worktree's pages and the base's, diff them, and keep a visual diff; a re-run is its next version. Prints what changed, in about 450 tokens.
--aslogs both sides in as a dev user, each with its own login - #
berthd shots baseline [LOC/WT] [--name turn-start] [--pages …] [--sizes …] [--color-scheme …] - Save the worktree's pages as a baseline to compare with later
- #
berthd shots accept [LOC/WT] ID - Keep a visual diff's after-shots as the worktree's
acceptedbaseline (the app's Accept as baseline) - #
berthd flow secret FLOW [--scope S] - Make a webhook flow's signing secret
- #
berthd session rename NAME [TITLE] - Name a session's work; no TITLE clears it
- #
berthd session kill NAME - Stop a session
Ports and sharing
- #
berthd ports [--json] - What is listening on the box
- #
berthd stats [--json] - Memory, disk, load, and agents running or waiting
- #
berthd ps [--json] - Every browser on the box with who started it, its CPU, memory and age, and what each session's processes use
- #
berthd ps stop ID - Stop a browser from that list (an ID like
b-4182-…), or end a session (s-NAME) and everything it started - #
berthd info - The box's name, OS, build, tools and agent presets, as JSON
Units
Long-running programs berthd runs under the box's service manager, so they survive reboots and restart on failure. Their output goes to a log berthd owns, not the journal.
- #
berthd units [--json] - Managed units
- #
berthd unit add NAME -- COMMAND... - Install and start a unit
- #
berthd unit get NAME [--json] - Its state and where its log is
- #
berthd unit log NAME - What it has written, for one that will not stay up
- #
berthd unit restart NAME - Start it again
- #
berthd unit rm NAME - Stop and remove it (its log stays)
Plugin helpers
A plugin can bring a helper: a
program that runs on the box beside your dev servers, such as Leadline's
berth-leadline, which records their queries, traces and logs, or
berth-database, which browses and edits a worktree's development database.
You turn one
on for a box from the plugin in the app; your laptop downloads it, checks it
against the checksum in the plugin's manifest and uploads it. These commands
are the box's own view of what was put there.
- #
berthd helpers [--json] - The helpers of plugins on this box: the plugin, the program and its version, whether it runs, its PID, and why not when it doesn't
- #
berthd helper log PLUGIN - What a plugin's helper has printed, and when berthd started and stopped it
- #
berthd helper rm PLUGIN [--purge] - Stop and remove a plugin's helper. Its data stays for the next time;
--purgeremoves that too
How berthd runs a helper:
- As you, in its own folder. A helper is the box user's own program,
with what that user can reach. Its files are in
<state>/box/helpers/<plugin>/: the program inbin/<version>/, its data indata/, its log beside them (files). The program that runs is the one whose SHA-256 the laptop sent: berthd checks the upload against it before keeping a byte, and checks the file again each time it starts it. Its arguments are the manifest's and nothing else, with{dir}filled in with its data folder, and it gets a small environment, not berthd's. - For as long as berthd runs. berthd starts every installed helper when
it starts, before it serves anything, and stops them when it stops: asked
first (
SIGTERM), killed after five seconds, with whatever they started. A helper that exits is started again: after a second, then two, four, up to a minute. After three failures in a row it is shown asfailed, with why, and berthd keeps trying. One left running by a berthd that was killed is ended before the next berthd starts its own. - Reached on loopback only. A helper says where it listens in a file in
its data folder, and berthd relays to that address only if it is on this
machine. The app reaches a helper's API through berthd
(
helpers/{plugin}/api/…); nothing of it is open to the network. - With the helper's token, if it has one. A helper may write a
tokenin that file beside its address. berthd then sends it back asAuthorization: Bearer <token>with every request it makes of that helper: what it relays for the app, and its own calls before a service starts. The file is in a folder only you can read, so the helper can refuse everyone but berthd. WhateverAuthorizationthe app sent is taken off a relayed request first, for every helper, and the token is in no log and no answer of berthd's. - Never in the way of a service. Before berthd starts a worktree's service it asks each running helper that wants to know, and waits at most two seconds for what it adds to the service's environment. A helper that is down, slow or wrong changes nothing. With several helpers on, each is shown the service's variables as the project has them, not as another helper changed them.
- Shown the worktree's
.envtoo. A variable a helper's manifest names that Shipyard's environment for the service does not have is taken from the worktree's dotenv files (.env,.env.development,.env.local,.env.development.local, a later one winning) and shown to the helper as the service's own; the project's own setting always wins, and a variable that names a secret is never read. What the helper answers for it goes into the service's environment like any other, so a recording proxy ends up in front of a database whose address is only in.env. berthd reads those four names in the worktree's folder and nothing else, never through a link out of the worktree, at most 256 KB each, and only when a helper withattachis running that names a variable the project has not already set. A read that fails, or takes longer than the two seconds a helper has, changes nothing. - Asked to look, by the app.
POST helpers/{plugin}/attach-env(app API) has berthd read the same files for one helper when nothing is being started, and tell it with.envwhere a service's name would be: the Database tab does this when it opens. Nothing the helper answers is set anywhere, the worktree is not added toattached.json, and the answer names files and variables, never a value. It is a paired laptop's to ask, not the box's own socket's. The same route takes the variables themselves in place of reading the files (an address a person pasted in the Database tab): berthd hands them to the helper with.manualas the name, and logs, announces, answers and keeps none of it. - Told when a worktree goes. After a worktree is removed (with
berthd worktree rm, from the app, by a review's clean-up, after an archive script, or bygit worktree removeitself), berthd tells each running helper whose manifest names adetachpath, and does the same for every worktree of a location that is removed. It happens in the background with two seconds to answer, so a helper that is down or slow never holds up or fails a removal, and berthd forgets the worktree in its own list of attached services either way. - Removed with its plugin. Turning the plugin off on the laptop, or
removing it there, has the laptop remove its helper from this box, as
berthd helper rmdoes (with--purgewhen the plugin was removed): see a helper does not outlive its plugin. berthd keeps its list of the services still running with what a helper told them (attached.json) after the helper is gone, its data too: turned on and off again, the helper's removal names them again, until they are started again without it.
A before:helper.install gate on the box can
refuse a helper, and a before:helper.attach gate a look in a worktree's
.env files or an address given by hand; helper.installed and helper.removed are announced.
Skills, secrets and events
- #
berthd skills [list|install|uninstall] [SKILL...] [--agent claude|codex|all] [--target user|project] [--location LOC] [--commit] - Teach Claude Code and Codex to use Shipyard
- #
berthd secret test REF - Check this box can resolve
op://vault/item/fieldorenv://NAME(prints the value's length, never the value) - #
berthd secret exec [--socket PATH] -- PROGRAM [ARGS...] - Used by sessions and services: resolves secret references, then runs the program. See secrets.
- #
berthd secret signin [--check] - Signs the box's
opin to 1Password in this terminal (op signin) and keeps its session for berthd'sop://reads; a team setup's 1Password step runs it.--checkasks nothing and exits 0 when berthd can read 1Password now. See secrets. - #
berthd emit TYPE [key=value...] [--origin TOOL] - Announce an event, e.g.
deploy.finished - #
berthd events [--json] - Stream the box's events
Integrations
- #
berthd integrations [status] - Where Shipyard's hooks and skills are for each agent CLI on this box, per Claude Code and Codex account (
Claude Code: hooks and 7 skills in ~/.claude, ~/.berth/accounts/claude/personal), and the command that adds them where they're missing - #
berthd integrations install claude|cursor|codex|gemini|opencode|omp|all|present - Install Shipyard's skills and agent hooks for a tool (
present: every agent CLI on this box, quietly skipping the rest), andberthd mcpas an MCP server for Claude Code, Codex, Gemini CLI and oh-my-pi. Claude Code and Codex get them in every account folder - #
berthd hook TOOL EVENT [PAYLOAD] - What those hooks run: turns a tool's hook into a Shipyard event (
agent.finished,agent.waiting), naming the session from$BERTH_SESSION. While berthd is down it keeps the event in~/.berth/box/spool/, published when berthd starts
See agent integrations for what the hooks and skills do, and the berth CLI for the laptop's side.