Trails CLI

Command-line tools for working with Trails projects.

Use the canonical Homebrew installation guide for installation, updates, and removal. The CLI requires Bun at runtime; use trails --version to check the installed release.

Use the CLI to scaffold a Trails app, add surfaces, inspect the current topo, run warden checks, manage draft state, and keep local Trails project state tidy.

These installation examples target Trails 0.2.1 on the normal npm release line.

bunx @ontrails/[email protected] create my-app --permit '{"id":"local-dev","scopes":["project:write"]}'
bunx @ontrails/[email protected] create my-app --workspace --permit '{"id":"local-dev","scopes":["project:write"]}'

Apps generated by the published 0.2.0 CLI need an explicit Node types dependency before typechecking. Follow the 0.2.0 scaffold repair.

Common workflows:

• trails create starts a standalone app by default; --workspace creates a configured workspace with that app under apps/<name>. Generated surfaces live under bin/, app source stays side-effect-free, and --dry-run returns the complete write plan without touching disk. Workspace creation rejects targets nested beneath an existing configured workspace while allowing a child workspace beneath an ancestor standalone Config. On a rerun, a preserved app entry also rejects when its runtime-selected topo ID can be statically proven to conflict with workspace.apps; dynamic, indirect, and post-construction mutation forms remain preserved and are validated by runtime commands such as trails compile.
• trails add surface adds another surface entrypoint to an existing project.
• trails topo inspects topo state and manages pins/history.
• trails compile writes the selected app's trails.lock. At a configured workspace root, pass --app <id>; compile never fans out or writes an aggregate root lock.
• trails validate checks the selected app, or validates every configured app when run at a workspace root without --app.
• trails wayfind, trails wayfind --trails --intent read, trails wayfind <id> --contract, trails wayfind <id> --deps, trails wayfind <id> --impact, trails wayfind pattern "wayfind.*", trails wayfind query "release drift", and trails wayfind diff ... read graph artifacts through Wayfinder. Pass --app <id> for one configured app. A workspace-root saved read returns a labeled app-partitioned view and may be partial; workspace diff requires complete views on both roots. trails wayfind file <file> --outline remains the operator-owned explicit-source exception and does not accept app selection.
• trails schema <command...> shows accepted CLI routes, aliases, flags, and schemas for an operator command or command namespace.
• trails warden runs Trails governance checks for contract and architecture drift. Configured workspaces derive topo targets from workspace.apps; --app <id> narrows topo-aware checks while preserving project-wide source facts. Use --scope-exclude <glob> or project warden.scope.exclude config when local notes, scratch space, or generated state should not be governed by Warden.
• trails regrade plan <from> <to> --root-dir <path> --json writes an active Regrade plan, trails regrade plan --expand stages wide-net review candidates in that plan, trails regrade preview reruns it without writing, and trails regrade apply consumes the plan and writes history. The minimal from/to seed is the primary workflow: planning deterministically derives morphology proposals, source-observed naming and public-identifier review candidates, review-only filename moves with reference-closure evidence, a namespace census, and current live-topo API preserves into the artifact's derivation section. Each derived item records provenance; uncertain forms and file moves remain review inventory until explicitly authored into the plan. A malformed or incompatible trails.lock fails planning instead of silently dropping live-API preserves. Use plan --expand --dry-run to inspect additional observed candidates without writing the active plan, and add --dry-run to apply to prove the apply path without mutating source. Use trails regrade plans and trails regrade check when a workspace has active plans that need inspection before apply. Human CLI runs stream concise phase progress to stderr; --json and --jsonl keep that channel quiet while returning phase names and timings in the structured result. MCP returns the same lifecycle facts from trails_plan_regrade, trails_check_regrade, trails_preview_regrade, trails_apply_regrade, and trails_adjust_regrade and forwards progress notifications when the caller supplies a progress token. Lifecycle timings describe the command invocation and are never persisted into plans or history receipts. Apply reuses its command-local preflight evaluation only when exact source bytes plus plan, policy, scope, lock, and tool identities still match. Any stale or unreadable fact fails closed; no prepared handle is written to disk or required for receipt regeneration, and the post-apply completion scan still runs independently.
• trails guide remains available for compatibility; prefer trails wayfind --source live --module <app-module> or saved-artifact Wayfinder reads for agent navigation.

For configured workspaces, migrate package-manager discovery, root aggregate-lock assumptions, and persistent warden.apps lists to static workspace.apps. --root-dir fixes the project boundary, --app selects one stable configured ID, and --module only refines that app's live entry. Run and completion ownership are derived live from those configured apps; a root aggregate trails.lock is neither created nor consulted as workspace identity.

Use trails config explain --json to inspect that source-static identity without loading app modules or consulting locks. From a workspace root it reports the configured app catalog; --app <id> or an app-root CWD narrows the same Config-authored identity and records how the selection was made.

Scaffolding never writes trails.lock itself. Install dependencies, then use the normal compile path with the narrow topo:write permit:

# From a standalone app
trails compile --permit '{"id":"local-dev","scopes":["topo:write"]}'

# From a configured workspace root
trails compile --app my-app --permit '{"id":"local-dev","scopes":["topo:write"]}'

The selected app receives a validated lock with its deterministic scaffold overlay. The generated README teaches the same standalone or workspace flow.

Trails is contract-first: define trails once with typed input, Result output, examples, and meta; the framework derives CLI, MCP, HTTP, and future surfaces from the same contracts.

See the main Trails documentation for the full framework guide: https://github.com/outfitter-dev/trails