Skip to content
New: answer your agents from your phoneLearn more

The ket engine, from your shell.

The CLI talks to the same engine as the native app, so interactive and scripted workflows share the same projects and worktrees.

Work with projects and worktrees

$ ket project add .
$ ket worktree add fix-flaky-poll
fix-flaky-poll-3f2a9c41d0be  ~/.local/share/ket/worktrees/…

Create a task branch and its isolated working directory without leaving the terminal. ket prints the new worktree's id; commands that take a worktree use that id, or the worktree you're in when you leave it out. ket worktree add also provisions the worktree, bringing dependencies and .env files across from your primary checkout.

Start work and inspect changes

$ ket run claude --on fix-flaky-poll-3f2a9c41d0be --prompt "fix the flaky test"
$ ket ps
$ ket diff fix-flaky-poll-3f2a9c41d0be --stat
$ ket events --follow

Start an agent on a worktree, list sessions across projects, review a worktree's changed-file summary and follow engine events as they happen.

Let an agent drive ket

Any agent that can run shell commands can use the CLI, and agents you open in ket have it already. Tell yours what you want:

Start the next backlog item in a new worktree.

The agent reads the backlog with ket backlog list and starts the first note with ket backlog start. The ket window makes the worktree and opens an agent there on the note, in a tab like any other. ket tells Claude Code and Codex sessions about the command as they start; point another agent at ket --help.

Commands

CommandWhat it does
ket project add [path]Register the repository containing a path, or the current directory.
ket project listList projects, most recently used first.
ket worktree add <branch>Create a worktree on a new branch and provision it. --base picks the starting ref, --no-provision skips setup.
ket worktree listList worktrees in every project, or one with --project.
ket worktree status [id]Show changed files and how far the branch has diverged from its base.
ket worktree provision [id]Provision a worktree, such as one created in the app.
ket worktree rm <id>Remove a worktree. --delete-branch removes its branch too.
ket run [agent] --on <id> --prompt <text>Start an agent in a worktree. Pass - as the prompt to read it from stdin.
ket start <prompt>Start work in a new worktree, with its agent in a tab in the ket window. Needs ket open.
ket psList agent sessions across every project.
ket diff [id] [--stat]Print what a worktree changed against its base, uncommitted work included.
ket merge <id>Commit a worktree's work and merge it into its base.
ket backlog add <title>Add a note to a project's backlog.
ket backlog listList a project's backlog notes, most pressing first.
ket backlog start <note>Start a note in a new worktree, as the backlog's Start does, and mark it done. Needs ket open.
ket backlog done <note>Mark a backlog note done.
ket events --followStream ket's events as JSON lines.
ket filter [--keep] -- <command>Run a command and print its output trimmed the way Economy's filter trims it for an agent, exiting with the command's status. --keep saves the full output for ket recall.
ket recall <id>Print the full output of a command the filter trimmed, by the id in its trailer.
ket doctorCheck that everything ket depends on is present.
ket commandsList every command ket can perform, the same ones the command palette offers.

Every command has --help. Commands that delete work, such as ket worktree rm, always take the worktree's id rather than guessing it from the current directory.

Use one model for scripts and the app

A project or worktree created from the CLI appears in the app because both surfaces drive the same local engine. That makes the command useful for personal shortcuts, repeatable setup and automation around existing developer tools.

For the concepts behind the commands, see Projects, Worktrees and Git, diffs and merging in the docs.