CLI Reference
Every Shep command, grouped by area. This page covers Shep v1.252. Run shep <command> --help for the authoritative flag list of the version you have installed.
IDs. Features, agent runs and repositories have UUID IDs. Wherever a command takes <id>, you can pass the full ID or any unique prefix of it (for example 1a2b).
Global flags work on every command:
| Flag | Effect |
|---|---|
--verbose | More output. |
--debug | Debug output. |
--log-level <level> | debug, info, warn, error or silent. |
-v, --version | Print the version. |
-h, --help | Help for any command. |
Daemon and web UI
| Command | What it does | Key flags |
|---|---|---|
shep | Start Shep in the background (if it isn’t running) and open the web UI. Same as shep start. | — |
shep start | Start the background daemon. Default port 4050; if it’s busy, the next free port. | -p, --port <n> |
shep stop | Stop the daemon. | --force |
shep restart | Restart the daemon (starts it if it isn’t running). | -p, --port <n>, --force |
shep status | Is the daemon running, on which port. | --logs [lines] (default 50), -f, --follow |
shep ui | Run the web server in the foreground in this terminal (not as a daemon). Stop with Ctrl+C. | -p, --port <n>, --no-open |
shep version | Print version information. | — |
shep upgrade | Upgrade Shep to the latest version. | --force |
shep logs prune | Report — and with --yes, delete — old agent worker logs. | --older-than <7d>, --yes, --json |
See Web Dashboard.
Features
shep feat creates features and moves them through their lifecycle.
shep feat new "<description>"
shep feat new "add a /health endpoint that returns uptime and version" --push --pr
shep feat new "redesign the payment system" --no-fast --pr
shep feat new "fix navbar logo alignment" --allow-merge --pr
shep feat new "add sso" --remote myorg/webapp --pr| Flag | Effect |
|---|---|
-r, --repo <path> | Run in another local repo (default: current folder). |
--remote <url> | GitHub URL or owner/repo: clone it (forking if you can’t push), then create the feature there. Not with --repo. |
--push | Push the branch when implementation completes. |
--pr / --no-pr | Open (or don’t open) a draft PR. --pr implies --push. |
--fast / --no-fast | Implement straight from the prompt (default), or run the spec-driven phases. |
--explore | Start an exploration (prototype) session instead. |
--allow-prd | Auto-approve the requirements gate. |
--allow-plan | Auto-approve the plan gate. |
--allow-merge | Auto-approve the merge gate: Shep merges once CI is green. |
--allow-all | Auto-approve all three gates. Does not turn on push or PR. |
--model <id> | Model for this feature (default: your default model). |
--effort <level> | Reasoning effort: low, medium, high, xhigh, max. Only Claude Code uses it. |
--attach <path> | Attach a file. Repeatable. |
--parent <id> | Create a child feature that starts once its parent’s work lands. |
--pending | Create the feature without starting the agent. |
--no-rebase | Skip syncing main from the remote before creating the branch. |
--inject-skills / --no-inject-skills | Inject curated skills into the worktree, or skip it for this run. |
--explore-harness [--explore-k <n>] | Self-learning: run the implement step in Explore mode. Needs the selfLearning flag; costs about 4× the implement step at k=1. |
Watching and steering
| Command | What it does | Key flags |
|---|---|---|
shep feat ls | List features. | -r, --repo <path>, --include-deleted, --show-archived |
shep feat show <id> | Full detail: phase, settings, PR, worktree, coordination. | — |
shep feat status <id> | What the agent is doing (working, blocked, waiting, done, failed) and why. | --json |
shep feat wait <id> | Block until the agent needs someone or stops. Exits 0 reached, 1 not found, 2 timeout, 3 ambiguous, 130 interrupted. | --until <states>, --timeout <s>, --json |
shep feat logs <id> | The agent’s log. | -f, --follow, -n, --lines <n> |
shep feat review [id] | Interactive terminal review of a feature waiting for approval. | — |
shep feat approve [id] | Approve the gate it’s waiting at. | — |
shep feat reject [id] | Reject with feedback; the agent re-runs that phase. | --reason <text> (required) |
shep feat start <id> | Start a pending feature. | --force (ignore the parallel limit) |
shep feat resume <id> | Resume a stopped or failed run. | --force |
For review, approve and reject, leaving out the ID picks the one feature in the current repo that is waiting.
Managing
| Command | What it does | Key flags |
|---|---|---|
shep feat del <id> | Delete the feature: removes the worktree, local and remote branch, and closes its PR (asks first). | -f, --force, --no-cleanup, --no-close-pr |
shep feat archive <id> | Hide it from the canvas. | -f |
shep feat unarchive <id> | Bring it back. | — |
shep feat adopt <branch> | Track an existing branch as a feature. | -r, --repo <path> |
shep feat feedback <id> "<text>" | Iterate on an exploration prototype. | — |
shep feat promote <id> | Turn an exploration into a regular feature. | --fast |
shep feat comments <id> | Show the PR’s review comments and what Shep did about them. | --no-refresh |
shep feat address-comments <id> [comment-ids…] | Have the agent address review comments, push, and reply on each. | --no-refresh |
See PR review comments.
Checkpoints
| Command | What it does | Key flags |
|---|---|---|
shep feat checkpoints <id> | List the checkpoint taken after each step. | — |
shep feat diff <id> | Show what a step changed, or compare two. Steps are a number, a name or a label (3, implement, 0003-implement). | --to <step> (required), --from <step>, --stat |
shep feat restore <id> <step> | Roll the worktree back to a checkpoint. | -f, --force |
See Git checkpoints.
Fleet
| Command | What it does | Key flags |
|---|---|---|
shep fleet status | Running, queued, waiting on you and failed counts; queue and circuit-breaker state. | --repo <path> |
shep fleet triage | Everything across the fleet that needs a human decision. | --repo <path> |
shep fleet approve | Batch-approve features waiting at gates. One of the flags is required. | --all, --gate prd/plan/merge, --low-risk |
shep fleet retry --failed | Restart the agents behind crashed, failed or stopped runs. | --repo <path> |
shep fleet pause | Pause the admission queue. Running agents continue; new work waits. | --reason <text> |
shep fleet resume | Resume the queue and admit whatever now has room. | — |
--low-risk approves only what your guardrail rules prove safe — with no rules, nothing. Set the parallel limit with shep settings workflow --max-parallel <n>. See Fleet management.
Terminal console and processes
| Command | What it does | Key flags |
|---|---|---|
shep tui | Live terminal console of every feature: approve, reject, stop, resume, follow logs, open shells. Needs an interactive terminal. | --repo <path>, --all, --no-notify, --status [plain/tmux] |
shep ps | The daemon and every agent worker, with feature, agent, status, uptime, CPU and memory. | --all, --json, -w, --watch |
shep ps stop <id> | Stop an agent run. Takes a run ID, a feature ID, or a prefix of either. | --force |
See Terminal console.
Apps and dev servers
| Command | What it does | Key flags |
|---|---|---|
shep app new "<description>" | Start a new app under ~/.shep/projects/. Its first feature is spec-driven by default. | --starter blank/vite-shadcn, --fast, --agent <type>, --model <id> |
shep app ls / show <id> / del <id> | List, inspect or delete apps. | del -f |
shep app git create-remote <id> | Create a GitHub repo for an app. | — |
shep app cloud-providers ls / connect <provider> / github-login | Manage cloud deployment providers. | --token, --json |
shep app deploy start <id> / status <id> | Deploy an app and check the deployment. | --provider, --json |
shep dev start / stop / status / logs | Run and inspect the local dev server of an app, feature or repo (default: current folder). | -a, --app, -f, --feature, -r, --repo; logs -F -n; status --json |
shep dev plan show / set / clear | Inspect, pin or clear how the dev server is started. | set -c <command> --cwd --port --setup … |
shep dev approve | Approve the commands in the repo’s .shep/dev.json. | --fingerprint <hash> |
See Start an app and Dev servers.
Agents and sessions
| Command | What it does | Key flags |
|---|---|---|
shep agent ls / show <id> | List agent runs, or show one. | — |
shep agent logs <id> | An agent run’s log. | -f, -n <n> |
shep agent stop <id> | Stop a running agent. | --force |
shep agent approve <id> | Approve a paused agent run and resume it. | — |
shep agent reject <id> | Reject a paused agent run and cancel it. | -r, --reason <text> |
shep agent delete <id> | Delete an agent run record. | --force |
shep agent questions ls / answer / cancel | Questions agents asked you. | --app <id> (required), --answer <text> |
shep session ls / show <id> | Claude Code, Cursor or Gemini CLI sessions on this machine. | --claude-code, --cursor-cli, --gemini-cli, -n, --flat, -m |
shep run <agent-name> | Run a Shep agent workflow directly (analyze-repository, feature-agent). | -p, --prompt, -r, --repo, -s, --stream |
shep usage | Agent duration, tokens, cost and failures over a window. | --since <7d>, --by phase/agent/feature/model, --json |
shep agent questions belongs to the collaboration flag, which is on by default. See Agents, Models & effort and Decisions.
Repositories
| Command | What it does | Key flags |
|---|---|---|
shep repo ls | Tracked repos: ID, name, feature count, path. | — |
shep repo show <id> | Details of one repo. | — |
shep repo add | Clone a GitHub repo and track it. | --url <url or owner/repo>, --dest <path> |
shep repo import <dir> | Track many local folders at once. | --all, --git-only |
shep repo init-remote [name] | Create a GitHub repo from the current local repo (private by default). | --public, --org <name> |
See Multi-Repo.
Settings
| Command | What it does | Key flags |
|---|---|---|
shep settings | Interactive wizard: agent, IDE, workflow defaults. | — |
shep settings show | Print current settings. | -o table/json/yaml |
shep settings agent | Default agent and auth. --auth is required with --agent (except dev). | --agent <type>, --auth session/token, --token <key> |
shep settings model | Default model (interactive). | — |
shep settings effort [level] | Default reasoning effort. | --clear |
shep settings adaptive-models | Per-task model tiers. | --enable, --disable, --high, --medium, --low <model>, --clear |
shep settings workflow | Default gates, push/PR and parallel limit. | --allow-prd, --allow-plan, --allow-merge, --allow-all, --push/--no-push, --pr/--no-pr, --max-parallel <n> |
shep settings worktree | Custom worktree commands. | --create-command, --post-create-command, --timeout <ms>, --clear |
shep settings ide | Default editor. | --editor <name> |
shep settings language | Display language. | — |
shep settings flags | List feature flags; enable <flag> / disable <flag>. | — |
shep settings messaging | Messaging remote control; status, disconnect. | — |
shep settings init | Reset all settings to defaults. | -f, --force |
See Configuration.
Tools and editors
| Command | What it does | Key flags |
|---|---|---|
shep ide <id> | Open a feature’s worktree in your editor. | --vscode, --cursor, --windsurf, --zed, --antigravity |
shep tools list | Tools Shep knows about and whether they’re installed. | — |
shep install [tool] | Install a tool (agent CLIs, gh, editors, terminals…). | --how (print instructions only) |
shep doctor | Check a contributor’s development environment for working on Shep itself. | — |
Usage metrics
| Command | What it does |
|---|---|
shep telemetry status | Whether usage metrics are on, and what’s queued. |
shep telemetry show | Exactly what would be sent. |
shep telemetry on / off | Turn usage metrics on, or off (deleting queued events). |
shep telemetry identity on/off | Include or leave out identity fields (GitHub username, agent account hash). Off by default. |
shep telemetry contact on/off | Allow or refuse contact from the Shep team on GitHub. |
Integrations
| Command | What it does | Key flags |
|---|---|---|
shep mcp | Run Shep’s MCP server over stdio. Add it to Claude Code with claude mcp add shep -- shep mcp. | --log-level |
shep chat block <kind> | Post a block into a chat: spec-review, preview or plan. Used by agents. | --title (required), --file or --content, --scope |
shep review [PR] | AI code review of a GitHub pull request (number or URL). | --owner, --repo, --post |
shep review list / show <id> / post <id> | List reviews, show one, post one to GitHub. | list -n <n> |
shep plugin catalog / list / add / remove / enable / disable / configure / status | Manage MCP, hook and CLI plugins. | add --name --type mcp/hook/cli --command --transport stdio/http |
shep bedrock init / sync / doctor / ship | Project Bedrock memory for an app (needs Python 3.9+ and pipx). | --app <id> |
shep security enforce | Evaluate a repo’s supply-chain security posture against policy. | -r, --repo, -o table/json/yaml |
Projects
Work items and planning. These commands are always available; the web pages sit behind the projects flag (on by default).
| Command | What it does |
|---|---|
shep project ls / new / show <slug> / del <slug> | Projects. new -n <name> -p <PREFIX> [-r <repo>]. |
shep item ls <project> / new <project> / relate / export <project> | Work items. new -t <title> [-p priority] [--parent <ID>]; export -o <file> writes CSV. |
shep item investigate <item> / hypotheses <item> / fix <item> <n> | The bug loop: an agent ranks root-cause hypotheses, then fixes one (failing test first). --agent, --repo, --spec. |
shep cycle ls / new / show / add-items / transfer | Cycles (sprints). |
shep intake ls <project> / accept <id> / decline <id> | Triage incoming requests for a project. |
shep notifications ls <recipient> | Notifications (alias notif). |
See Projects & bug loop.
Supervisor
Belongs to the collaboration flag (on by default).
| Command | What it does | Key flags |
|---|---|---|
shep supervisor configure | Set a supervisor policy for a scope. | --scope global/repo/app, --scope-id, --feature, --autonomy advisory/cosign/autonomous, --prd-authority, --plan-authority, --merge-authority, --model |
shep supervisor status / enable / disable | Inspect or toggle a scope’s policy. | --scope (required), --scope-id, --feature |
shep supervisor approve / reject | Decide a supervisor run. | --run <id>; reject --reason <text> |
Software factory
Each group below is behind its own feature flag. All of them are on by default; when one is off, its command is hidden and prints how to turn it back on (shep settings flags enable <flag>).
| Command group | Flag | What it does |
|---|---|---|
shep space — ls, show, new, edit, rm, default, line, rule, assign, unassign, config | spaces | Group repos into spaces and product lines, with their own agent logins, git identity, allowed agents, PR-comment and docs-first settings. |
shep connection — add linear/jira/notion, ls, test, rm | trackers or knowledge | Connect Linear, Jira and Notion accounts. |
shep sync — rule add/ls/enable/disable/rm, run | trackers | Keep a Linear team or Jira query in a Shep project. |
shep knowledge — source add/ls/enable/disable/rm, sync, ls, search | knowledge | Notion pages agents in a space can read. |
shep signal — add, ls, rm | signals | Record evidence of what users need. |
shep opportunity — add, ls, show, estimate, link, unlink, accept, drop, build, weights | opportunities | Bets backed by signals, ranked by value per review hour. |
shep feedback — key create/ls/revoke, themes, promote | feedback | Feedback intake keys and themes. |
shep discovery — run, ls, schedule | discovery | An agent reads loose signals and proposes opportunities. |
shep incident — open, ls, show, note, triage, act, approve, reject, resolve | incidents | Production incidents: triage, act on the workload, resolve. |
shep outcome — ls, check, ship, tell, hours | outcomes | What happened after opportunities shipped. |
shep autopilot — show, set, run | autopilot | What Shep starts on its own in a space. |
shep factory status | factory | What a space’s factory is doing and what waits on people. |
See the Software factory section.
Experimental and opt-in
These need a feature flag that is off by default. Turn one on with shep settings flags enable <flag>. See Feature flags.
| Command | Flag | What it does |
|---|---|---|
shep harness — init, run, resume, stop, apply, promote, discard, ls, inspect, view, explain, permissions, capabilities, policies, eval | queryAwareHarness | Shep’s own query-aware agent harness. Hidden until the flag is on. See Agent harness. |
shep learn — status, history, show, diff, adopt, reject, rollback, reflect | selfLearning | Review, adopt and roll back the harness Shep learned from feature runs. |
shep aspm — scan, rescan, ingest, findings, campaigns, posture, exceptions, ai-review | aspm | Application security posture management. |
shep whatsapp status | whatsappDispatch | WhatsApp task dispatch status. |
shep cluster — new, ls, show, del, link, unlink, status | clusters | Kubernetes clusters for apps. The command runs without the flag, but the web pages need it. |
shep workflow — create, list, show, run, schedule, enable, disable, history, update, delete | scheduledWorkflows | Scheduled agent workflows (templates issue-triage, branch-rebase). The command runs without the flag, but the scheduler needs it. |
Tips
shep <command> --helpis the authoritative flag list for your installed version.- Use
--json(feat status,feat wait,ps,usage,logs prune, …) when scripting. - There’s no shell tab-completion script.
shep statusis the fastest way to confirm the daemon is up;shep psshows every agent process.