Framework CLI automation protocol

Consume versioned CLI JSON envelopes, bounded context, transactional change plans, receipts, and restricted verification safely.

Parse the version 1 envelope

JSON-capable CLI commands return a versioned machine envelope. Parseable JSON does not imply success: check the process exit status, ok, and error-level diagnostics.

API / contract	Type / boundary	Default / result	Behavior
`schemaVersion`	`1`	required	Machine protocol version.
`command`	`string`	required	Canonical producing command identifier.
`ok`	`boolean`	derived	False when the command or returned diagnostics contain an error.
`project.fingerprint`	`16 lowercase hex characters`	required	Bounded fingerprint of command-relevant project data, not a file content hash.
`data`	`command-specific`	required	Payload described by the command or companion schema.
`diagnostics`	`Diagnostic v1[]`	[]	Contains code, error/warning level, message, and optional location, confidence, fix, docs, or commands.
`nextActions`	`{ command, reason }[]`	[]	Suggested next commands; never implicit authorization.
`metrics`	`durationMs / bytes / estimatedTokens`	required	Bounded transport and execution metadata.

The installed package ships schemas under node_modules/@tavojs/cli/schemas.
Generator input uses node_modules/@tavojs/cli/generator-spec.schema.json.
agent-context data declares protocolVersion: 1 and protocolStability: stable.

Request the smallest useful context

Summary context contains conventions, focused source metadata, relevant API cards, recipes, commands, and bounded project information.
Request full detail only when a complete route or inventory graph is necessary.
Focused inspection includes a SHA-256 content hash where available; use that hash as a write precondition.

BASH

bashnpx tavo agent-context --json   --task modify-route   --target /account   --detail summary

npx tavo inspect route /account --json

Use explicit transactional operations

A change plan contains between one and 100 versioned operations. Existing-file mutations require a 64-character SHA-256 precondition; low-risk diagnostic fixes require either expectedSha256 or expectedMissing.

API / contract	Type / boundary	Default / result	Behavior
`generate`	`generator spec`	planned write	Runs one validated `Tavo.js` generation specification.
`create-file`	`path + content`	new file	Rejects an unsafe, escaping, or existing target.
`replace-range`	`hash + 1-based range`	bounded edit	Rejects stale content before replacing the exact source range.
`delete-file`	`path + hash`	transactional delete	Rejects a stale or escaping target.
`apply-fix`	`diagnostic code + precondition`	low-risk fix only	Applies a CLI-owned safe fix identified by its diagnostic.

Each text payload is limited to 1 MiB.
Traversal and symlink escapes are rejected.
If a later operation fails, earlier writes are rolled back.

JSON

json{
  "schemaVersion": 1,
  "operations": [
    {
      "id": "update-account-title",
      "kind": "replace-range",
      "file": "src/pages/account.tsx",
      "expectedSha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
      "range": {
        "start": { "line": 12, "column": 3 },
        "end": { "line": 12, "column": 24 }
      },
      "text": "<Text>Account settings</Text>"
    }
  ]
}

Retain and verify the receipt

API / contract	Type / boundary	Default / result	Behavior
`dryRun`	`boolean`	required	Distinguishes a planned receipt from an applied change.
`transaction`	`planned \| committed \| rolled-back \| rejected`	required	Reports the final transaction state.
`fileHashes`	`path → SHA-256 \| null`	required	Records post-operation file state for focused verification.
`operations`	`operation result[]`	required	Reports each planned or attempted operation.
`verificationCommand`	`string`	required	Suggested focused verify command for the receipt.

change prints a protocol envelope to stdout; it does not create a receipt file automatically.
Save stdout only after checking that the command completed successfully.
verify expands affected Framework surfaces from the receipt and checks current hashes.
--no-project-scripts prevents verify from running package.json scripts. Confirm data.projectScripts is false.

BASH

bashnpx tavo change --from-json change-plan.json --dry-run
npx tavo change --from-json change-plan.json > change-receipt.json
npx tavo verify   --receipt change-receipt.json   --smoke   --no-project-scripts   --json

Use stdin and specs deliberately

Generator specs support page, component, store, layout, 404, error, action, and feature records.
Page specs use typedRoute: true only when defineRoutePage generation is desired.
Validation and dry-run prove structural validity and write scope; they do not approve the product change.
Use --force only after inspecting an intended replacement.

BASH

bashnpx tavo generate --validate-spec tavo.generated.json
npx tavo generate --from-json tavo.generated.json --dry-run
npx tavo generate --from-stdin --dry-run < tavo.generated.json
npx tavo change --from-stdin --dry-run < change-plan.json

Verify semantic CLI behavior

npx tavo inspect plugins --json performs plugin preflight and reports owners, permissions, reasons, exposure, and diagnostics.
Build flags override configured JavaScript budgets and prerenderStyles for that invocation.
Plain tavo preview delegates to Vite preview. tavo preview --ssr rebuilds when production output is missing or stale.
Use the project-local CLI resolved from the lockfile. Use npx @tavojs/cli only for initial application creation.
Use --help on the installed version as the exact command/flag inventory; use the authored references for side effects, security, precedence, and failure behavior.

Look up exact public types

Follow linked API names to their canonical TypeScript declarations and package boundaries.