Skip to content

CLI

Generated from the code by apps/docs/scripts/reference.mjs: edit the source, not this page.

wisp --help prints this. wisp help <plugin> [verb] lists a plugin’s verbs and a verb’s flags: every plugin command below is also wisp <plugin> <verb> (see Commands).

Commands and tasks. Words that aren’t a command are a task: wisp fix the flaky test starts one. A line whose first word is one of wisp’s command groups (computer, cloud, grid, crew, trigger, plugin, recipes, machines, machine, share, version, skill, mcp, …) is that command when one word follows: a verb it doesn’t have (wisp update deps, wisp settings open) prints its verbs and exits 2. Two or more words after it are a task (wisp update the readme, wisp share the results with the team). show, stop, wait, reply, attach and btw take a task’s id, or last for the newest; one other word is a slip, two or more a task (wisp show me where the bug is). A few command words also start everyday prompts and are a task when their command’s argument isn’t there: wisp ship the docs, wisp run the tests, wisp plan the migration (ship, merge, run, plan, init, notes, export, …). A verb the group doesn’t have (wisp computer start), a flag its command doesn’t take, or words it doesn’t take print the group’s verbs or the command’s usage and exit 2. To start a task that begins with such a word, quote it as one argument (wisp "computer start fails on boot, fix it") or put -- first (wisp -- computer start fails on boot). A plugin’s name is its command only when one of its verbs follows (wisp channels refresh, where a bad flag is an error too); otherwise the line is a task, so wisp review the auth module and wisp update the readme start tasks.

Terminal context. After a command fails, wisp "check the error above" adds what just happened in this terminal to the task: the last commands and their exit codes, the failing one’s output (tmux, WezTerm, kitty, iTerm2, Terminal), the folder and git status, with secrets masked. --context, --no-context, --show-context and --lines N decide it for one run; wisp shell-init zsh|bash|fish adds the hook that records each command’s exit code. See Ask about what just happened in your terminal.

