@pracht/cli

Command-line tool for developing, building, validating, and scaffolding pracht apps.

Install

npm install @pracht/cli

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          # per-route client JS report (gzip + raw)
pracht build --json             # same report as JSON (agent-friendly)
pracht build --no-budget-fail   # report exceeded budgets without failing

--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                       # diff against origin/main
pracht plan --base main
pracht plan --markdown            # fenced diff for PR comments
pracht plan --json                # full structured payload
pracht plan --write               # refresh .pracht/app-graph.json (commit it)

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. See docs/MCP.md for client registration and the tool reference.

pracht dev-mcp