CLI

CLI reference

Every top-level command, grouped by what you are trying to do. For the exact parser output, add --help to any command.

shape of a command
skep [--home HOME] [--version] <command>
  • --home HOME selects the state directory. It goes before the command. Default: $SKEP_HOME, else ~/.skep.
  • --version prints the package version and the worker contract version.
skep --version
skep --version
skep 1.6.0 (worker contract 0.3.8)
captured: skep --version; the two numbers are filled in from this release's sources

Set up and check

Get a machine ready

The guided first run, the manual profile commands it replaces, the health checks and the model provider registry.

Commands: set up and check
CommandWhat it does
skep onboard [--provider NAME] [--model MODEL] [--endpoint URL] [--api-key-env ENV] [--workdir DIR] [--sandbox auto|podman|none] [--template NAME] [--unlocked] [--role NAME] [--yes] [--no-chat] The guided first run: model, work directory, sandbox, policy baseline, role. The template defaults to builder. After the baseline it asks once whether skep may work in the work directory without asking; --unlocked says yes, and --yes never does. Run it again and it resumes at the first step that is not done.
skep onboard --check Read-only: skep doctor plus the baseline, engine, sandbox, work directory and egress checks. Exits 0 only when all are ready.
skep onboard --quiet | --verbose Turn the first-session why: lines and the per-turn tally off, or back on.
skep setup --personal [--provider NAME] [--model MODEL] [--endpoint URL] [--api-key-env ENV] Create or update the local profile without the guided steps.
skep setup --template NAME [--dry-run] [--apply] Apply a policy template (builder, operator, assistant). --dry-run prints the resolved table and writes nothing; --apply confirms switching an existing policy document.
skep doctor Check configuration and runtime readiness: profile, provider, each engine and its sign-in, the sandbox. Exits non-zero when the profile is not ready.
skep status [--personal] [--json] Setup, provider, sandbox and approval status. --personal adds recent runs with their re-verification state.
skep provider list Registered model providers.
skep provider health The latest health probe of each provider.
skep provider presets The built-in catalog. Each row says where prompts go.
skep provider add [ID] [--preset PRESET] [--protocol P] [--base-url URL] [--model M] [--api-key-env ENV] [--cost-class C] [--order N] [--host H] [--activate] Register a provider profile, from a preset or by protocol (anthropic, bedrock, ollama, openai_compat, openai_responses). --api-key-env takes the name of a variable, never a key.
skep provider use ID Make a profile the active one. The assistant uses it from its next turn.
skep provider set-key ID [--clear] Store a profile's API key. The value is read from standard input and kept in a 0600 file.
skep provider login ID --client-id CID [--device-url URL] [--token-url URL] [--scope S] OAuth device-code login with your own client id; the token is stored as the key.
skep provider remove ID Delete a provider profile.

Run a task

Dispatch work

One task against one repository, a small team of tasks, and a view of the agents running on this machine.

