CLI Reference
wisp help <command> or wisp <command> --help shows one command's rows. App commands run from the app's folder.
Commands
| Command | What it does |
|---|---|
wisp new [name] | create an app (options below) |
wisp dev [--port|-p <n>] | run the app, rebuild and reload on save (port 3000). With --port 0, the system picks a free port. HOST can be 0.0.0.0 or an address of this machine (HOST=192.168.1.5): a save of a template still swaps in with no rebuild |
wisp dev --https | serve over TLS with a self-signed certificate made once in .wisp/dev-cert.pem and .wisp/dev-key.pem (renewed when you delete them, when the address in HOST is new, or when it expires). Browsers ask once to trust it. For secure-context APIs (camera, clipboard, service workers) on a LAN address with HOST=0.0.0.0. Not with --target |
wisp dev with [package.metadata.wisp.dev.proxy] | forward paths to other http:// or https:// servers, and with [package.metadata.wisp.dev] run start companion commands (Config) |
wisp dev --target node|bun|deno | the dev loop through that host's glue, built into .wisp/emulate/<host> (refuses vercel, netlify, lambda, native, cloudflare, pages). --port 0 is an error with --target |
wisp preview [--port|-p <n>] [--fast] | build the release binary and run it as deployed (port 4173). It checks the port and waits for the app on HOST. --port 0 is an error |
wisp preview --static|--spa [--out dist] [-p <n>] | export the site and serve it like a static host (no server code, POST is 405). --spa falls back to index.html |
wisp build | one release binary with CSS and static files inside |
wisp build --sourcemap | the same, with source maps for browser code |
wisp build --fast | quicker ThinLTO build for CI and iteration |
wisp clean [--cache] | cargo clean of target/. --cache also deletes the shared build cache (WISP_BUILD_CACHE), only a folder that a build marked when it was new or empty and that holds only the entries of a cargo build directory |
wisp build --analyze | each route's JS, CSS and wasm bytes, raw and gzipped, then the heaviest modules with the routes that load them, and modules with equal bytes. Builds nothing |
wisp build --analyze=json | the same as one JSON document on the standard output, for tools: total, routes, modules and duplicates |
wisp build --analyze=html [--out file] | a treemap page of all modules and of each route. It writes target/wisp-analyze.html, or file. A relative path starts at the app folder. The page has no script and loads no outside file |
wisp build --static [--out dist] | the pages as plain files for a static host. Removes files of an earlier export it no longer writes. Warns of dead links and #ids (seo-link, seo-anchor) |
wisp build --static --allow-dead-links | a link to a missing page or to an #id that the linked page lacks only warns (also without --static, for the PRERENDER crawl) |
wisp build --no-crawl | the prerender and --static follow no link: only the routes and entries() say which pages are rendered, and no link is checked |
wisp build --spa [--out dist] | the same, and index.html draws the SSR = false pages |
wisp build --target extension [--out dist] | a Chrome extension folder (Manifest V3) from the static export and the app's manifest.json. With --static, --spa or another --target the error is --target extension goes alone, without --static, --spa or another --target. With --analyze it is --analyze goes alone. Only --analyze=html takes --out <file>. An inline script, an on* attribute or a javascript: URL in a page fails the build: N inline scripts, event handlers or javascript: URLs in the pages. Move the code to a .js file under static/. See Browser Extension |
wisp build --target|-t <host> [--edge] [--out|-o <dir>] | a folder for cloudflare, pages, deno, vercel, netlify, node, bun or lambda. --edge uses edge functions on vercel or netlify |
wisp client [-o|--out client.ts] | a typed TypeScript client of the +server.rs endpoints |
wisp openapi [-o|--out openapi.json] | print or write the OpenAPI 3.1 document |
wisp openapi --check | fail if the committed file is stale (CI) |
wisp check [--types] [--rust] [--target <host> [--edge]] [--explain-imports] | check routes and templates without compiling, and lint them (accessibility, SEO, CSS and JavaScript: see /docs/design-pages). The lint levels are in [package.metadata.wisp.lint] (see /docs/config). --types runs tsc (without TypeScript it prints Wisp SKIPPED type checking. A skip is not a pass. Wisp checked nothing. and the cause; set WISP_TSC). --rust runs cargo clippy, or cargo check with a note when clippy is not installed. --target <host> warns of what that host cannot run. --explain-imports lists names used with no use line. --fix makes the safe fixes and --fix --dry-run only counts them and fails if one is left. A fix keeps the mode of the file, and it fails for a file when the file system cannot set that mode. --fix --dry-run with --rust, --types, --target or --explain-imports is an error. --rules lists every lint with its level. Syntax errors in scripts show file:line:col |
wisp test [--browser] [args] | cargo test with its args. --browser adds browser tests |
wisp test --coverage [args] | Runs the tests with cargo llvm-cov. Maps the counts to .wisp lines. Writes target/wisp-coverage.lcov. See Testing |
wisp test --e2e [--fast] [args] | Builds the app, starts it on a free port, runs npx playwright test with WISP_URL. --fast builds quicker |
wisp test --e2e --init | Writes playwright.config.ts and e2e/home.spec.ts |
wisp fmt [paths] | format .wisp files |
wisp fmt --check | name unformatted files and fail |
wisp fmt --stdin [path] | format stdin to stdout, for editors |
wisp package [args] | in a component library: check it, then cargo package |
wisp route add <path> [kind] | write a route: page (default), form, layout, server, rest (or api) or crud. The file is written as wisp fmt leaves it. A folder that the route scanner skips is refused with its reason: a name that ends in .bak, .tmp or .orig, a name that starts with a dot (.well-known is a route and is written), and a Windows device name such as con. A path that matches the same URLs as an existing route (/[[opt]] beside /) is refused and nothing is written. So is a rest route whose path has an id parameter (/x/[id]): a rest route serves its own /[id] |
wisp route add <path> crud | list, new and edit forms for a table, with its #[model] and Table::saved() in src/db.rs (added unless the file declares a type of that name: a comment or string with the name does not count). If its routes match the URLs of another route, or a file write fails, it writes nothing and deletes what it made. A model that would take the name of a type the file uses (/tables is Table, /strings is String) gets Row added: TableRow |
wisp route list | each route's methods, URL and file |
wisp component add <Name> | a blank src/components/Name.wisp |
wisp component list | the components with file and props |
wisp deploy init <host> [--force] | a GitHub Actions workflow that deploys on push. It installs wisp at the release tag that the app pins. It runs wrangler, vercel and netlify-cli at exact versions. Each wisp release sets them. Actions use tags: pin each uses: to a commit SHA for a stricter build |
wisp deploy init fly|render|railway|cloud-run [--force] | that host's config and a Dockerfile, with a health check on /_wisp/health, a kill timeout past the drain (Fly and Railway), the host's client IP header where it is safe, and saved tables on one instance |
wisp deploy init docker [--onion] [--force] | a Dockerfile and .dockerignore. --onion adds Tor files for a Tor onion service. The deploy init commands refuse a file that is a symbolic link, and write nothing then |
wisp deploy init tor [--unix] [--force] | write deploy/tor/torrc (lines for /etc/tor/torrc: HiddenServiceDir /var/lib/tor/<app>/, HiddenServicePort 80 127.0.0.1:3000, and the Tor DoS options as comments) and deploy/tor/<app>.env (HOST=127.0.0.1, WISP_ONION=on) for tor and wisp service install, with no container. --unix makes Tor connect to the socket /run/<app>/app.sock: torrc has HiddenServicePort 80 unix:/run/<app>/app.sock, the env file has WISP_LISTEN=unix:/run/<app>/app.sock in place of HOST and PORT, and deploy/tor/<app>-unix.conf is a systemd drop-in. A WebSocket route does not work with --unix. Only tor takes the flag (Tor onion service) |
wisp npm add <pkg>[@version] | add an NPM package to package.json, no Node needed. wisp build pins each downloaded file by SHA-256 in npm.lock |
wisp npm remove <pkg> | remove one |
wisp npm list | the app's NPM packages and versions |
wisp recipe add <name> [--force] | apply the recipe add/<name>/recipe |
wisp recipe list | the recipes in add/ |
wisp ui add <name…> [--force] | copy components (button, dialog, tabs…) into src/components |
wisp ui list | the components wisp ui add has |
wisp service install|uninstall|start|stop|status | run the release binary as a systemd unit, launchd daemon or Windows scheduled task. Options: --name, --user or --root (install needs one), --port, --dry-run. install on an installed service upgrades it: the new build runs after it. On Windows the task command must be 261 characters or fewer. status exits 1 with not installed when there is no service (Linux: not running for a stopped unit) |
wisp host [path|name] [--yes|-y] [--dry-run] | set up an app on this machine and keep it running. As an administrator it never builds. On Linux and macOS, a user who is not root asks and builds, then it runs itself under sudo. It reads the machine, asks for each choice that no option gives, and picks the lightest setup. A name in the list updates that app. Else the value is the app folder (default: the current folder). Options: --name <s>, --domain <d> or --no-domain, --port <n>, --method native|docker, --proxy caddy|none, --user <u> or --root, --install-deps (installs only Caddy). --dry-run shows the steps and changes nothing (Wisp Host) |
wisp host help | the rows of wisp host (also --help, -h) |
wisp host list | each app in the list (hosts.tsv, WISP_HOME) with its method, port, domain, state and path |
wisp host info | the facts that it reads about this machine and the setup that it picks. It changes nothing |
wisp host status|start|stop|restart <name> | show the state of an app in the list, or start, stop or restart it |
wisp host logs <name> [-n <lines>] | the last lines of the log of the app (100) |
wisp host update <name> [--dry-run] | start a new build of the app. An administrator uses the build that exists. Another user runs wisp build. The setup stays. It writes a missing Caddy block again and keeps an existing one |
wisp host delete <name> [--yes] [--purge] [--dry-run] | delete the setup of the app and its line in the list. The app folder stays. --purge also deletes the host folder (only with its .wisp-host file) and the data of the setup. --yes asks nothing |
wisp lsp | the language server, over stdio. A bad header or Content-Length gets a JSON-RPC error (-32700). The server then reads on from the next Content-Length |
| CLI downloads | curl stops at 512 MiB for a file and 64 MiB for a body in memory. It checks the size against Content-Length: a response with no length is not capped |
wisp update-docs | update AGENTS.md and wisp-ref/ to this Wisp |
wisp upgrade [--check | --undo | --force-undo] | install the newest release and, in an app, bump its Wisp dependencies to it (see Updating) |
wisp changelog [version | --since <version>] | print what changed from the installed version to the newest, one version, or everything after one (see Updating; the same text is /changelog) |
wisp mcp | docs, routes, components and checks for AI agents (MCP, stdio) |
wisp --help | the commands by group (-h). wisp help <command> [verb] lists one command's rows |
wisp --version | the version (-V) |
Options for Wisp New
| Option | What it does |
|---|---|
-t, --template demo|minimal|api|extension | a demo app, one empty page, a JSON API (also --api), or a Chrome extension. The extension has a popup, an options page and a background worker (Browser Extension) |
--tailwind, --no-tailwind | add Tailwind CSS, or not |
--ts, --no-ts | TypeScript only (script = "ts"). On by default. In wisp dev a violation is a warning |
--strict, --no-strict | warnings are build errors (strict = true). In wisp dev they are warnings, so a pasted docs example runs. On by default |
--typecheck, --no-typecheck | wisp build and wisp check run tsc (typecheck = true). Off by default |
--git, --no-git | create a git repository, or not |
--install, --no-install | compile dependencies now, or on the first wisp dev |
-y, --yes | use the default for each option not given |
--lib | a component library, not an app. It asks nothing |
Only --template takes a value (--template=minimal). The other options take no value. --git=false is an error: write --no-git.
An app also gets a rust-toolchain.toml that pins the Rust version of the Docker image (wisp deploy init docker). Local builds and the image then use one compiler. See Reproducible builds. An option given both ways (--ts --no-ts) is an error. The folder name is the package name, so it takes ASCII letters and digits only: über is refused.
Updating
wisp upgrade installs the newest release (cargo install --git https://wisp.ar0.eu/ --tag <tag> wisp-web --force). The git tag of the release is the trust anchor: cargo gets the source at that tag and builds it. In an app folder it also sets tag = "<tag>" on the Wisp git dependencies in Cargo.toml, runs cargo update for wisp-web-rt, wisp-web-build, wisp-web-macros and wisp-web-shared, then runs wisp check and wisp update-docs with the new CLI. It reports each step.
The app upgrade is all or nothing. Before it changes a file, wisp upgrade copies Cargo.toml, Cargo.lock, AGENTS.md, the files of wisp-ref/ and .github/workflows/deploy.yml (when it exists) to target/wisp-upgrade. The upgrade sets the --tag of the cargo install wisp-web line in that workflow to the new release. First it checks that the installed CLI shows the new version, and stops with no change when it does not. When a step fails, it puts the copies back and says so. When wisp check fails, fix the check errors, then run wisp upgrade again. After a good upgrade, wisp upgrade --undo puts back the files of the last upgrade and deletes the copies. It refuses when Cargo.toml, Cargo.lock, AGENTS.md, the files of wisp-ref/ or the workflow changed after the upgrade, as the undo would lose that change. It names each such file. It also refuses when the upgrade stopped before the bump finished and left no stamp. wisp upgrade --force-undo undoes all the same. The undo never deletes a workflow that did not exist at the upgrade. The copies are under target/, so cargo clean deletes them. The CLI stays at the new release: to get the old one back, run the install command with the old --tag.
wisp upgrade --check only reports. It exits 1 when a newer release is out, so CI can use it. WISP_RELEASES_URL sets the release list URL, an https URL (default: the Forgejo API at code.wispweb.dev). The answer must have the Forgejo or GitHub releases JSON shape. wisp new pins a new app to the tag of the CLI that made it, so an update is always a change you make.
wisp dev, wisp build and wisp new look up the newest release at most once a day (the Forgejo API of the repository, prereleases included; the answer is cached in the user cache folder as wisp/latest-release). They print one line on stderr when the CLI, or the wisp-web-rt version in the app's Cargo.lock (a git dependency; a path dependency on a Wisp checkout is never flagged), is older than that release:
! wisp 1.0.0-pre.2 is out of date: 1.0.0-pre.3 is out. Run wisp upgrade.
- security 1.0.0-pre.3: Signed cookies under WISP_BASE keep their name and base path
- 1.0.0-pre.3: Brotli for assets and baked pages, assets from other sites by URL
Changes: https://wispweb.dev/changelog/?v=1.0.0-pre.2
Under the line it lists at most five lines on what changed between the CLI and the newest release, taken from the release notes (the section of CHANGELOG.md that the release carries): the first lines of each Security section, then the summary of each newer version. The notes are cached with the answer. When they cannot be read the notice is the one line. wisp upgrade prints the same lines before it installs, and wisp changelog --since 1.0.0-pre.2 prints every entry after that version. wisp changelog alone prints the installed version and everything newer; wisp changelog 1.0.0-pre.2 prints one version. Versions up to the installed one come from the CHANGELOG.md built into the CLI, so they work offline; newer ones are read from the releases at code.wispweb.dev, and without a network the command says so and shows what it has. The link opens the changelog page with your version marked.
The lookup runs on a background thread with a 3 second limit. A command never waits for it, and the server and the built app never run it. It is off when offline, when CI is set, and with WISP_NO_UPDATE_CHECK=1. On Windows wisp upgrade builds the new CLI in a temporary folder first. Then it renames the running wisp.exe to wisp-old.exe and puts the new file in its place. It moves the running file only when that file is the installed CLI. A Ctrl-C during the build leaves the old wisp.exe. If the last rename fails, the old file goes back.
CLI Older Than the App
App commands warn on stderr when the installed wisp is older than the app's wisp crate, and ask before continuing in a terminal. WISP_NO_UPDATE_CHECK=1 turns the warning off. More: CLI, dev loop and security.
Is This Page Useful?