CLI
pracht commands for development, builds, previews, inspection, verification, evals, scaffolding, offline docs, and agent setup.
On this page
Installation
Scaffolded projects include the CLI. In an existing project, add it as a dev dependency:
pnpm add -D @pracht/clinpm install -D @pracht/cliyarn add -D @pracht/clibun add --dev @pracht/cliThen add scripts to your package.json:
{
"scripts": {
"dev": "pracht dev",
"build": "pracht build",
"doctor": "pracht doctor"
}
}The CLI needs Node 22.18 or newer and exits with a one-line message on an older version. pracht --version prints the installed version.
create-pracht
Create a new app, interactively or non-interactively for agents and CI:
# Interactive
pnpm create pracht my-app
# Non-interactive manifest app for Node.js
pnpm create pracht my-app --adapter=node --router=manifest --yes
# Pages router, Cloudflare adapter, no install step
pnpm create pracht my-app --adapter=cf --router=pages --skip-install --yes
# Tailwind starter for Vercel
pnpm create pracht my-app --adapter=vercel --template=tailwind --yes# Interactive
npm create pracht@latest my-app
# Non-interactive manifest app for Node.js
npm create pracht@latest my-app -- --adapter=node --router=manifest --yes
# Pages router, Cloudflare adapter, no install step
npm create pracht@latest my-app -- --adapter=cf --router=pages --skip-install --yes
# Tailwind starter for Vercel
npm create pracht@latest my-app -- --adapter=vercel --template=tailwind --yes# Interactive
yarn create pracht my-app
# Non-interactive manifest app for Node.js
yarn create pracht my-app --adapter=node --router=manifest --yes
# Pages router, Cloudflare adapter, no install step
yarn create pracht my-app --adapter=cf --router=pages --skip-install --yes
# Tailwind starter for Vercel
yarn create pracht my-app --adapter=vercel --template=tailwind --yes# Interactive
bunx create-pracht my-app
# Non-interactive manifest app for Node.js
bunx create-pracht my-app --adapter=node --router=manifest --yes
# Pages router, Cloudflare adapter, no install step
bunx create-pracht my-app --adapter=cf --router=pages --skip-install --yes
# Tailwind starter for Vercel
bunx create-pracht my-app --adapter=vercel --template=tailwind --yes| Flag | Effect |
|---|---|
--adapter=node|cf|netlify|vercel|static |
Node.js, Cloudflare Workers, Netlify, Vercel, or static output |
--router=manifest|pages |
Explicit src/routes.ts routing or file-system src/pages/ routing |
--template=minimal|tailwind, --tailwind, --no-tailwind |
Tailwind setup |
--agent-tools[=core|full], --no-agent-tools |
Seed or skip the pracht Claude Code skills, .mcp.json, and AGENTS.md/CLAUDE.md. core (the default) seeds four skills, full the whole catalog; add more later with pracht skills add |
--yes, -y |
Skip the prompts. Anything not passed defaults to a pracht-app directory, Node, manifest router, no Tailwind, and core agent tools |
--skip-install |
Write files without installing dependencies |
--no-git |
Skip git init and the initial commit |
--json |
Print a machine-readable summary |
--dry-run |
List files without writing them |
Every generated app has dev, build, typegen, and typecheck scripts. The dev and typecheck scripts generate route, API, and capability types before running. Node, static, Cloudflare, and Netlify starters add preview; Node starters add start; Cloudflare, Netlify, and Vercel starters add deploy.
pracht dev
Start the Vite dev server with SSR and HMR:
pracht dev
# Custom port (default: $PORT or 3000)
pracht dev --port 4000
# Isolate Vite's optimizer cache for concurrent dev servers
pracht dev --cache-dir /tmp/pracht-vite-cacheRoutes render on the server for each request, and changes to routes, shells, loaders, and components apply through HMR.
A failing loader, middleware, or render prints one terminal line (phase, route id, request path, and message) next to the browser error overlay. Failures that name none of your files also print their stack; set DEBUG to print it for every failure.
When several dev servers share one checkout, give each its own --cache-dir (default node_modules/.vite) so they do not race on Vite's optimizer cache.
The startup banner prints the resolved app graph: routes with render mode, shell, and middleware; API endpoints with methods; and capabilities with effect class, exposure, and dispatch path. Tables show their first 25 rows; pracht inspect routes lists the rest. The banner prints again after every routes.ts edit and server restart. When the graph cannot be resolved, for example because a route names an unknown shell, the banner shows the error and the number of routes in the manifest instead.
pracht build
Run a production build: client bundle, server bundle, and SSG/ISG prerendering.
pracht build
pracht build --analyze # per-route client JS report
pracht build --json # the same report as JSON (implies --analyze)
pracht build --no-budget-fail # warn instead of failing on an exceeded budget| Output | Contents |
|---|---|
dist/client/ |
Static assets with hashed filenames, plus prerendered SSG HTML |
dist/server/server.js |
Server entry module |
Run a Node build with node dist/server/server.js; other targets use their platform tooling (see Deployment). Set per-route client JS limits with budgets.
pracht preview
Build and serve the production target locally. --skip-build reuses the existing build:
pracht preview
pracht preview --port 4000
pracht preview --skip-build| Adapter | What runs |
|---|---|
| Node | dist/server/server.js with the host environment |
| Static | A static file server over dist/client/ |
| Cloudflare | wrangler dev against the config pracht build generates from your wrangler.jsonc. Needs Wrangler and that file; local Worker secrets go in a gitignored .dev.vars |
| Netlify, Vercel | Nothing: the command exits 1 and points you to netlify dev, or vercel build and vercel dev |
The command stays attached to the preview process and exits with its status.
pracht generate
Scaffold routes, shells, middleware, API routes, and capabilities:
pracht generate shell --name app
pracht generate middleware --name auth
pracht generate route --path /dashboard --render ssr --shell app --middleware auth
pracht generate api --path /health --methods GET,POST
pracht generate capability --name notes.search --expose http --description "Find notes matching a query."| Subcommand | Flags |
|---|---|
route |
--path (required), --render (ssr default, spa, ssg, isg), --shell, --middleware (comma-separated), --loader, --error-boundary, --static-paths, --title, --revalidate <seconds> (ISG only), --test / --no-test |
shell |
--name (required), --loader (adds a shell loader) |
middleware |
--name (required) |
api |
--path (required), --methods (comma-separated, default GET) |
capability |
--name (required, e.g. notes.search), --effect (read default, write, destructive), --expose (comma-separated http, webmcp, mcp; omit to keep it private), --title, --description (required with --expose) |
Every subcommand accepts --json for machine-readable output.
- Manifest apps register routes, shells, middleware, and capabilities in
src/routes.ts. - Pages-router apps get route files in
src/pages/. Capabilities are discovered fromsrc/capabilities/, so the module declares its ownname. - In pages mode,
generate middleware --name _middlewarescaffolds the rootsrc/pages/_middleware.ts, the only middleware seam; it needs a serverful adapter.generate shellis manifest-only; pages apps add an_app.tsxto the directory it should wrap.
generate route also writes a Playwright smoke test to e2e/<route-id>.spec.ts when the app has a Playwright setup. --test forces it and --no-test skips it. See Generated smoke tests.
pracht typegen
Generate typed declarations from the resolved app graph, so navigation, API calls, and capability calls are checked at compile time:
pracht typegen
pracht typegen --check # fail instead of writing when a file is stale (CI)| File | Contents | Override |
|---|---|---|
src/pracht.d.ts |
Route ids, params, loader data, and typed apiFetch() calls |
--out |
src/pracht-routes.ts |
The runtime href() helper |
--runtime-out |
src/pracht-capabilities.d.ts |
Each capability's input and output types, effect class, and exposure; written only when the app registers capabilities | --capabilities-out |
Add --json for machine-readable output.
--check compares declarations, not bytes, so reformatting the generated files never fails it, and regenerating leaves a correct file untouched.
New apps generate types during setup and before their dev and typecheck scripts run. In an existing app, run pracht typegen once to enable type generation. pracht dev then refreshes types when route files, the manifest, or an imported definition module change.
pracht doctor
Validate app wiring and report missing files or configuration drift:
pracht doctor
pracht doctor --jsonIt checks:
vite.config.*exists and registerspracht().- The app manifest or pages-router directory wiring.
- Referenced shell, middleware, and route modules.
- CLI and adapter package dependencies.
tsconfig.jsondoes not use amoduleResolutionthat predates packageexports("node","node10","classic"), which breaks@pracht/coreimports undertscwhile Vite still builds.
pracht inspect
Print the resolved app graph:
pracht inspect # all targets
pracht inspect routes
pracht inspect api
pracht inspect capabilities
pracht inspect agents
pracht inspect build
pracht inspect all --json| Target | Reports |
|---|---|
routes |
Page routes: render and hydration mode, shell, middleware, loader |
api |
API endpoints and their methods |
capabilities |
Capabilities: effect class, exposure, HTTP path, middleware, remote MCP status |
agents |
The agent surface: Web Bot Auth policy and keys, confirmation mode, remote MCP, llms.txt, and per-transport exposure counts. Flags capabilities that set expose.mcp while agents.mcp is unconfigured |
build |
Adapter, client entry, and CSS/JS manifests, including CSS for routes that ship no JavaScript. Run it after pracht build |
all |
Everything (the default) |
For remote MCP, the JSON output includes mcpEndpoint, mcpDestructive, mcpRuntimeStatus, and mcpUnavailableReasons. Text output marks an exposure mcp(unserved) when a requirement is missing and mcp(unverified) when inspection cannot confirm it. See Remote MCP.
Unknown targets and graph-loading errors exit non-zero. If a registered API or capability module fails to load, inspect, plan, verify, and the MCP inspection tools fail and name it rather than report partial metadata.
On Cloudflare, read bindings inside a handler or run(), never at module top level. Graph commands load your modules without real bindings, so a top-level binding read or Workers runtime-class construction fails with the API named. Importing env is fine. See Accessing Cloudflare bindings.
pracht plan
Diff the app graph against a base git ref. The output lists added, removed, and changed routes, API endpoints, capabilities, and constraints, for reviewers:
# Snapshot the resolved app graph to .pracht/app-graph.json (commit it)
pracht plan --write
# Diff the live graph against the snapshot committed at origin/main
pracht plan
# Custom base ref, machine-readable, or PR-comment output
pracht plan --base origin/release
pracht plan --json
pracht plan --markdownA ! marks a capability change that widens what agents can reach. pracht verify fails when the committed snapshot is stale; run pracht plan --write to refresh it. See the app-graph snapshot for the workflow.
pracht verify
Run deterministic checks over adapter wiring, route and API modules, capability contracts, declared constraints, environment safety, and app-graph snapshot freshness:
pracht verify
pracht verify --changed
pracht verify --json--changed narrows file-oriented checks to changed files for a fast local loop; run the full scope before committing. The command exits 1 when a blocking check fails. --json emits the checks, scope, and final ok value.
pracht verify webmcp
Check the page tools a live browser registers against the capability graph:
pracht verify webmcp --url http://localhost:3000
pracht verify webmcp --start "pracht preview" --json
pracht verify webmcp --start "pracht preview" --scenario evals/notes-webmcp.eval.jsonIt launches an installed Chrome 150+ with WebMCP testing enabled and visits each route that activates page tools. It exits 1 on startup failure, unsupported APIs, registration failure, or drift, including tools left behind after navigation. The dev-only pracht_* tools are ignored.
Add playwright-core as a dev dependency (npm install -D playwright-core). pracht never downloads a browser, so pin one in CI with --browser.
| Flag | Effect |
|---|---|
--url |
The running app (default http://localhost:3000) |
--start "<command>" |
Start the app, verify, then stop it, as in pracht eval |
--browser <path> |
Chrome or Chromium executable; auto-detected when omitted |
--timeout <ms> |
Browser, navigation, and startup timeout (default 10000) |
--scenario <files> |
Comma-separated WebMCP eval scenarios whose steps also run |
--json |
Machine-readable report |
pracht report
Assemble a PR-ready Markdown report from the pracht plan diff, pracht verify results, and per-route client JS budgets from the last build:
pracht report
pracht report --base origin/release --out report.md--base sets the git ref (default origin/main); --out writes to a file instead of stdout. See PR reports from machine truth.
pracht eval
Run scripted agent-task scenarios against a live app's agent surface. The command exits 1 when any scenario or expectation fails:
pracht eval # evals/**/*.eval.json
pracht eval evals/notes.eval.json
pracht eval --url http://localhost:3000
pracht eval --start "pracht preview" --url http://localhost:3000
pracht eval evals/notes-webmcp.eval.json --browser /pinned/path/to/chrome
pracht eval --json| Transport | Scenario setting | Calls |
|---|---|---|
| HTTP | default | The capability HTTP projection |
| MCP | "transport": "mcp" |
The app's remote MCP endpoint |
| WebMCP | "transport": "webmcp" and "webmcpRoute" |
The browser's page tools |
See pracht eval for the scenario format.
| Flag | Effect |
|---|---|
--url |
Overrides every scenario's own URL |
--start "<command>" |
Launch one server for the run, wait for it to answer, and stop it afterward |
--browser <path> |
Pin Chrome for WebMCP scenarios |
--json |
Report every scenario and step |
pracht preview works with --start for Node, Cloudflare, and static apps. Netlify and Vercel need a deployed URL or your own netlify dev or vercel dev.
pracht llms
Print the authoring guide for coding agents: project layout, conventions, constraints, and the verify/plan/report loop.
pracht llms
# Write the guide to llms.txt in the app root
pracht llms --write
# Write it somewhere else (implies --write)
pracht llms --out docs/pracht-guide.mdThis guide is for an agent editing your app. It is a different file from the llms.txt your deployed site serves, so use --out when the project also publishes one. The get_docs tool of pracht dev-mcp serves the same guide.
pracht docs
Print the pracht docs that ship inside your installed @pracht/cli, so you and your coding agent read the version the app uses, offline:
pracht docs # list pages by section
pracht docs routing # print a page as Markdown
pracht docs routing#route-manifest # print one section
pracht docs --search "loader revalidate"
pracht docs --json # the page list as JSONA topic is a page slug, its title, or its site path, such as recipes/auth. An unknown topic exits 1 and suggests close page names. --search takes one quoted query and returns slug#section targets with a snippet, best matches first. --json also works with a topic or --search.
Links between pages point at sibling files (routing.md#…), and the same files are in node_modules/@pracht/cli/docs/. The pracht dev-mcp tools get_docs, list_docs, and search_docs serve the same pages.
pracht dev-mcp
Start the authoring Model Context Protocol server over stdio for coding agents:
pracht dev-mcpIt gives the agent writing your code your app's graph: docs, inspection, doctor, verify, plan, report, typegen, eval, and generators. Register it as a local MCP server in your client rather than running it by hand; it runs until the client disconnects. pracht mcp is a deprecated alias that prints a notice to stderr.
This is not your app's own remote MCP endpoint, which serves your app's operations to end-user agents in production. See the authoring MCP server for client registration and the tool reference.
pracht skills
List and install the pracht Claude Code skills from the published agent-skills index:
# The catalog, with a marker on the ones this app already has
pracht skills list
# Install into .claude/skills/
pracht skills add audit-loaders add-dbcreate-pracht seeds four core skills; pracht skills add installs others. See Context cost for why the default set is small.
| Flag | Effect |
|---|---|
--force |
Reinstall a skill that is already installed, or write through a symlinked .claude/skills that stays inside the project |
--index <url> |
Use a different catalog (https, or http on localhost for an offline mirror) |
--json |
Machine-readable output; add --json reports installed, skipped, and failed |
add verifies every download against the index's SHA-256 digest and exits non-zero if any skill failed to install.