Owlshift Owlshift

Command reference

This page lists every owlshift command with its arguments, options and help text, as owlshift help do prints them for do. It is generated from the binary, and a test fails when it differs from the commands. To update it after changing a command, run:

OWLSHIFT_UPDATE_CLI_REFERENCE=1 cargo nextest run -p owlshift-cli --locked cli_reference

Every command also takes --help, and owlshift --version prints the version. Commands and options meant for Owlshift's own processes are left out. In a usage line, <NAME> is required and [NAME] optional; the help text says which options go together or exclude each other.

Works a team's backlog with coding agents, and asks a human on the ticket when a decision is theirs.

Commands

owlshift doctor

Check whether this machine is ready: git, the harness CLIs and their logins, the agent runs' isolation and Claude Code token, the configuration files. Says why each problem matters and how to fix it.

owlshift doctor [OPTIONS]

Arguments and options:

owlshift config

Read the configuration.

owlshift config <COMMAND>

owlshift config show

Print the effective configuration and the file each value comes from.

owlshift config show

owlshift init

Write a commented owlshift.toml for this repository, then store its tracker and forge secrets and the agent runs' Claude Code token owlshift do needs in the system keychain.

owlshift init [OPTIONS]

Arguments and options:

owlshift do

Run one ticket to a verified pull request, in the foreground. Its questions are posted on the ticket.

owlshift do <TICKET>

Arguments and options:

owlshift continue

Continue a ticket once its decider has answered on it: once their reply has been left unedited for 10 minutes, or ends with go, check the answers, then ask again what is missing or run on to a verified pull request. Restarts a parked ticket.

owlshift continue [OPTIONS] <TICKET>

Arguments and options:

owlshift watch

Watch this project's tickets whose questions wait, in the foreground, and continue each one as owlshift continue would once its decider's reply counts; checked every minute. A first Ctrl-C ends it once the steps under way finish, a second (or SIGTERM) stops them and checks their runs, a third (or SIGQUIT) stops everything at once. It also resumes a ticket at Intake, Design, Design review, Build or Verify that an answered round (round > 0) left shown working or needing input, a refusal after the answer check included. A parked ticket, or one left at Build before any question round, still needs owlshift continue; owlshift continue --to-watch restarts a park and leaves it to watch.

owlshift watch [OPTIONS]

Arguments and options:

owlshift forget

Start over what Owlshift keeps on a ticket between commands, when it has no room left or cannot be read: its asks and decisions go, their comments staying on the ticket; its round count and the refusals its next runs are told stay. Refused while another command works the project.

owlshift forget <TICKET>

Arguments and options:

owlshift cancel

Cancel a ticket's work: its step under way stops within 5 seconds, its runs stopped and checked, and the project's watch parks it, with a PARKED comment saying who canceled and why. owlshift continue restarts it from where it was stopped. Refused for a ticket parked already, one whose delivery ended, and one waiting in the ready column: removing its admission keeps it there.

owlshift cancel [OPTIONS] <TICKET>

Arguments and options:

owlshift release

Release a ticket's claim on the git remote, so that another runner can take it: on the machine that holds it at any time, its step under way stopped first; from another machine when the claim's operator is yours, or once it expired, by a person the project's [people] lists. Any other live claim is refused, with its holder and its expiry. A RELEASED comment on the ticket says who released it and how to have it worked again; its stage is left as it is.

owlshift release <TICKET>

Arguments and options:

owlshift gate

Run the project's gate once, as a Build's gate runs it: in a fresh worktree of origin's default branch, confined, with the variables the project declares and you allow. Prints each command's last lines, status and time, then removes the worktree. The gate is the project file's at that commit, or yours when it has none. Refused while another command works the project.

owlshift gate [OPTIONS]

Arguments and options:

owlshift unquarantine

Clear this project's quarantine: the marker a run whose isolation check did not pass leaves, which makes every command refuse the project. Shows what the marker says, then clears it once you type the project's name (owner/repo) at a terminal. The dedicated checkout and the worktrees stay as they are. Refused while another command works the project.

owlshift unquarantine

owlshift why

Say why this project's admitted tickets are not running: blockers, the ticket or pull request that holds what they would touch, the caps, a harness at its usage limit, the quarantine, and the people's tickets left out for want of zones; then the machine's run slots and the harnesses limited. With a ticket, its reasons over time. Read only, takes no lock, and works while owlshift watch runs.

owlshift why [TICKET]

Arguments and options:

owlshift start

Serve this project with the background service, and start the service for this login session when it does not run: it keeps one owlshift watch --drain per served project alive, without a terminal, each on the project file of its default branch. Its output goes to service/daemon.log in the data directory.

owlshift start [OPTIONS]

Arguments and options:

owlshift stop

Stop the background service: each watch ends once its steps under way finish, then the service exits. With --forget, stop serving this project only.

owlshift stop [OPTIONS]

Arguments and options:

owlshift pause

Pause every project of this machine, or only OWNER/REPO: from each watch's next pass, no ticket is dispatched and no step starts, nor a merge on green; the steps under way finish, and answers, pull requests and stages are still read. The service keeps running.

owlshift pause [OPTIONS] [OWNER/REPO]

Arguments and options:

owlshift resume

Lift the pause of every project of this machine, or of OWNER/REPO only: each watch goes on at its next pass.

owlshift resume [OWNER/REPO]

Arguments and options:

owlshift status

Say what the background service serves and does: the daemon, each served project's watch (running, restarting and why, paused and why, draining) and the file it runs on, the tickets waiting for a person, the steps under way, each harness's usage and reset, the latest digest. Read only, takes no lock.

owlshift status [OPTIONS] [OWNER/REPO]

Arguments and options:

owlshift ui

Open the local web UI in your browser, logged in: checks that the daemon's web UI listens on 127.0.0.1 at [ui] port (18466 unless the personal file sets it), then opens a link with a one-time code, valid for a minute.

owlshift ui [OPTIONS]

Arguments and options:

owlshift uninstall

Remove what Owlshift installed on this machine, as its install manifest lists it: the service at login and the keychain entries owlshift init stored. A daemon that runs is stopped first, its runs checked. Repositories, tickets and branches are never touched.

owlshift uninstall [OPTIONS]

Arguments and options:

owlshift daemon

The background service itself, in the foreground: owlshift start runs it. One per data directory; a second exits at once. Ctrl-C ends it once its watches drained, a second (or SIGTERM) stops their steps checking their runs, a third stops everything now.

owlshift daemon

owlshift self-update

Update an install made by hand, by install.sh or from an archive, to the latest release: its signature and checksum verified with the key built into this binary, then the binary replaced at its own path. An install by Homebrew or cargo is refused, with the command that updates it; an older release is never installed.

owlshift self-update [OPTIONS]

Arguments and options:

owlshift logs

Print the events owlshift do, continue, watch and forget recorded, oldest first.

owlshift logs [OPTIONS] [TICKET]

Arguments and options: