CLI

The jaunt entry point is jaunt.cli:main. Commands are grouped below by the job they do: authoring specs, building, testing, contract mode, the daemon, and project maintenance. New to Jaunt? Start with Quickstart instead.

Every generation command runs through the Codex engine and needs the codex CLI installed and authenticated (codex login). See Codex Engine.

Common flags

These apply to every generation command (build, test, status, check, watch, tree, specs, adopt, reconcile, eject). Per-command sections below list only the flags unique to that command.

Authoring

jaunt init

Scaffold a jaunt.toml, source/test directories, and a starter spec. The TypeScript starter intentionally leaves package metadata to the package manager; when no package.json exists, follow its printed npm init command before installing tools.

jaunt init
jaunt init --root /tmp/myproj
jaunt init --force
jaunt init --language ts

init takes no other common flags.

jaunt specs

List magic specs and the dependency graph between them.

jaunt specs
jaunt specs --module my_app.specs

Specs registered by a magic_module(__name__) call are marked [module]; decorated specs carry no marker. When a spec's effective kwargs are non-empty (a per-symbol option, or a module default it inherited), they print after the marker:

- mail:parse_email (mail.py) [module] kwargs={'prompt': 'All parsers are RFC 5322 strict.'}

Module-origin specs that have never been built print with a [newly governed — first build] marker, so the first build a magic_module scan commissions is never a surprise.

For a TypeScript target, specs is static: the Node worker parses private *.jaunt.ts[x] inputs without executing them and reports ts: module and symbol IDs.

jaunt instructions

Print a project-aware agent primer: the authoring modes, the build/test loop, the command and exit-code reference, then a live snapshot of the current project (resolved [paths], engine/model, semantic-gate and repo-map settings, which modules are stale). Run before an initialized project exists, it prints the framework rules plus the full jaunt.toml schema and a note to run jaunt init.

jaunt instructions
jaunt instructions --json

--json emits {command, ok, text, project}, where project is the structured snapshot (or null with no jaunt.toml).

Building

jaunt migrate --config-v2

Preview or apply the deterministic version-1 to version-2 configuration rewrite:

jaunt migrate --config-v2
jaunt migrate --config-v2 --apply

The action moves Python-specific settings under [target.py], verifies that the loaded Python compatibility view is unchanged, and makes no model call. It is separate from --merge-projects.

jaunt sync

Render TypeScript API mirrors, missing canonical facades, and typed unbuilt placeholders without calling a model:

jaunt sync
jaunt sync --target ts:src/tokens/index

The owner project must typecheck before the artifacts are committed. Existing custom facades are never overwritten. Sync may refresh the deterministic API mirror and its sidecar hash bookkeeping, but it never rewrites a built implementation's body or advances its provenance to a changed contract. Semantic and fingerprint re-stamps belong to build; compatible alpha artifact repairs belong to migrate --language ts. A synchronized placeholder keeps the editor green but remains unbuilt in status and check.

jaunt design

Ask Codex to propose the declaration and TSDoc for one @jauntDesign contract:

jaunt design --target ts:src/store/index#TokenStore
jaunt design --target ts:src/store/index#TokenStore --apply

The default prints a patch, leaves the spec unchanged, and records the exact proposal under .jaunt/. --apply requires that proposal, makes no model call, checks the source digest and dirty-tree policy, confines the patch to the marked declaration, and validates it before writing.

jaunt build

Generate implementation modules for @jaunt.magic specs. Stale dependents of a changed upstream API are rebuilt too.

jaunt build
jaunt build --force
jaunt build --target my_app.specs
jaunt build --jobs 16
jaunt build --language ts --target ts:src/tokens/index

--json reports generated, skipped, refrozen, failed, cost, and context_stats, plus needs_deps, emitted_stubs, and advisories when present — see JSON Output. The context_stats seeded-skills block is keyed skills_workspace_seeded (with the legacy skills_workspace alias for this release). The build plan flags any module-origin spec with no artifact yet as newly governed by module scan before generation starts.

jaunt watch

Watch source and test roots and rebuild on relevant Python or TypeScript changes. For [target.ts], Jaunt also watches the configured projects, package manifests, lockfiles, and Vitest config while excluding generated output.

jaunt watch
jaunt watch --test

Accepts the build-shaping flags (--instruction, --include-target-tests, --no-auto-skills, --no-builtin-skills) plus --test (run tests after each successful build). With --json, watch emits one envelope per rebuild cycle, not nested build/test documents.

jaunt status

Show which modules are stale or fresh, using the same dependency-driven freshness model as build (including modules invalidated by an upstream API change).

jaunt status
jaunt status --magic-only