usage:
wisp open wisp
wisp "task" launch a task in this folder
wisp serve run wisp here, in this terminal, without opening anything (--port N --host ADDR)
wisp add [folder] add a project: a folder here, a path or a git link (wisp add a README is a task)
wisp "task" -d launch it and return with its id (the default outside a terminal; --wait blocks)
wisp attach <id> follow a task live: its steps, its answer, its questions; a reply box after
(Ctrl-C detaches, a second Ctrl-C stops it)
wisp ls list sessions (the newest 50; --state running,waiting,review,done|needs --limit N --all, -a: all, archived too
--watch: follow the list)
wisp show <id> state + latest presentation as markdown (--watch: follow its turn live)
wisp wait <id> block until it finishes or asks you something
wisp reply <id> "text" follow up (answers a pending question) (--queue --mode plan|edits|auto
--agent ID --model ID --effort LEVEL: switch harness / model from here on)
wisp btw <id> "question" ask on the side without interrupting the run; prints the answer
wisp stop <id> stop a run
wisp held <id> start|without|skip a turn held before it started: start it (Trust and start), run it without the
repo's own programs, or skip this run
wisp ship <id> commit, push and open a PR for a worktree session (--draft)
wisp merge <id> squash-merge its PR and sync your local base branch
wisp run <recipe> [values…] run a saved recipe; values fill its {params} in order, or key=value
wisp recipes list recipes
wisp plugin list plugins
wisp plugin new <name> start a plugin of your own in ~/.wisp/plugins/<name>
wisp plugin enable|disable|trust|untrust <id> switch a plugin on or off; trust one you installed (its theme applies)
wisp plugin install <folder|git URL> install one, off, and see what it asks for; remove <id> takes it out
wisp crew list your crew
wisp crew pause|resume <member> stop a member's check-ins and jobs, or start them again (by name or id)
wisp init a .wisp/ folder here: wisp.yml, the AGENTS.md note, its modules fetched and locked
(asks first outside a git repo or project; --here: make it anyway)
wisp plan|destroy what applying .wisp/ would change; take out everything it declares (--yes)
wisp fmt format the .wisp/ folder (--check)
wisp workspace [list|show|select|new NAME] the folder's workspaces: one set of variables each
wisp output [name]|graph|mv FROM TO the folder's outputs, its references as Graphviz, rename an address
wisp track <id> keep a task in this repo's .wisp/tasks, for you to commit (--level spec|report|full)
wisp untrack <id> take a tracked task out again
wisp log [path] the tracked tasks, newest first; with a path, the ones that touched it
wisp blame <file>:<line> which task wrote that line, and what it was asked
wisp resume <id> a new task that carries on from where that one stopped, on today's code
wisp adopt [<id>|--all] bring in sessions you ran in a harness outside wisp (--since 7d --track)
wisp notes [<task>] [--set section=text] a task's Notes (goal, decisions, what failed, state …); --set rewrites one
wisp fresh [<task>] [--print] [-f brief.md] a new conversation on the same task, from a brief (--print shows it)
wisp hook install|uninstall|status a git hook that adds Wisp-Task: <id> to commits a task's agent makes
wisp secret set|rm NAME a secret your formulas reference as ${secret:NAME}: piped in or typed hidden, never an argument
wisp import [home] bring another wisp home (~/.wisp) in: its plan first, then on yes (--dry-run --yes)
wisp apply -f wisp.yml your setup as code: plan, diff, confirm (--dry-run --yes --prune --trust --profile P)
wisp diff|validate -f F what apply would change; schema and checks (wisp schema: the editor schema)
wisp export [kinds…] what's set up here, as a formula (--include ui,account --format yaml|json|toml)
wisp task spec|export|formula|history <id> what was asked, to share, the setup it ran with, its family
wisp run -f x.task.yml a shared task spec, on your code; its formula: ./wisp.yml, module.x or inline
(wisp run <workflow|task> [k=v]: by name, --wait)
wisp run <task> --formula F a task a formula declares, by its name, nothing applied (--formula F "…": a prompt)
wisp rerun <id> the same ask from the same commit (--from latest --formula f.yml[,g.yml]
--fill-from-snapshot --steps N --agent … --last N --project P --wait)
wisp ls --agent|--crew|--workflow|--formula f.yml|--since 7d tasks by what made them
wisp history export --since 30d every task as JSONL, scrubbed
wisp share <id> a signed .wisp-task, previewed with its redactions (--level spec|report|full --to cloud|file|gist
--access anyone|people:a,b|teams:t|password --expires 7d --publish)
wisp share <kind>.<name> a setup (with what it references) to wisp Cloud (--to cloud --access … --publish)
wisp shares what you've shared: access, views, imports, versions (--revoke ID --updates)
wisp open <file|url|link> a shared task or setup: its plan, then run, import or apply it (--run --their-setup --compare --import --yes)
wisp cloud signin|status|signout wisp Cloud (or another grid: wisp cloud signin <url>)
wisp cloud accounts|switch|remove each grid account signed in to; switch or sign out of one
wisp version print this wisp's version (also --version, -v)
wisp update [apply] is there a newer wisp? apply installs it (wisp help update: check, view)
wisp usage your limits this period and what each task took (--agent ID: that harness's, by task)
wisp machines|machine <verb> your machines and this one: list, add, remove… (wisp help machines)
wisp spell|spells spells are plugins: wisp plugin new|install
wisp computer on|off|status this computer on the grid, reachable from your other wisps (on --grid <url>: signs in there first)
wisp --on <machine> … run any command on that machine (wisp ls --on studio, wisp "task" --on cloud)
wisp desktop open the wisp app window
wisp mcp run the MCP server (stdio) for other agents and editors
wisp skill [install] print / install the wisp agent skill (--agent claude|codex|opencode|all --project)
wisp grid dev|init|serve|doctor wisp Grid: wisp for many people on your server (wisp grid help)
wisp <plugin> <verb> … any command of any plugin, flags from its arguments (wisp crew create --name Ada)
wisp help [plugin [verb]] every plugin's commands, a plugin's verbs, a verb's flags
wisp completions zsh|bash|fish shell completions from the same catalogue
wisp shell-init zsh|bash|fish a hook for your shell's rc file: wisp then knows each command you ran, its folder and
its exit code (kept 7 days on this machine; eval "$(wisp shell-init zsh)" in ~/.zshrc)
wisp tasks --touching <path>|--tracked the tracked tasks (.wisp/tasks) behind a path, or all of them (--json)
wisp sdk types ts|py [FILE] typed commands for the SDKs (a .d.ts or a .pyi), from the same catalogue
wisp -- ls the repo a task that starts with a command's word; or quote it as one: wisp "computer start fails"
(after a command group, computer, cloud, grid, crew, plugin, settings…, one word it
doesn't have is an error naming its verbs; two or more are a task: wisp share the results
with the team. show, stop, wait, reply, attach and btw take a task's id or last; other
words after them are a task: wisp show me where the bug is)
launch options: --mode plan|edits|auto --agent claude|codex|opencode|cursor|antigravity|grok|copilot --model ID --effort LEVEL
--cwd DIR --also DIR (repeatable) --wait --json --no-worktree --compare agent[:model],…: one task per harness
--try subagents=haiku|sonnet|task --try skills=off run it twice on --agent, the second with
that changed (repeatable or comma separated); Compare says what differed
--goal NAME keep going until a goal declared by name (goals: in a formula) is met
--goal-text "…" the same with what done means in words
--formula f.yml[,g.yml] run under these formulas, nothing applied (its agents, skills, connectors…)
--factory [NAME] run it through a software factory (spec, build, checks, review, ship); alone: default
--yes go ahead although it takes a usage window past your Ask near the limit line
terminal context: wisp "check the error above" attaches what just happened in this terminal: its last commands, their
exit codes, the failing one's output (tmux, WezTerm, kitty, iTerm2, Terminal), the folder and git status,
secrets masked; never runs a command again (--context --no-context --show-context --lines N)
options: --port N --browser --no-open --json --version