CLI Reference

Every Shep command, grouped by what it does. Run shep <command> --help for the latest flag list — this page covers the core surface.

Daemon

Command	Description
`shep`	First-run setup, then start the daemon and open the dashboard.
`shep start`	Start the background daemon. Add `--port` to override 4050.
`shep stop`	Stop the daemon.
`shep restart`	Stop and start.
`shep status`	Print daemon status, port, and metrics.
`shep ui`	Open the dashboard (daemon must be running).


shep start --port 4051
shep status
shep stop

Features

The most-used family of commands. shep feat for create, list, inspect, and clean up.

`shep feat new "<description>" [flags]`

Create a new feature. Without flags, Shep uses your default workflow from shep settings.


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-all

Common flags:

Flag	Effect
`--push`	Push the branch when implementation completes.
`--pr`	Open a draft PR (implies `--push`).
`--no-pr`	Skip the PR even if your default opens one.
`--fast` / `--no-fast`	Skip or use the spec-driven pipeline. Default: `--fast`.
`--allow-prd`	Auto-approve the PRD gate (only meaningful in `--no-fast`).
`--allow-plan`	Auto-approve the plan gate (only meaningful in `--no-fast`).
`--allow-merge`	Auto-merge the PR after CI passes.
`--allow-all`	Enable every automation.
`--model <id>`	Override the agent’s model for this feature.
`--attach <path>`	Attach a reference file to the prompt. Repeatable.
`--repo <path>`	Run against a different local repo without `cd`.
`--remote <url>`	Clone a remote repo and run there.
`--parent <fid>`	Create as a child of an existing feature.
`--no-rebase`	Don’t rebase the worktree branch onto the latest base before working.
`--inject-skills`	Auto-inject discovered Claude Code skills into the agent prompt.
`--pending`	Create the feature in a pending state, don’t start the agent yet.

Lifecycle commands


shep feat ls                          # list features in current repo
shep feat show <id>                   # full detail
shep feat logs <id>                   # tail logs
shep feat resume <id>                 # resume paused / blocked feature
shep feat approve <id>                # approve current gate (PRD / plan / merge)
shep feat reject <id> --feedback "..." # reject and request changes
shep feat review <id>                 # open the review view
shep feat archive <id>                # hide feature without deleting
shep feat unarchive <id>              # restore archived feature
shep feat del <id>                    # delete feature and remove worktree
shep feat adopt <branch>              # adopt an existing branch as a Shep feature

<id> can be the feature ID (feat_abc123) or its slug (add-health-endpoint).

Agents

shep agent controls the AI agent processes that implement features.

Command	Description
`shep agent ls`	List agent runs (active and completed).
`shep agent show <id>`	Detail for one agent run.
`shep agent logs <id>`	Stream raw agent output.
`shep agent stop <id>`	Stop a running agent immediately.
`shep agent approve <id>`	Approve a pending agent action (per-task approval).
`shep agent reject <id>`	Reject a pending agent action.
`shep agent delete <id>`	Delete an agent run record.

To stop a feature’s agent without remembering the agent ID, use shep feat show <id> to find the agent ID, or stop from the dashboard.

Repos

Command	Description
`shep repo ls`	List repos Shep is tracking.
`shep repo show <id>`	Detail for one repo (path, active features).

Settings


shep settings                         # interactive wizard
shep settings show                    # print all current settings
shep settings init                    # re-run first-time setup
shep settings agent                   # configure AI agent (Claude / Cursor / Gemini)
shep settings ide                     # configure default IDE
shep settings workflow                # configure workflow defaults (push, PR, etc.)
shep settings model                   # configure default model per agent
shep settings language                # configure dashboard language

shep settings workflow is the most useful — set your defaults once and stop typing the same flags every time.

Tools

Command	Description
`shep tools list`	List the tools Shep needs and whether they’re installed.
`shep install`	Install missing dependencies (gh, etc.).
`shep ide-open`	Open the current repo in your configured IDE.

Other

Command	Description
`shep run`	Run the configured agent directly without the feature pipeline.
`shep version`	Print the installed Shep version.
`shep upgrade`	Upgrade Shep to the latest published version.
`shep review`	Review changes Shep has made across all features.

Experimental commands

A few command families are hidden behind the Agent Collaboration & Supervision feature flag — shep supervisor, shep intake, shep agent message, shep agent questions. They don’t appear in shep --help until the flag is on. See Experimental Features for what they do and how to enable them.

Tips

Run shep <command> --help for the latest, authoritative flag list.
Tab-completion works in zsh and bash if you’ve sourced the completion scripts.
Most commands accept feature slugs in place of IDs — easier to read in scripts.
shep status is the fastest way to confirm the daemon is up.