A module the next build resolves through the free re-stamp path reads stale (re-stamp: free) rather than stale (structural); when that module also carries legacy raise RuntimeError("spec stub") bodies, status hints jaunt migrate. Orphaned artifacts (a generated file whose spec is gone) list in their own section, reported under "orphans" in --json.

jaunt clean

Remove target-owned generated artifacts under the configured roots. Python removes __generated__ directories and header-marked .pyi stubs. TypeScript removes owned implementations, API mirrors, sidecars, and generated magic-test batteries while preserving private specs, public facades, and contract batteries.

jaunt clean
jaunt clean --dry-run
jaunt clean --orphans

Plain jaunt clean wipes every generated directory and stub. --orphans narrows the sweep to artifacts whose spec no longer exists: the generated module, its .contract.json sidecar, its .pyi, and its generated tests or contract battery. It leaves fresh, still-governed output alone, and writes one orphan removed line to the journal per deletion. Combine with --dry-run to preview without deleting or journaling.

Testing

jaunt test

Generate held-out batteries, then run the target's protected test runner on only the generated files. Python uses pytest; TypeScript uses project-local Vitest.

jaunt test
jaunt test --no-build
jaunt test --no-run
jaunt test --pytest-args=-k --pytest-args email
jaunt test --language ts --target ts:src/tokens/index

Generated tests split into a held-out set: Python cases use @pytest.mark.jaunt_tier("example" | "derived"); TypeScript batteries carry the same tier in protected reporter metadata. When a test fails and Jaunt regenerates the implementation, derived failures are redacted to a semantic case id and category so the implementation generator never sees the value, file, timing, or diagnostic location it could otherwise game; example failures keep authored evidence. --no-redact-derived disables that barrier and logs a warning — a debugging escape hatch only.

Fresh TypeScript batteries skip generation but still typecheck and run. Changes only to the protected runner or Vitest fingerprint deterministically reheader the unchanged battery and appear under refrozen; content-affecting drift and --force regenerate it.

Contract mode

Adopt committed code under docstring/TSDoc contracts and keep a derived pytest or Vitest battery in sync. See the Contract Mode guide and TypeScript target guide.

jaunt adopt

Add the target-language contract marker and derive its battery.

jaunt adopt my_app.slug:slugify
jaunt adopt src/slug.ts#slugify --language ts

Takes a positional Python module:func or TypeScript path.ts#symbol ref plus the common flags. Python adopts whole classes; TypeScript supports committed exported functions and concrete classes described in the TypeScript guide.

jaunt reconcile

Derive or refresh committed contract batteries. This is the only contract command that calls the model.

jaunt reconcile
jaunt reconcile --language ts

jaunt check

The single deterministic CI gate for both modes — no model, no API key. It verifies committed contract batteries and Python/TypeScript magic freshness, exiting 4 on any blocking drift: a contract that is unbuilt, stale-prose, signature-drift, or behavior-drift; or a magic module that is unbuilt or stale (including a missing or stale Python .pyi stub). TypeScript invalid-artifact diagnostics and unbuilt private spec modules block the same gate.

jaunt check
jaunt check --contracts-only
jaunt check --magic-only

check also blocks on orphaned artifacts. A generated module, .pyi, or contract battery whose spec no longer exists exits 4 with a message naming the fix — jaunt clean --orphans, or restore the spec. A mid-refactor rename shows one orphan and one newly-governed spec and holds CI red until you rebuild, which is intentional.

--contracts-only and --magic-only are mutually exclusive. --json reports a magic block (fresh / stale / unbuilt, plus generated/stub/sidecar orphans) and a top-level orphans key for contract-battery orphans; see JSON Output. A project with no magic specs and no contract drift exits 0.

jaunt eject

Remove contract tracking; leave ordinary Python/pytest or TypeScript/Vitest code.

jaunt eject my_app.slug:slugify
jaunt eject src/slug.ts#slugify --language ts
jaunt eject ts:src/slug/index --language ts
jaunt eject --all

Daemon

Background codegen from committed spec changes. See the Background Daemon guide.

jaunt daemon

jaunt daemon start     # foreground; Ctrl-C to stop
jaunt daemon status
jaunt daemon stop

start and status accept --root and --json; stop accepts --root.

jaunt jobs

Inspect job records and the pending-rebuild preview, and land or discard parked proposals.

jaunt jobs
jaunt jobs show <id> --full
jaunt jobs retry <id>
jaunt jobs land <id>
jaunt jobs land --all
jaunt jobs discard <id>
jaunt jobs wait --timeout 1800

Under the default propose-only mode ([daemon] auto_commit = false), green jobs are parked as proposals rather than committed:

