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
cal, a worktreecal/billing, a session by its name. From the laptop,berthtakes the same commands with the box in front:berth sessions devl,berth exec devl/cal/billing -- …. - JSON. Every listing takes
--json. - State.
BERTH_HOMEoverrides the state directory. Hooks run from~/.berth/hooks.jsonand~/.berth/plugins.
The daemon
| Command | What it does |
|---|---|
berthd serve [--listen ADDR] | Serve paired laptops (default: the tailnet address only, port 7444) |
berthd install [--listen ADDR] [--keep-listen] [--dry-run] | Run serve as a user service (systemd, or launchd on macOS). --keep-listen keeps an installed service's non-tailnet address; --dry-run checks the box and prints what it would do |
berthd uninstall | Remove that service |
berthd pair [--address HOST[:PORT]] [--ttl 10m] | Print a single-use pairing link |
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 |
berthd version | Print this build's version |
berthd session attach NAME | Attach to a session in this terminal |
Locations and worktrees
| Command | What it does |
|---|---|
berthd locations | 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 | The repo's, the box's and the effective config |
berthd services | 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 Berth app |
berthd worktree new LOC/NAME [--branch B] [--base REF] | Create a git worktree and run its setup |
berthd worktree rm LOC/NAME [--force] | Remove a worktree |
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
| Command | What it does |
|---|---|
berthd sessions | List sessions |
berthd agents | Agent CLIs this box can start |
berthd task new LOC/NAME [--agent ID] [--prompt TEXT] [--open split|tab] [--branch B] [--base REF] | A worktree with an agent running in it |
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 [--no-enter] [--wait] [--timeout 30m] | Type a prompt into a session, and wait for its turn |
berthd session wait NAME [--for finished,waiting] [--timeout 30m] | Wait for its agent's turn to end |
berthd exec LOC[/WORKTREE] [--timeout 10m] -- COMMAND... | Run a command there and print its output |
berthd loop SESSION --check CMD [--prompt TEXT] [--max 5] [--turn-timeout 30m] | Prompt, wait, check, and feed failures back |
berthd session kill NAME | Stop a session |
Ports and sharing
| Command | What it does |
|---|---|
berthd ports | What is listening on the box |
berthd stats | Memory, disk, load, and agents running or waiting |
berthd info | The box's name, OS, build, tools and agent presets, as JSON |
berthd share PORT | Make a port public (Cloudflare quick tunnel; needs cloudflared) |
berthd shares | List public shares |
berthd unshare ID | Stop a share |
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.
| Command | What it does |
|---|---|
berthd units | Managed units |
berthd unit add NAME -- COMMAND... | Install and start a unit |
berthd unit get NAME | 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) |
Skills, secrets and events
| Command | What it does |
|---|---|
berthd skills [list|install|uninstall] [SKILL...] [--agent claude|codex|all] [--target user|project] [--location LOC] [--commit] | Teach Claude Code and Codex to use Berth |
berthd secret test REF | Check this box can resolve op://vault/item/field or env://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 emit TYPE [key=value...] [--origin TOOL] | Announce an event, e.g. deploy.finished |
berthd events | Stream the box's events |
Integrations
| Command | What it does |
|---|---|
berthd integrations install claude|cursor|codex|all | Install Berth's skills and agent hooks for a tool |
berthd hook TOOL EVENT [PAYLOAD] | What those hooks run: turns a tool's hook into a Berth event (agent.finished, agent.waiting) |
See agent integrations for what the hooks and skills do, and the berth CLI for the laptop's side.