@pracht/cli
Command-line tool for developing, building, validating, and scaffolding pracht apps.
Install
Commands
pracht dev
Start the local development server with SSR and HMR.
pracht dev
pracht dev --port 4000
pracht dev --cache-dir /tmp/pracht-vite-cache
--cache-dir overrides Vite's node_modules/.vite cache. Give concurrent dev
servers separate directories when they run against the same project checkout.
pracht build
Create a production build with client/server output and SSG/ISG prerendering.
pracht build
pracht build --analyze
pracht build --json
pracht build --no-budget-fail
--analyze prints, per route (pattern + render mode), the transitive client
chunks it loads with raw and gzip sizes, a total row, and the shared entry
chunks broken out. Output respects NO_COLOR.
When the pracht plugin config declares budgets (e.g.
budgets: { "*": "120kb", "/dashboard": "200kb" }), every build evaluates the
per-route gzip client-JS ceilings, writes dist/server/budget-report.json, and
exits non-zero on exceeded budgets unless --no-budget-fail is passed. See
docs/PERFORMANCE.md.
For Node.js targets, run the built server with:
node dist/server/server.js
pracht preview
Serve the production build locally. Runs pracht build first (skip with
--skip-build), then serves the output for the configured adapter:
- Node: runs
dist/server/server.js on --port (or $PORT, default 3000).
- Cloudflare: delegates to
wrangler dev against the built worker; requires
wrangler in node_modules or on your PATH plus a wrangler config.
- Vercel: there is no faithful local production runtime — the command points
you at
vercel build / vercel dev instead.
pracht preview
pracht preview --port 4000
pracht preview --skip-build
pracht verify
Run fast framework-aware verification checks without paying for a full build or
test loop. Use --changed to focus on changed manifest-managed files and
--json for machine-readable output. When dist/server/budget-report.json
exists (written by pracht build when budgets are configured), the last
build's client JS budget results are surfaced as checks.
When the app declares defineApp({ constraints }) or commits a
.pracht/app-graph.json snapshot, verification also resolves the live app
graph, enforces every constraint, and fails if the snapshot is stale (fix with
pracht plan --write).
pracht verify
pracht verify --changed
pracht verify --json
Use the browser-backed subcommand for routes that expose WebMCP page tools:
pracht verify webmcp --url http://localhost:3000
pracht verify webmcp --start "pracht preview" --json
It launches an installed Chrome 150+ build with WebMCP testing enabled,
compares the native route-scoped tool registry with the resolved app graph,
and verifies navigation cleanup. Framework-owned pracht_* development tools
are excluded from app-graph parity. Pracht never downloads an unpinned browser;
pass --browser /path/to/chrome in CI. --scenario accepts explicit safe WebMCP
eval files when invocation/cancellation proof should join the report.
pracht eval
Run scripted capability scenarios over HTTP (default), remote MCP
("transport": "mcp"), or native WebMCP ("transport": "webmcp" plus
"webmcpRoute"). A WebMCP step can set cancelAfterMs to prove host
cancellation reaches the dispatch path.
pracht eval --start "pracht preview"
pracht eval evals/notes-webmcp.eval.json --browser /path/to/chrome --json
pracht plan
Semantic app-graph diff against a base git ref. Reads the
.pracht/app-graph.json snapshot committed at the base ref (a route-graph
lockfile), resolves the live graph, and prints the routes, API endpoints, and
constraints that were added, removed, or changed — an intent-level changelog
for reviewers. Per-route gzip sizes are annotated when the last build wrote a
budget report.
pracht plan
pracht plan --base main
pracht plan --markdown
pracht plan --json
pracht plan --write
pracht report
Assemble a PR-ready markdown report from machine truth: the pracht plan
diff, pracht verify results, and the last build's client JS budget table.
Use it as the factual half of a PR description.
pracht report
pracht report --base main --out pr-report.md
pracht llms
Print the embedded pracht authoring guide for coding agents (project layout,
conventions, the verify → plan → report loop). --write saves it as
llms.txt in the app root so agents pick it up automatically.
pracht llms
pracht llms --write
pracht docs
Read the pracht docs that ship inside this package, so they match the installed
version and work offline. With no topic it lists the pages; a topic prints one
as Markdown (slug#section prints one section); --search finds sections.
The files are also in node_modules/@pracht/cli/docs/.
pracht docs
pracht docs routing
pracht docs --search "loader revalidate"
pracht generate route
Create a new route module. In manifest apps this also updates src/routes.ts.
When the app has a Playwright setup (playwright.config.* or an e2e/
directory), a smoke test is emitted at e2e/<route-id>.spec.ts as well —
--no-test skips it, --test forces it. Generated tests import
@playwright/test; when that dependency is absent, the command prints an
install follow-up (for example, pnpm add -D @playwright/test).
pracht generate route --path /dashboard --render ssr --shell app --middleware auth
pracht generate route --path /blog/:slug --render ssg --no-test
pracht generate shell
Create a shell module and register it in the app manifest.
pracht generate shell --name app
pracht generate middleware
Create a middleware module and register it in the app manifest.
pracht generate middleware --name auth
pracht generate api
Create an API route under src/api/.
pracht generate api --path /health --methods GET,POST
pracht inspect
Inspect the resolved app graph. Use --json for agent/tool consumption.
pracht inspect --json
pracht inspect routes --json
pracht inspect api --json
pracht inspect capabilities --json
pracht inspect agents --json
pracht inspect build --json
pracht inspect agents summarizes the configured agent surface: Web Bot Auth
policy and keys, the destructive-confirmation mode, the remote MCP endpoint,
whether llms.txt is generated, and which capabilities are exposed on which
transports. The llms.txt state comes from the resolved production server-build
configuration, including build- or production-only options. If an older
installed @pracht/vite-plugin cannot expose that state, JSON reports null and
text reports unknown rather than treating missing metadata as disabled. The
JSON report also includes mcpEndpoint, mcpDestructive, mcpRuntimeStatus,
and mcpUnavailableReasons; text marks declarations mcp(unserved) or
mcp(unverified) when inspection cannot confirm that the tool is reachable.
pracht typegen
Generate src/pracht.d.ts and src/pracht-routes.ts from the resolved
route graph for typed <Link>, route-object useNavigate(), and href()
helpers, plus typed API route registrations for apiFetch(). API modules are
not executed during generation. Use --check in CI to fail when generated
files are stale. After the first generation, pracht dev keeps the default
outputs current; before it, the dev banner prints a one-line setup tip.
pracht typegen
pracht typegen --check
pracht doctor
Validate the local app wiring across the whole project. Use --json for
machine-readable output.
pracht doctor
pracht doctor --json
pracht dev-mcp
Start a Model Context Protocol server on stdio that exposes inspect, doctor,
verify, plan, report, generate, the authoring guide, and the bundled docs
(get_docs, list_docs, search_docs) as native tools for coding agents.
get_runtime_diagnostics({ url }) reads recent server request errors and
capability traffic from the app's running loopback dev server without a WebMCP
browser. See
docs/MCP.md
for client registration and the tool reference.