CLI

The tenchi command scaffolds the prescribed structure, inspects the composed application, and keeps API changes reviewable.

Create an application

uvx tenchi new my_app

Names use snake_case. The generated project includes a todos feature, SQLite persistence with request-scoped transactions, a memory test adapter, strict checks, integration tests, Swagger UI, OpenAPI, application-tool, and evaluation-policy snapshots, a concise AGENTS.md, project-local MCP configuration, and GitHub Actions CI.

Generate application slices

uv run tenchi make feature notes
uv run tenchi make feature notes --dry-run
uv run tenchi make use-case notes create_note
uv run tenchi make use-case notes create_note --json

Generators create files and print explicit wiring instructions. They never rewrite route or infrastructure modules. --dry-run validates the operation and lists every file without writing it. --json emits the same result as a versioned object with the app root, artifact identity, files, follow-up steps, and any error.

Inspect routes

uv run tenchi routes
uv run tenchi routes --json

The default target is app.server.routes:routes. Override it with --routes module:attribute. JSON output is a versioned object containing the application root and the composed HTTP surface under routes.

Map the application

uv run tenchi map
uv run tenchi map --json
uv run tenchi map --feature notes --json
uv run tenchi map --feature notes \
  --kind route,job,task,tool,evaluation,use-case,policy,port --json

Map combines the canonical source layout with composed API routes, operational tasks, background jobs, application tools, and evaluations. It returns a deterministic, versioned graph covering features, contracts, routes, background jobs, operational tasks, application tools, evaluations, use cases, policies, ports, adapters, context types, entrypoints, and tests. Edges describe ownership, route bindings, dependencies, authorization, implementations, and feature tests. Each edge carries project-relative source evidence and an exact or inferred confidence value.

--feature keeps the selected feature and its directly connected nodes, which makes cross-feature policy and shared-port dependencies visible without loading the entire application. --kind accepts a comma-separated projection of node kinds. The default route target is app.server.routes:api_routes; override it with --routes module:attribute. The default job target is app.server.jobs:jobs; override it with --jobs module:attribute. The default tool target is app.server.tools:tools; override it with --tools module:attribute. The default evaluation target is app.server.evaluations:runner; override it with --evaluations module:attribute.

The JSON result also embeds tenchi doctor diagnostics and unresolved source relationships. Agents should inspect both before editing and use stable node IDs and source locations to choose the files involved in a change. See coding agents for the complete workflow across map, make, check, and OpenAPI compatibility.

Manage application-tool contracts

uv run tenchi tools
uv run tenchi tools --json
uv run tenchi tools --diff tools.json
uv run tenchi tools \
  --diff-ref origin/main \
  --snapshot tools.json
uv run tenchi tools --check tools.json
uv run tenchi tools --write tools.json

The default target is app.server.tools:tools; override it with --tools module:attribute. Plain output is the canonical portable manifest. --json wraps that manifest with the application root and agent protocol version for automation.

--check is an exact drift check. --diff and --diff-ref classify changes directionally and fail on breaking or unknown changes. A Git ref supplies a meaningful historical baseline even when the working branch updates its snapshot. Use --diff-format json for the versioned compatibility result. See Application tools for the compatibility rules.

Manage OpenAPI

uv run tenchi openapi --routes app.server.routes:api_routes \
  --title my_app --version 0.1.0
uv run tenchi openapi --routes app.server.routes:api_routes \
  --title my_app --version 0.1.0 --diff openapi.json
uv run tenchi openapi --routes app.server.routes:api_routes \
  --title my_app --version 0.1.0 \
  --diff-ref origin/main --snapshot openapi.json
uv run tenchi openapi --routes app.server.routes:api_routes \
  --title my_app --version 0.1.0 --check openapi.json
uv run tenchi openapi --routes app.server.routes:api_routes \
  --title my_app --version 0.1.0 --write openapi.json

Common metadata options are --title, --version, --description, and --security. --diff-ref reads --snapshot (default openapi.json) from a Git commit instead of the working tree. See OpenAPI and compatibility for the safe baseline workflow.

The standalone openapi command does not discover metadata declarations from the route module. Use the same target and metadata flags for print, diff, check, and write operations. tenchi check and tenchi verify do discover literal OPENAPI_* declarations.

When --diff-format json is selected, the versioned result includes the application root, baseline label, compatibility status, severity counts, and classified changes.

Check architecture

uv run tenchi doctor
uv run tenchi doctor --json

Doctor validates the canonical application structure, dependency direction, and authorization consistency. Findings include a stable code, severity, file, line, and message in the versioned JSON result.

Run every check

uv run tenchi check
uv run tenchi check --json

Check runs Ruff format, Ruff lint, Pyright, pytest, doctor, and the exact OpenAPI, application-tool, and evaluation-policy snapshot checks. Every step runs even when an earlier one fails. Human output shows a compact status list; JSON includes stable step names, commands, exit codes, durations, and bounded failure output. Use --timeout to change the per-step limit.

OpenAPI defaults come from literal top-level OPENAPI_TITLE, OPENAPI_VERSION, optional OPENAPI_DESCRIPTION, and optional OPENAPI_SECURITY declarations in the module selected by --routes; command flags override them. The route target defaults to app.server.routes:api_routes, and the snapshot defaults to openapi.json. The tool target defaults to app.server.tools:tools, and its snapshot defaults to tools.json. The evaluation target defaults to app.server.evaluations:runner, and its snapshot defaults to evaluations.json. Override them with --evaluations and --evaluation-snapshot.