• jaunt jobs land <id> lands one proposal. It re-validates first: a stale spec digest, a mismatched branch, dirty target paths, or a 3-way apply conflict all refuse the land (exit 4); a stale digest or apply conflict also marks the proposal SUPERSEDED. jaunt jobs land has no --force; use jaunt jobs retry <id> --force to land despite a changed spec.
• jaunt jobs land --all lands every fresh proposal in job-creation order, prints per-job outcomes, and exits 0 only when every attempted land succeeded, else 4.
• jaunt jobs discard <id> drops a proposal and its patch artifact.

jaunt jobs wait blocks until the target job finishes, or (without an id) until the daemon is idle. A parked proposal (PROPOSED) counts as terminal-green, so wait returns 0 on it. --settle N sets the idle race-guard window; --timeout N exits 5 on timeout. Bad ids or wrong-state jobs exit 2.

jaunt log

Tail the JAUNT_LOG change journal that build, test, and daemon runs append to.

jaunt log
jaunt log -n 50          # 0 = all lines
jaunt log --module my_app.specs

jaunt guard

A PreToolUse hook for coding agents that reads a hook payload on stdin and warns when a tool call is about to touch files under the generated dir. See docs/hooks.md in the repo for Claude Code wiring.

jaunt guard
jaunt guard --generated-dir __generated__

jaunt install-codex-plugin

Install Jaunt's first-party Codex plugin from the GitHub marketplace, or from a local clone for development.

jaunt install-codex-plugin
jaunt install-codex-plugin --local --root /path/to/jaunt
jaunt install-codex-plugin --json

jaunt install-claude-plugin

Install Jaunt's first-party Claude Code plugin with the matching GitHub or local marketplace flow.

jaunt install-claude-plugin
jaunt install-claude-plugin --local --root /path/to/jaunt
jaunt install-claude-plugin --json

Both installers are idempotent and use a 120-second timeout per CLI command.

Maintenance

jaunt tree

Maintain treedocs.yaml, the one-line-per-path repo map injected into build prompts. See Repo Context.

jaunt tree             # sync (AST-only descriptions by default)
jaunt tree --check     # CI gate: exit 4 if the tree is stale
jaunt tree --enrich    # force LLM enrichment this run

jaunt cache

Inspect or clear the LLM response cache under .jaunt/.

jaunt cache info
jaunt cache clear

Both accept --root, --config, and --json.

jaunt skill

Manage project-local skills under .agents/skills/.

jaunt skill list
jaunt skill show rich
jaunt skill add rich --description "Rich usage notes" --lib rich
jaunt skill remove rich -f
jaunt skill import --from /path/to/skills-dir
jaunt skill refresh
jaunt skill build rich

Two subcommands generate content through the Codex engine: skill build <name> expands a user-managed checked-in skill (it must already exist with --lib metadata, usually from skill add <name> --lib <package>), and skill refresh regenerates Jaunt-managed auto skills. Both drive codex exec under the hood.

jaunt migrate

Plan or apply mechanical migrations. The default is always a dry run: jaunt migrate prints what it would change and exits 0, while jaunt migrate --apply writes the validated plan. Neither mode calls the model.

jaunt migrate
jaunt migrate --apply
jaunt migrate --apply --allow-newly-governed
jaunt migrate --language ts
jaunt migrate --language ts --apply

For Python targets, the command handles two source and stub migrations:

• Legacy stub bodies. A raise RuntimeError("spec stub") body — the form the old scaffold emitted — is rewritten to ..., and the generated header is re-stamped over the untouched body, so the conversion is free. For a symbol that is already a spec this is a re-stamp. For a currently ungoverned function in a magic_module file, rewriting its body would newly govern it and commission a first build, so migrate lists it as would newly govern and skips it unless you pass --allow-newly-governed.
• Stub re-emission. When a committed .pyi is stale only because _STUB_FORMAT_VERSION bumped in a past release, migrate --apply re-renders it without a build. This retires the 1.4.2 wart where jaunt check reported stubs stale until you ran jaunt build once.

For a TypeScript-only version-2 root, plain jaunt migrate selects TypeScript. Use --language ts explicitly in a mixed Python/TypeScript root. The worker analyzes the current project and proposes only deterministic artifact work:

• create or repair the API mirror, canonical facade, typed unbuilt placeholder, and sidecar;
• re-stamp a compatible built implementation when only its tool fingerprint or deterministic artifacts are stale;
• report model-rebuild when the contract changed or an alpha protocol, IR, or route is incompatible.

The TypeScript migration records exact input hashes and commits its complete write set through the recoverable artifact transaction. An apply refuses a stale plan or dirty worktree unless --force is present. Preview-era private specs, facades, or loader layouts that do not map unambiguously to the current route are reported as manual-intervention; Jaunt does not rename or rewrite them.

Every applied change is printed file by file. After an apply on a legacy-body project, jaunt status reports the module fresh with no model call.

jaunt eval

Exit codes

Next: Configuration.