Commands: run a task
CommandWhat it does
skep run [repo] [instructions] --execution-mode sandbox|workspace [options] Run one coding task. skep makes a disposable worktree, starts the worker, records what it does, captures the patch and re-verifies the result.
skep team --manager ROLE --task REPO INSTRUCTIONS [--task …] [--role ROLE] [--delegated-by ACTOR@ROLE] [--execution-mode sandbox|workspace] [--answer-host HOST] [--worker-cmd COMMAND] A team run: a manager in a role dispatches one to three tasks, recorded as one thread in the decision log.
skep agents [--json] Coding agents running on this machine, each working, idle or blocked, and whether skep governs it.
examples
$ skep run /path/to/repo "fix the failing test" --execution-mode sandbox
$ skep run /path/to/repo "fix the failing test" --engine codex --execution-mode sandbox
Options of skep run
OptionWhat it does
--execution-mode sandbox|workspace sandbox runs the worker behind the OS sandbox. workspace has no OS sandbox and is for skep's own worker only. An external engine always runs in sandbox.
--engine aider|builtin|claude_code|codex|pi The coding engine for this run, over the project's pinned engine.
--worker-cmd COMMAND A worker command for this run (default: $SKEP_WORKER_CMD, else skep's own worker). A project pinned to an external engine refuses it unless --engine builtin is passed.
--network DOMAIN A domain the worker may reach; repeatable; added to the project's hosts. Omitted, the policy's default network applies: the builder and operator baselines allow their package registries, the assistant baseline and a bare home allow none. A worker that calls the model always reaches its configured provider.
--minimal Start with deny-all grants and learn through approvals. A worker that calls the model still reaches its provider. Cannot be combined with --template, --network or --env-allow.
--env-allow ENV Pass one environment variable to the worker, by name; repeatable.
--template NAME, --param KEY=VALUE, --no-template Run a saved workflow template and fill its parameters, or skip the automatic match against learned templates.
--ref REF The git ref the worktree is based on.
--role ROLE, --delegated-by ACTOR@ROLE Give the worker a role, whose layer narrows its grants, and dispatch as a delegator: the worker holds no more than the delegator does.
--answer-host HOST On a home with no approved baseline, answer a host the run would ask about, for this run only; repeatable. Required when there is no terminal to ask on.
--auto-approve Retired: still accepted for one release, prints a note and has no effect. A patch lands without a click only when the project turns on auto_apply_verified_patch and pins a real check.
--planning-protocol plan|react One plan up front (the default) or a bounded act-and-observe loop.
--budget-wall-clock, --budget-max-iterations, --budget-max-actions, --budget-max-provider-calls Limits for this run.
--caste CASTE The worker kind: coding (the default) or audit.
--resume-of TASK_ID The task this run supersedes.
--quiet Do not print the live phase lines.

Review and land

Read the evidence, then decide

Approving a completed run applies its patch on a branch. The branch, pull-request and repository commands are your half of git: they run on your own credentials.

Commands: review and land
CommandWhat it does
skep review <task_id> The run's evidence, re-verification result, approval state and diff. A unique prefix of the id is enough.
skep review <task_id> --approve [--branch NAME] [--pr] [--pr-base BRANCH] [--note TEXT] [--actor NAME] On a completed run, apply the patch on skep/<task_id> or the branch you name; the default branch is refused. On a run waiting at a gate, resume it. --pr then pushes that branch and opens a pull request with the GitHub CLI.
skep review <task_id> --deny Reject the pending approval.
skep review <task_id> --allow-command Approve and remember a pending shell command, then resume the run.
skep review <task_id> --reverify Re-verify a completed run that was never re-verified, with the project's pinned verify command. A run with no re-verification record cannot be approved.
skep branch list REPO Branches and how they track origin.
skep branch create REPO NAME [--from REF] Create a branch off a base ref.
skep branch merge REPO --source REF --into BRANCH Merge one ref into a branch. Refuses to merge into the default branch.
skep branch push REPO NAME Push a branch that is not the default branch to origin.
skep branch delete REPO NAME [--remote] Delete a branch; refuses unmerged work.
skep pr list REPO [--state open|closed|merged|all] Pull requests.
skep pr open REPO --branch NAME [--base BRANCH] [--title TITLE] Open a pull request for an existing local branch.
skep pr merge REPO NUMBER [--method merge|squash|rebase] Merge an open pull request. This is the one command that moves the base branch.
skep pr close REPO NUMBER [--delete-branch] Close a pull request without merging.
skep repo list Every repository skep can reach.
skep repo refresh REPO Fetch origin and fast-forward the default branch.
skep repo push-baseline REPO [--base BRANCH] Create the missing default branch on an empty origin.

A worker can never push, pull, fetch or switch branches. skep itself pushes only when you ask: with --pr on an approval, skep pr open or skep branch push.

Projects, policy and roles

Say what is allowed

A project binds a repository to its policy. The policy commands read the rules, answer for one action, and lock the baseline.

Commands: projects, policy and roles
CommandWhat it does
skep project preview REPO [--pack PACK] [--strategy STRATEGY] [--phase PHASE] [--engine ENGINE] [--verify-command CMD] Show what a setup would save, and save nothing.
skep project setup REPO [--pack PACK] [--strategy STRATEGY] [--phase PHASE] [--engine ENGINE] [--verify-command CMD] [--group NAME] [--loopback-port PORT] [--codex-chatgpt-login | --no-codex-chatgpt-login] [--unlocked | --no-unlocked] Save a project. It infers the verify command from the repository's own entry point; --verify-command pins one. A repository that is not a project yet needs --pack or --strategy. Also takes --project-id, --name, --no-seed-schedules and --no-seed-commands.
skep project list Every project.
skep project show [PROJECT_ID] [--effective REPO] One project's policy, or what a run against a repository would actually get.
skep project set-phase PROJECT_ID PHASE Move a project between phases (bootstrap, build, maintain).
skep project remove PROJECT_ID Unregister a project. skep forgets it; the folder is untouched.
skep policy registry Every policy setting skep has.
skep policy rsop REPO The resultant policy for a repository: each key, the layer that decided it, what it overrode.
skep policy why REPO SCOPE ACTION VALUE [--role NAME] [--delegated-by ACTOR@ROLE] Would this one action be allowed here, and which rule decides? Nothing is dispatched or recorded.
skep policy explain SUBJECT A template, baseline or role:<name> as an allow / ask / deny table.
skep policy approve [--template NAME | --file PATH] [--reapprove] [--yes] [--diff] Lock a template or a layer file as the policy baseline. --diff first replays recent decisions under the new layer and shows what flips.
skep policy baseline [status|diff] The approved baseline. status exits 1 when the file no longer matches its lock.
skep policy migrate --dry-run Replay the decision log under today's policy and list every verdict that changes. Writes nothing.
skep policy decide SCOPE ACTION VALUE [--repo REPO] [--actor NAME] [--role NAME] [--delegated-by ACTOR@ROLE] [--read-only] Decide one action for an agent outside skep, and record the decision.
skep policy hook [--actor NAME] The same decision as a Claude Code PreToolUse hook: payload on standard input, verdict as hook JSON.
skep policy grants Every learned grant: its id, what it matches, its lifetime, what it is bound to.
skep policy revoke RULE_ID Remove one learned grant. What it allowed asks again.
skep policy decisions [--actor GLOB] [--since TIME] [--limit N] [--team ID] The decision log, newest first, with counts per verdict.
skep role list Every role; * marks the one new chats open in.
skep role show NAME One role's record and its policy layer as a table.
skep role use NAME [--chat ID] Set the role new chats open in, or switch one chat.
skep trust CHAT_ID [--bit private|untrusted] Trust a chat again by clearing its taint bits. The chat deck's /trust is the same action.

The daemon and the chat

Talk to the assistant

skep serve is the local daemon: the HTTP API, the web interface, the chat and the schedule ticker. skep chat is the same chat in a terminal.

Commands: the daemon and the chat
CommandWhat it does
skep serve [--host HOST] [--port PORT] [--worker-cmd COMMAND] [--no-readopt] Run the daemon. It prints its address and an access token at startup. Workers still running from a previous serve are picked up again unless --no-readopt.
skep chat [--url URL] [--chat ID] [--continue] [--thinking] [--role ROLE] [--oneshot MESSAGE] [--yes] Talk to the assistant in the terminal. It needs a running skep serve.
skep start [--host HOST] [--port PORT] The older status dashboard. skep serve is the full daemon and is what you normally want.
skep channel status One line for each messenger channel: configuration, secret present or not, last delivery.
Options of skep chat
OptionWhat it does
--continue, --chat ID Resume the most recent chat, or one by id.
--role ROLE Open the new chat in this role. The default is the one skep role list marks with *.
--oneshot MESSAGE Send one message to a new chat, print the reply as it streams, and exit. No prompts: cards the turn proposes are skipped and reported by id.
--yes With --oneshot: confirm every card this turn proposes, once. Never a policy card; those stay pending.
--thinking Show the model's thinking, dimmed.
--url URL The daemon's address. Default: $SKEP_SERVE_URL, else the port this home's serve recorded, else port 8765 on this machine.

Repeat and reuse

Schedules, templates, skills and memory

Recurring runs, saved task shapes, and the two things skep can learn only with your approval.

Commands: repeat and reuse
CommandWhat it does
skep schedule add NAME REPO [INSTRUCTIONS] --every 1d [--template NAME] [--param KEY=VALUE] [--caste CASTE] [--ref REF] [--network DOMAIN] [--env-allow ENV] [--role NAME] [--start-at TIME] [--once] Add a recurring run, from instructions or a saved template. --every takes 30s, 5m, 2h or 1d. --start-at sets the first run (a time with no zone is UTC); --once fires once, then disables.
skep schedule list Every schedule.
skep schedule remove NAME Remove a schedule.
skep schedule health How each schedule has been doing.
skep tick [--worker-cmd COMMAND] Dispatch every due schedule once, for cron. A running skep serve does this itself.
skep template add [NAME] [--instructions TEXT] [--from FILE] [options] Author a workflow template, from flags or a .toml or .json file.
skep template list Every template.
skep template show NAME One template in full.
skep template suggest NAME REPO INSTRUCTIONS [--save] Suggest a template from remembered approvals; --save keeps it.
skep template remove NAME Remove a template. skep template delete is the same command.
skep template rename OLD_NAME NEW_NAME Rename a template; schedules bound to it follow.
skep skill … The learned-skill lifecycle: propose, list, show, test, approve, reject, export, seed, shelf, promote, packs, import-md, import. Nothing is admitted without your approval.
skep skill shelf [list|add|remove] [PATH] Register a directory of Agent Skills, for example ~/.claude/skills.
skep memory … Durable memory, gated by proposals: list, search, show, forget, add (the operator records a fact directly, with no proposal), proposals, propose, approve, reject, approve-batch, reject-batch.

Agents you run elsewhere

Govern an agent skep did not start

Two ways to put skep's policy in front of an agent running in another tool. Both decide from the same policy and record the decision; neither is a sandbox.

Commands: agents you run elsewhere
CommandWhat it does
skep acp govern [--repo PATH] [--actor NAME] -- AGENT_ARGV… The process an ACP client starts in place of the agent. It answers the agent's permission requests from policy and records them.
skep acp doctor -- AGENT_ARGV… Start the agent, open a dry session and print what skep can govern in it. Sends no prompt.
skep acp install-hint Print the rows to paste into T3 Code's Local ACP command dialog.
skep policy hook The Claude Code PreToolUse hook (listed above with the policy commands).

What each one covers and does not cover is on the agents page.

Ops and imports

Nodes, ops checks and imports

A smaller surface: governed operations checks against registered machines, and a one-way import from Hermes.

Commands: ops and imports
CommandWhat it does
skep node add NODE_ID [--name NAME] [--host HOST] [--kind local|ssh|container] [--trust LEVEL] [--cap CAP] Register a node and the ops capabilities it allows.
skep node list Registered nodes.
skep ops run CHECK --node NODE [--approve] [--arg KEY=VALUE] Resolve an ops check against a node. Without --approve it is a dry-run plan.
skep ops schedule add … Add a conservative ops schedule.
skep hermes import [--hermes-home PATH] [--dry-run] Stage Hermes memory, skills and sessions behind skep's existing gates: they arrive as proposals and drafts.

Slash commands

The command deck

In the web chat and in skep chat, a message that starts with / is a command of yours. The model never sees it.

The deck, read at build from the web app's COMMANDS table
CommandWhat it doesEffect
/help list the command deck read
/policy [repo] effective policy for a repo (default: last used) read
/repos registered repos read
/skills learned-skill candidates and admitted skills read
/runs [n] recent runs read
/approvals the pending approval queue read
/state <repo> a repo's git state: branches, HEAD, recent commits read
/setup <repo> [--pack X] [--phase Y] bind a repo to a trusted project confirm card
/phase <project-id> <bootstrap|build|maintain> move a project's trust phase confirm card
/unregister <project-id> unregister a project: skep forgets it, its folder stays confirm card
/land <task-id> [branch] land a completed run's patch confirm card
/approve <review-id|card-id> [branch] approve a pending review, or a pending card by its id confirm card
/deny <review-id|card-id> deny a pending review, or a pending card by its id confirm card
/workon <path> [--pack X] [--phase Y] make a local directory a first-class workspace — git baseline + trusted project confirm card
/schedule <name> <repo> <every> <instructions…> create a recurring schedule the ticker dispatches — every takes 30m/6h/1d confirm card
/role <builder|operator|assistant|custom-role> switch this chat's role — prompt, voice and policy layer together; a role only tightens the baseline confirm card
/personality <concise|technical|friendly|custom:text|default> set this chat's reply style — style only, never policy confirm card
/persona <text…|default> set the profile-level identity every chat starts with — identity only, never policy confirm card
/btw <question…> ask a side question WITHOUT touching running work — read-only turn: no cards, no mutations, runs beside a pending card read-only turn
/steer <task-id> <text…> send a steering note into a RUNNING react run — input, never authority: resolves no card, approval, or gate acts at once
/resume <task-id> continue a crashed/timed-out run from its checkpoint — model-free confirm card
/browser register the built-in Playwright browser under the browse scope confirm card
/trust [private|untrusted] trust this chat again: clear its taint (both bits by default) — yours only, never the model's; outside content read later sets it again acts at once
  • A command marked confirm card changes something, so it shows a card and waits for your yes.
  • /trust and /steer act at once, with no card. In the terminal, a typed /approve or /deny is the decision itself and is not asked twice.
  • /approve and /deny take a review id or a card id. /land takes a task id. Approving a completed run's review already applies its patch; /land lands a completed run directly.
  • /workon is not a selector: it makes a directory a workspace, with a git baseline and a project.
  • There is no command that starts a run. Ask for the work in a plain message and confirm the card the assistant proposes, or use skep run.
Terminal only: these five exist in skep chat, not in the web chat
CommandWhat it does
/status Print the startup line again: assistant readiness, approvals and cards waiting.
/model [name] [--scope chat|default] Show the model this chat uses. With a name, propose a change of model on a card.
/replay Print the last messages of this chat.
/stop Stop this chat's running turn at its next step. The web chat has a Stop button on its working line.
/exit Leave the chat. A bare exit or quit also works.

The same reference as one markdown file, with more detail on roles and delegation: CLI reference doc.