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, or no input box, is on that session’s screen |
kelpie rename <session> "name" |
name a session; leave the name off to clear it |
kelpie close <session> |
exit a session, the same as Close on the board. Resuming brings the conversation back |
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 close |
stop its sessions and dev server, run the repo’s teardown and remove the worktree, keeping the branch. Refuses a dirty worktree, printing why. teardown still works as another name for it |
A feature’s session is told to read the agent skill below, which says to run kelpie restart-dev
itself and to ask you if that fails. close completes even when run from a session it stops, because the board
does the work.
Agents
Section titled “Agents”| Command | |
|---|---|
kelpie skill |
print the agent skill that teaches a coding agent these commands, matching the build you have |
kelpie skill --install |
write it to ~/.claude/skills/kelpie (Cursor and OpenCode read it there too), and to Codex’s skills when Codex is installed. Run it again after an update |
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, signing it into Claude through a browser tab the first time. --gce creates the VM on Google Compute Engine first; --name, --token-file. See Machines |
kelpie machine remove <name> |
take a machine off the board. --gce also deletes the VM and the ssh Host that machine add --gce made |
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 |