CLI
The Mac app puts kelpie on your PATH (see Install). It drives the
board already running, so anything the board’s buttons start, a script or an agent can start too.
Every command takes -p, --port for a board that is not on the configured port.
Start a session
Section titled “Start a session”kelpie chat --cwd ~/acme --ask "why is the login test flaky?"kelpie feature saved-cards --cwd ~/acme --ask "Let a returning customer pay with a saved card"kelpie chat and kelpie feature <name> start a session, the same as New on the board, and
print its session id. A chat sends the ask once its box takes text; a feature needs one, to seed
its session with. A claude.ai artifact link in the ask shows as the row’s artifact chip.
| Flag | |
|---|---|
-c, --cwd <path> |
where to start: one of the places New offers (default: here) |
--agent <id> |
the agent, as the board names it (default: the board’s first) |
--ask "..." |
what to ask the session |
--ask-file <path> |
read the ask from a file, or - for stdin |
--machine <name> |
start it on that machine, in its checkout of the --cwd repo, cloned there first if it has none |
--parent <session> |
the coordinator to nest it under |
--no-parent |
nest it under nothing |
Run from inside a Claude Code session, both record that session as the new one’s coordinator. The board draws the new session under its coordinator, and when it finishes a turn kelpie types its last reply into the coordinator, labelled as coming from it, as soon as the coordinator is idle. So a coordinator waiting on its workers, and a worker whose reply went up, are not waiting on you; a worker’s dialog or permission prompt still is, and so is any worker whose coordinator has exited.
Drive a session
Section titled “Drive a session”| Command | |
|---|---|
kelpie say <session> --ask "..." |
send a message, the same as its chat box. Refused while a dialog is on that session’s screen |
kelpie rename <session> "name" |
name a session; leave the name off to clear it |
kelpie notify <title> <body> [--url <link>] |
push a notification to every device that turned them on in the board |
Features
Section titled “Features”Both act on the feature checked out in the current directory, or --cwd.
| Command | |
|---|---|
kelpie restart-dev |
restart its dev server, the same as Restart on the board, and print its new tmux session |
kelpie teardown |
stop its sessions and dev server, run the repo’s teardown and remove the worktree, keeping the branch. Refuses a dirty worktree or a primary checkout, printing why |
A feature’s session is told to run kelpie restart-dev itself when kelpie is on PATH, and to
ask you otherwise. teardown completes even when run from a session it stops, because the board
does the work.
Machines and config
Section titled “Machines and config”| Command | |
|---|---|
kelpie machine add <host> |
set up a box ssh reaches and add it to the config. --name, --token-file. See Machines |
kelpie config |
print the config file’s path and the values in effect, creating the file if it is missing |
kelpie --json |
print the board once, machine readable |