Repo verbs
kraft repo manages the repositories Kraft works in and their worktrees.
kraft repo list
kraft repo connect
kraft repo connect --verify
kraft repo connect --test-command "make check" --setup-command "./configure"
kraft repo disconnect
cd "$(kraft repo path <id>)"
kraft repo path --shell
kraft repo open <id>
kraft repo open <id> --editor cursor
| Command | Effect |
|---|---|
repo list | The connected repos. * marks the one you are in. --all also lists auto-connected repos nobody has touched yet. |
repo connect [PATH] | Connects a repo (safe to repeat). See Connect a repo. |
repo disconnect [PATH] | Forgets the repo. Refused (exit 1) while it has an item that has not ended. See Disconnect a repo. |
repo path [ID] | Prints the item's worktree path. repo cd is an alias. --shell prints a shell function that does the cd for you. |
repo open [ID] | Opens the worktree in an editor. --editor picks code, cursor, zed, obsidian or system (the OS opener). With none named, it is the Default editor in Settings, else KRAFT_EDITOR, else the OS opener. |
What repo list prints
repo list prints a table with the columns NAME, STATE, CHAIN and PATH. The first column holds * for the repo you are in. STATE is enabled or disabled, and CHAIN is the repo's default_chain. A line after the table counts the repos left out, and names --all, when it hides any.
NAME STATE CHAIN PATH
* app enabled default /Users/you/code/app
api enabled quick-task /Users/you/code/api
Connect a repo
kraft repo connect [PATH] connects the repo at PATH, by default the current directory. A relative PATH, . included, is read from where you stand. A repo with no commit yet is refused: commit its files first.
| Flag | What it does |
|---|---|
-y, --yes | Takes the proposal without asking, even in a terminal. |
--test-command CMD | Replaces the proposed test command ("" for none). |
--setup-command CMD | Replaces the proposed setup command ("" for none). |
--no-tests | Declares a repo with no tests, and saves it enabled: its work items pass verification without running a test. Cannot be combined with --test-command. |
--verify | After connecting, runs the setup and test commands once. See Verify a repo's commands. |
--timeout MIN | With --verify, the minutes each command may take. Default 30. |
--on-host | With --verify, runs a sandboxed repo's commands on this machine. |
--json | Prints the answer as JSON. With --verify, its lines are in verify.output. |
With --no-tests, and nothing found to prepare either, setup_command is saved as "" too. Nested and area scopes still run. How connect proposes commands has the rest.
What connect proposes
repo connect proposes a setup command and a test command from the repo's task runner, CI and lockfiles (How connect proposes commands). It prints each with the file it came from, lists what else it found, and says when it found none. In a terminal it asks which candidate to use.
Verify a repo's commands
--verify runs the setup command, then each test command, in a throwaway worktree of the commit a work item starts from. It runs them as a work item would, with a worker's environment.
It exits 1 when a command fails, when one runs past --timeout minutes, or when a command leaves files a work item would commit.
A sandboxed repo's commands run in its sandbox when a work item runs them, so --verify refuses the repo unless you pass --on-host. It prints verify: this repo runs sandboxed, and --verify would run its commands on this machine instead; pass --on-host to do that anyway.
Connecting a repo that is already connected
On a repo already connected, connect probes again for what its entry leaves undecided: a test command where it has none and no test scopes, and a setup command where none is declared. It says what it found and saves only that, after a yes in a terminal. A repo saved disabled for want of a test command is enabled once it has one.
Anything already decided stays as it is: change it in repos.yaml. --verify rehearses what it then declares.
Disconnect a repo
Refused (exit 1) while the repo has an item that has not ended, paused and never-started ones included: complete, cancel or abandon them first (kraft item complete, cancel, or abandon --yes). Ended items are untouched, and no file in the repo is.
Related
- repos.yaml: each repo's settings, such as
setup_command,envandtest_scopes. Past connecting, you edit them in Settings › Repos or inrepos.yaml, not with the CLI. - How connect proposes commands: where the proposed setup and test commands come from.
- Item verbs: file work in a repo you connected.