Skip to Content
GuidesCLI Reference

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:

FlagEffect
--verboseMore output.
--debugDebug output.
--log-level <level>debug, info, warn, error or silent.
-v, --versionPrint the version.
-h, --helpHelp for any command.

Daemon and web UI

CommandWhat it doesKey flags
shepStart Shep in the background (if it isn’t running) and open the web UI. Same as shep start.—
shep startStart the background daemon. Default port 4050; if it’s busy, the next free port.-p, --port <n>
shep stopStop the daemon.--force
shep restartRestart the daemon (starts it if it isn’t running).-p, --port <n>, --force
shep statusIs the daemon running, on which port.--logs [lines] (default 50), -f, --follow
shep uiRun the web server in the foreground in this terminal (not as a daemon). Stop with Ctrl+C.-p, --port <n>, --no-open
shep versionPrint version information.—
shep upgradeUpgrade Shep to the latest version.--force
shep logs pruneReport — 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
FlagEffect
-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.
--pushPush the branch when implementation completes.
--pr / --no-prOpen (or don’t open) a draft PR. --pr implies --push.
--fast / --no-fastImplement straight from the prompt (default), or run the spec-driven phases.
--exploreStart an exploration (prototype) session instead.
--allow-prdAuto-approve the requirements gate.
--allow-planAuto-approve the plan gate.
--allow-mergeAuto-approve the merge gate: Shep merges once CI is green.
--allow-allAuto-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.
--pendingCreate the feature without starting the agent.
--no-rebaseSkip syncing main from the remote before creating the branch.
--inject-skills / --no-inject-skillsInject 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

CommandWhat it doesKey flags
shep feat lsList 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

CommandWhat it doesKey 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

CommandWhat it doesKey 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

CommandWhat it doesKey flags
shep fleet statusRunning, queued, waiting on you and failed counts; queue and circuit-breaker state.--repo <path>
shep fleet triageEverything across the fleet that needs a human decision.--repo <path>
shep fleet approveBatch-approve features waiting at gates. One of the flags is required.--all, --gate prd/plan/merge, --low-risk
shep fleet retry --failedRestart the agents behind crashed, failed or stopped runs.--repo <path>
shep fleet pausePause the admission queue. Running agents continue; new work waits.--reason <text>
shep fleet resumeResume 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

CommandWhat it doesKey flags
shep tuiLive 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 psThe 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

CommandWhat it doesKey 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-loginManage 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 / logsRun 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 / clearInspect, pin or clear how the dev server is started.set -c <command> --cwd --port --setup …
shep dev approveApprove the commands in the repo’s .shep/dev.json.--fingerprint <hash>

See Start an app and Dev servers.

Agents and sessions

CommandWhat it doesKey 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 / cancelQuestions 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 usageAgent 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

CommandWhat it doesKey flags
shep repo lsTracked repos: ID, name, feature count, path.—
shep repo show <id>Details of one repo.—
shep repo addClone 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

CommandWhat it doesKey flags
shep settingsInteractive wizard: agent, IDE, workflow defaults.—
shep settings showPrint current settings.-o table/json/yaml
shep settings agentDefault agent and auth. --auth is required with --agent (except dev).--agent <type>, --auth session/token, --token <key>
shep settings modelDefault model (interactive).—
shep settings effort [level]Default reasoning effort.--clear
shep settings adaptive-modelsPer-task model tiers.--enable, --disable, --high, --medium, --low <model>, --clear
shep settings workflowDefault 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 worktreeCustom worktree commands.--create-command, --post-create-command, --timeout <ms>, --clear
shep settings ideDefault editor.--editor <name>
shep settings languageDisplay language.—
shep settings flagsList feature flags; enable <flag> / disable <flag>.—
shep settings messagingMessaging remote control; status, disconnect.—
shep settings initReset all settings to defaults.-f, --force

See Configuration.

Tools and editors