Verify a completed change

uv run tenchi verify --base-ref origin/main
uv run tenchi verify --base-ref origin/main --json

Verify produces one receipt for the finished source tree. It runs tenchi check, rejects application-map diagnostics and unresolved relationships, and compares the generated OpenAPI document, application-tool manifest, and evaluation-policy manifest with the snapshots at the selected Git ref. The receipt records the immutable commit resolved from --base-ref, so all three compatibility reports use the same historical state even if the named ref moves later.

Use the pull request base, previous push, or previous release as the base ref. The option is required: using the current branch snapshot could hide a breaking change when code and its updated snapshot are committed together. The command exits non-zero for a failed check, incomplete architecture evidence, a breaking or unknown boundary change, or a baseline that cannot be read.

If the selected ref already contains the OpenAPI and tool snapshots but genuinely predates the application's first evaluations.json, pass --allow-missing-evaluation-baseline once and confirm the evaluation result includes an evaluation manifest baseline metadata change. Missing evaluation snapshots otherwise fail closed, so a renamed or mistyped path cannot silently replace the historical policy.

--snapshot, --tool-snapshot, --evaluation-snapshot, and the route, task, job, tool, evaluation, and OpenAPI metadata options override the generated application conventions. Verify never updates snapshots. Because it runs the application's tests and validation commands, those commands retain their normal side effects and per-step timeout.

Verify loads app.server.evaluations:runner for architecture evidence and the payload-free policy comparison but does not run evaluators. Use --evaluations module:attribute when the application uses another composition target.

Verify the deployment environment

uv run tenchi preflight
uv run tenchi preflight --json
uv run tenchi preflight --timeout 3

Preflight discovers app.server.preflight:checks and runs its read-only async observations concurrently. Each check keeps its declared timeout; --timeout can only cap those limits. Results expose stable names, descriptions, statuses, durations, and failure codes while discarding dependency values and exception messages. The command exits non-zero when any check fails or times out.

Use --preflight module:attribute to override the declaration target. See deployment preflight for declarations, dependency patterns, redaction, and rollout placement.

Run AI evaluations

uv run tenchi eval list
uv run tenchi eval list --json
uv run tenchi eval snapshot --diff evaluations.json
uv run tenchi eval snapshot --diff-ref origin/main \
  --snapshot evaluations.json
uv run tenchi eval snapshot --check evaluations.json
uv run tenchi eval snapshot --write evaluations.json
uv run tenchi eval run
uv run tenchi eval run support.answer_quality --json

eval list discovers app.server.evaluations:runner and returns case names and schemas, metrics, thresholds, timeouts, and token or cost budgets without case inputs. eval snapshot prints, writes, checks, or directionally compares the payload-free policy without invoking evaluators. Breaking and unknown changes return a non-zero status; --diff-format json returns the versioned evaluation_diff result. A missing Git snapshot fails by default. During first adoption only, pass --allow-missing-baseline and require the resulting evaluation manifest baseline metadata change; do not use it for a renamed or mistyped path. eval run opens the application lifespan, gives each case a scoped context, and exits non-zero when a case, threshold, or budget fails.

Use --concurrency to override the number of cases in flight and --timeout to tighten each case's declared timeout. Use --evaluations module:attribute to override the runner target. Evaluation execution stays separate from check and verify because it may call external models, vary between runs, and incur cost. Those commands verify only the declared policy. See AI evaluations for declarations, scoring, redaction, and deployment guidance.

Run operational tasks

uv run tenchi task list
uv run tenchi task list --json
uv run tenchi task run projects.repair_members \
  --input '{"dry_run": true}'
uv run tenchi task run projects.repair_members \
  --input '{"dry_run": false}' \
  --json

task list discovers app.server.tasks:runner and reports every task's input and output JSON Schema. task run validates input, opens the application lifespan and scoped context, invokes the use case, validates its result before the context commits, and returns a non-zero exit status for failure results. Use --tasks module:attribute to override the runner target.

See Operational tasks for declarations, composition, dry-run design, failure semantics, and MCP access.

Serve coding-agent tools over MCP

uv run tenchi mcp
uv run tenchi mcp --root path/to/application

This command exposes repository inspection and validation—not the application's ToolGroup. MCP support is installed through the tenchi[mcp] extra. Generated applications include it as a development dependency and register the default command in .mcp.json. --routes, --api-routes, --preflight, --evaluations, --tasks, --jobs, --tools, --snapshot, and --tool-snapshot override the conventions captured by the server when it starts. --title, --version, --description, and --security override discovered OpenAPI metadata for the diff and check tools. Pass --allow-task-runs only when the connected agent may perform operational writes; task discovery remains available without it. Pass --allow-evaluation-runs only when the connected agent may call providers and consume evaluation budgets; evaluation discovery remains available without it. The command uses stdio and waits for an MCP client; it does not start an HTTP listener.

See connect an MCP-aware coding agent for tool behavior, safety, and client configuration.

Run development

uv run tenchi dev
uv run tenchi dev --host 0.0.0.0 --port 8080
uv run tenchi dev --no-reload

The default ASGI target is app.server.asgi:app. Override it with --app module:attribute. Production deployments should invoke an ASGI server directly rather than the development command.