Using the CLI
wisp --help lists every command by group, and wisp <command> --help (or
wisp help <command>) shows one command's forms and options. The full list is in the
Reference.
Running a prompt
wisp run "summarise the open TODOs in this repo"
wisp run sends the prompt, waits for the agent to finish, prints the answer and exits.
There is no time limit on the wait. Ctrl-C ends only the wait: the Run goes on in the
Runtime. wisp cancel stops it.
- Without a Session id it starts a new Session whose Project is the current folder.
- stderr gets
session <id>first, before the wait, so you can cancel or continue that Session. stdout gets the answer only, sowisp run "…" > answer.mdworks. With--jsonthe id is the outcome'ssessionIdinstead. - Exit code is
0when the Run completed and1when it failed or was cancelled. A failed Run printsfailed: <reason>: <message>on stderr. The reasons are listed in Troubleshooting. - Not signed in yet? At a terminal,
wisp runasksNot signed in. Run wisp login now?and signs you in before the Run. From a script, or with--json, it does not ask.
Continuing a conversation
Pass the Session id first:
wisp run 6b4f2a7e-… "now turn that into a checklist"
The agent sees the whole history of that Session. If a Run is already going on the Session, the new one waits for it to finish.
Choosing a model
wisp models lists the models the proxy offers, one per line:
wisp models
# <id> <tiers> <context window> <capabilities>
The columns are the model's id, the tiers it belongs to, its context window in tokens, and
what it can do besides text, such as images. A - means the catalog says nothing. With
--json, wisp models prints the catalog as the proxy sent it.
wisp run --model picks the model for one Run:
wisp run --model advanced "…" # the best model; the proxy picks which
wisp run --model balanced "…" # a model of the balanced tier
wisp run --model <id> "…" # this model
wisp run --model tier:<name> "…" # any model of this tier; the proxy picks which
--thinking asks for the thinking form of advanced, balanced or a model id, where the
model can reason.
- Without
--model, the Run uses the Session's own model (chosen with/modelin a chat), else the Runtime Default, elseteeLlmModelfrom the configuration. See Configuration. - A retry with
wisp retryuses the model its Run asked for. - Over
/v1, the same value goes in the Run'smodelPreference(the adapter contract).
The Runtime sizes the conversation to the smallest context window among the models your
choice can reach, so a tier with a small model in it compacts earlier. If none of them lists
images, the agent cannot look at an image file and tells you so.
Running a Skill
wisp skills list --project . # the Skills this folder's Sessions get
wisp run --skill open-case "$(cat alert.json)" # the text after the name is the Skill's arguments
wisp run 6b4f2a7e-… --skill summarise "" # a Skill on an existing Session, no arguments
Where Skills live, how to write one and the other ways to run one are in Skills.
Retrying safely
--key <k> gives the Run an idempotency key. If the same command runs again with the same
key, it gets the first Run's answer instead of running the prompt twice. This is what makes
a cron job or a retry loop safe. See Runs and restarts.
Structured answers
--output-schema <file> sends a JSON Schema (its root an object) that the answer must match.
On success wisp run prints only the value, as JSON, so the next command in a pipeline can
read it; --json still prints the whole outcome with the value in output.structured.
wisp run --output-schema verdict.json "is the build green?" | jq -r .status
A file that cannot be read or is not JSON is a usage error (exit 2) and nothing is sent; a
schema the Runtime refuses prints its 400 and exits 1. A Run whose agent never produces a
matching value fails output_schema_unsatisfied and exits 1.
Long Runs and approvals
wisp run --detach "rebuild the weekly report" # prints the Run id and returns
wisp runs events <run> # follow it: the answer as it is written, each tool call
wisp runs show <run> # its status, and its answer once it ended
wisp runs list --status running,parked # what runs now, and what waits on a person
wisp retry <run> # run a failed or cancelled Run's message again
--interactive lets a tool the Rules hold for a person wait for an answer instead of being
refused; it is refused only when the operator left interactive out of
confirmationModes. On a park wisp run prints each
Prompt and exits 3; answer with wisp confirm <run> <prompt> approve (or deny,
allow-project, allow-global), which waits for the next park or the end, exactly like
wisp run. Add --detach to answer and return at once.
The agent can also ask you questions on an --interactive Run: wisp run prints each card
as <question> ask_user <questions> and exits 3. Answer with
wisp answer <run> <question> "<answer>"..., one answer per question in order, or skip it
with wisp answer <run> <question> --skip. A question that takes several picks
("picks": "many") is answered with a list: pass every answer as JSON with
wisp answer <run> <question> --answers '[["Postgres","SQLite"],"accounts"]', a list where a
question takes several picks and a string elsewhere.
A Run has no step limit: the agent works until the task is done, it is cancelled, or the
model stops answering and the retries run out. --max-turns <n> stops it after n model calls, as failed with
step_ceiling; use it for unattended work you want bounded.
Sessions
wisp sessions list # Sessions started from this folder by the CLI
wisp sessions list --all # every Session, Wisp Desktop's included
wisp sessions list --origin telegram # every Session one client opened, e.g. the Telegram bot's
wisp sessions show <id> # a Session's messages
wisp sessions create --title "…" # start an empty Session and print its id
wisp sessions delete <id>
list prints one line per Session: id, origin (cli, desktop, telegram, slack or schedule), last update,
number of messages and title.
Sessions are kept on disk. They survive restarts and cost nothing while idle. A Session with a Project is found again through its folder, so continue it from that folder; see Sessions, Projects and the Desk.
Stopping a Run
wisp cancel <session>
This stops the Session's current Run and every Run queued behind it. The wisp run that was
waiting exits with 1 and prints cancelled.
What the agent did
wisp audit <session>
# 2026-09-18T11:04:22Z mcp__github__list_pull_requests ok 380ms allow
# 2026-09-18T11:04:23Z mcp__github__create_issue error 1ms ask
Every tool call of the Session, newest first: when it happened, the tool, whether it
succeeded, how long it took, and the Rule's decision. The audit also keeps what each tool
was given and what it returned, in the encrypted store: long strings cut short, and values
under names such as token or password masked. --json shows the arguments. A row like
the second one is a tool that was refused because no Rule
allowed it. See Permissions.
Plan and balance
wisp billing status # the plan's windows, the balance, auto-reload
wisp billing topup 10 # print a payment link for $10 and wait until it is paid
wisp billing auto-reload --threshold 5 --target 20
wisp run may be paid from the prepaid balance rather than the plan. When a Run fails
quota_exhausted because the balance is empty, wisp run prints the topup command to run.
See Plan and balance.
From scripts
--jsonmakes a command that lists or shows something print a single JSON document on stdout and nothing else there. Forwisp runit is the full Run outcome plussessionId.- Exit codes are stable:
0done,1failed,2bad command line,3parked on a Prompt (--interactive),4no Runtime reachable,5token refused. See the full table.
wisp run "check the build log for new warnings" --json | jq -r .output.text
A script that lets a person approve what the agent may not do alone branches on the exit code:
wisp run --interactive --json "draft the release notes and post them to #releases" > out.json
case $? in
0) jq -r .output.text out.json ;;
3) jq -r '.runId as $r | .confirmations[] | "wisp confirm \($r) \(.id) approve # \(.toolName)"' out.json ;;
*) jq -r '.failure.reason // empty' out.json >&2; exit 1 ;;
esac
On 3 it prints the wisp confirm line for each Prompt; whoever runs it gets the Run's
next park or its end, with the same exit codes. The same flow over HTTP is in
A first automation.
Reaching a Runtime
A wisp command finds the Runtime through $WISP_HOME/runtime.lock, which the running
Runtime writes. You can name one explicitly instead, either with flags or with environment
variables:
wisp status --url http://127.0.0.1:3008 --token "$TOKEN"
WISP_URL=http://127.0.0.1:3008 WISP_TOKEN="$TOKEN" wisp status
The URL and the token go together. Plain http is accepted for loopback addresses only, so
a token is never sent over a network unencrypted. To reach a Runtime on another machine,
use the https:// address of a TLS proxy in front of it, or an SSH tunnel to its loopback
port (ssh -N -L 3008:127.0.0.1:3008 you@server, then --url http://127.0.0.1:3008); see
Remote access. A token for a script
is a named one, wisp tokens create --name <n> --capability full, made on the Runtime's
machine. $TOKEN is that token, not the agentToken of runtime.json: on a machine with
Wisp inside Hermes, that one changes at every Hermes start.