CommandWhat it doesKey flags
shep ide <id>Open a feature’s worktree in your editor.--vscode, --cursor, --windsurf, --zed, --antigravity
shep tools listTools Shep knows about and whether they’re installed.—
shep install [tool]Install a tool (agent CLIs, gh, editors, terminals…).--how (print instructions only)
shep doctorCheck a contributor’s development environment for working on Shep itself.—

Usage metrics

CommandWhat it does
shep telemetry statusWhether usage metrics are on, and what’s queued.
shep telemetry showExactly what would be sent.
shep telemetry on / offTurn usage metrics on, or off (deleting queued events).
shep telemetry identity on/offInclude or leave out identity fields (GitHub username, agent account hash). Off by default.
shep telemetry contact on/offAllow or refuse contact from the Shep team on GitHub.

See Usage metrics & privacy.

Integrations

CommandWhat it doesKey flags
shep mcpRun 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 / statusManage MCP, hook and CLI plugins.add --name --type mcp/hook/cli --command --transport stdio/http
shep bedrock init / sync / doctor / shipProject Bedrock memory for an app (needs Python 3.9+ and pipx).--app <id>
shep security enforceEvaluate a repo’s supply-chain security posture against policy.-r, --repo, -o table/json/yaml

See MCP and A2A.

Projects

Work items and planning. These commands are always available; the web pages sit behind the projects flag (on by default).

CommandWhat 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 / transferCycles (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).

CommandWhat it doesKey flags
shep supervisor configureSet 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 / disableInspect or toggle a scope’s policy.--scope (required), --scope-id, --feature
shep supervisor approve / rejectDecide a supervisor run.--run <id>; reject --reason <text>

See Supervisor & guardrails.

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 groupFlagWhat it does
shep space — ls, show, new, edit, rm, default, line, rule, assign, unassign, configspacesGroup 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, rmtrackers or knowledgeConnect Linear, Jira and Notion accounts.
shep sync — rule add/ls/enable/disable/rm, runtrackersKeep a Linear team or Jira query in a Shep project.
shep knowledge — source add/ls/enable/disable/rm, sync, ls, searchknowledgeNotion pages agents in a space can read.
shep signal — add, ls, rmsignalsRecord evidence of what users need.
shep opportunity — add, ls, show, estimate, link, unlink, accept, drop, build, weightsopportunitiesBets backed by signals, ranked by value per review hour.
shep feedback — key create/ls/revoke, themes, promotefeedbackFeedback intake keys and themes.
shep discovery — run, ls, schedulediscoveryAn agent reads loose signals and proposes opportunities.
shep incident — open, ls, show, note, triage, act, approve, reject, resolveincidentsProduction incidents: triage, act on the workload, resolve.
shep outcome — ls, check, ship, tell, hoursoutcomesWhat happened after opportunities shipped.
shep autopilot — show, set, runautopilotWhat Shep starts on its own in a space.
shep factory statusfactoryWhat 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.

CommandFlagWhat it does
shep harness — init, run, resume, stop, apply, promote, discard, ls, inspect, view, explain, permissions, capabilities, policies, evalqueryAwareHarnessShep’s own query-aware agent harness. Hidden until the flag is on. See Agent harness.
shep learn — status, history, show, diff, adopt, reject, rollback, reflectselfLearningReview, adopt and roll back the harness Shep learned from feature runs.
shep aspm — scan, rescan, ingest, findings, campaigns, posture, exceptions, ai-reviewaspmApplication security posture management.
shep whatsapp statuswhatsappDispatchWhatsApp task dispatch status.
shep cluster — new, ls, show, del, link, unlink, statusclustersKubernetes 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, deletescheduledWorkflowsScheduled agent workflows (templates issue-triage, branch-rebase). The command runs without the flag, but the scheduler needs it.

Tips

  • shep <command> --help is 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 status is the fastest way to confirm the daemon is up; shep ps shows every agent process.