cli.md

CLI reference and discovery

This page is the maintained map of EasyCat's command families. Commands use the installed CLI form; from this repository, prefix them with uv run (for example, uv run easycat doctor). Run any command with --help for its full option reference.

First run and scaffolding

easycat console                    # offline text console
easycat console --voice-demo       # scripted, keyless audio-pipeline proof
easycat console --live             # explicit provider-backed console
easycat init my-agent              # scaffold a project
easycat init my-agent --easycat-git URL --easycat-git-rev REV # portable dependency
easycat init --list-templates # compare templates, base package requirements, env vars, files, preflight/check/fix/docs/json-schema/run commands
easycat init --list-templates --json # emit the machine-readable template catalog
easycat doctor           # check API keys, optional extras, provider reachability
easycat doctor --json    # emit machine-readable environment checks
easycat doctor --env-file .env
easycat doctor --env-file .env --json # emit checks with project .env loaded
easycat doctor --manifest easycat.toml --profile default --json # diagnose the selected profile
easycat doctor --fix               # explicitly create repairable local state

init --list-templates reports each scaffold's base easycat[...] package requirement and extras, required environment variables, optional environment knobs, generated files, and copyable create/preflight/check/fix/docs/json-schema/run commands. Use its JSON form for automation.

By default, a CLI running from an editable EasyCat checkout records that local path in the generated [tool.uv.sources]. Use --easycat-git URL with optional --easycat-git-rev REV when the project must install in CI or on another developer's machine. It is mutually exclusive with --easycat-source PATH. JSON config uses easycat_git, easycat_git_rev, and easycat_source with the same rules; Git credentials belong in a credential helper or SSH agent.

doctor distinguishes required, optional, unused, and not-applicable requirements. Network liveness is not credential validation. The default run does not create journal directories; --fix owns repair mutations.

With --manifest, doctor diagnoses the same selected profile plan resolves: it reports the credential, install extra, and manifest reference each selected role needs, and skips checks the selection does not use — a browser profile is not asked for a microphone. Resolution is static: the profile's application module is never imported or run and no provider is called. A manifest typo aborts the run with the same coded error plan prints; rerun bare easycat doctor for machine-only checks. --manifest/--profile and --provider are two incompatible scoping mechanisms and cannot be combined.

Every JSON check row carries a probe class so the boundary between static reading and live probing is machine-readable: static (declared metadata, environment variables, module availability), import, filesystem, hardware, and network (one bounded two-second unauthenticated request per configured provider). The envelope's probes object reports which classes actually ran.

From a failed doctor to a first run

A fresh checkout, from the first red run to a green one. easycat init scaffolds an application, not a server manifest, so step 2 writes the easycat.toml the rest of the sequence diagnoses:

easycat init my-agent && cd my-agent          # 1. scaffold the project
cat > easycat.toml <<'TOML'                   # 2. declare the profile to serve
[project]
name = "my-agent"

[voice.default]
transport = "webrtc"
stt = "openai"
tts = "openai"
TOML
easycat doctor --manifest easycat.toml --json # 3. fails: EASYCAT_E203, no credential
cp .env.example .env                          # 4. fill in the real key, then save
easycat doctor --manifest easycat.toml --env-file .env --json # 5. fails: EASYCAT_E202
# 6. apply each failing row's `fix` field, then:
uv sync
easycat doctor --manifest easycat.toml --env-file .env --json # 7. green
easycat plan --manifest easycat.toml          # 8. the same selection, role by role

Step 6 is whatever the failing rows' fix fields name — here, adding webrtc and silero-vad to the easycat[...] extras in the project's own pyproject.toml. A project scaffolded by easycat init pins its easycat dependency in [tool.uv.sources] (EasyCat is unpublished), so the fix edits that list and then runs uv sync — never uv add, which would drop the pin. A project that depends on a published easycat gets the registry guidance instead. doctor --manifest classifies the dependency source of the directory holding the manifest, so the fix is right even when you run it from elsewhere.

Running an application or playground

easycat serve
easycat serve --mode browser
easycat serve --manifest easycat.toml
easycat serve --manifest easycat.toml --profile production
easycat plan --manifest easycat.toml
easycat plan --manifest easycat.toml --profile production --json

Without --manifest, serve starts EasyCat's bundled playground agent. It does not import a VoiceApp from the current directory. With a manifest, it builds the selected VoiceServer profile. plan resolves the same provider and capability inputs without starting the server — and easycat doctor --manifest easycat.toml --profile default diagnoses that same selection against the local machine, so the two describe one selection mechanism rather than two. Roles the session does not build are reported as off — a vad role, for example, when the STT declares native_endpointing and owns turn boundaries — so their install extras are not counted as blocking gaps by either command.

--json reports the gap tuples missing_env, missing_extras, and missing_backends. missing_backends names a selected backend whose SDK is absent even though it has no pip extra, as role:provider (for example vad:krisp); like the other two it blocks the plan, because create_session raises for it.

Documentation and error lookup

easycat docs             # list route labels and available audience filters
easycat docs --verbose   # expand every route with descriptions and command hints
easycat docs --audience learners # expand routes for one reader audience or broad role
easycat docs --audience learners --json # emit a filtered docs route map for learners
easycat docs --audience app-builders # filter docs to scaffold and app-building routes
easycat docs --audience app-builders --json # emit a filtered docs route map for app builders
easycat docs --audience operators # filter docs to deployment and observability routes
easycat docs --audience operators --json # emit a filtered docs route map for operators
easycat docs --audience maintainers # filter docs to architecture and maintenance routes
easycat docs --audience maintainers --json # emit a filtered docs route map for maintainers
easycat docs --audience coding-agents # filter docs to repository coding-agent routes
easycat docs --audience coding-agents --json # emit a filtered docs route map for coding agents
easycat docs --json      # emit docs routes, audiences, and command hints for automation
easycat explain E102     # look up errors and CLI schema topics
easycat explain json-schema # document the --json envelope and command metadata
easycat explain --list

docs --json returns route paths, audience labels, Diátaxis categories, command hints, available_audiences, available_audience_filters, and the audience_alias_note. explain json-schema defines the shared JSON envelope and command-specific fields.

Bundles, journals, replay, and debugging

easycat bundles list      # list captured debug bundles and crash dumps
easycat bundles list --json # emit machine-readable bundle list
easycat bundles show PATH # summarise a debug bundle or SQLite journal
easycat bundles show PATH --json # emit machine-readable bundle/journal summary
easycat bundles export PATH # write a redacted coding-agent context pack
easycat bundles export PATH --output DIR --json # emit context-pack metadata
easycat inspect PATH      # summarise a debug bundle or SQLite journal
easycat inspect PATH --json # emit machine-readable bundle/journal summary
easycat replay PATH       # replay a debug bundle or SQLite journal
easycat replay PATH --json # emit machine-readable replay summary
easycat latency PATH
easycat latency PATH --json
easycat diff PATH_A PATH_B
easycat diff PATH_A PATH_B --json
easycat journal grep PATH --query TEXT
easycat journal follow PATH
easycat journal promote PATH TURN_ID --out FILE
easycat tail PATH
easycat debugger serve PATH --no-open-browser

Use bundles list to discover files instead of guessing paths. show and inspect accept a debug bundle or SQLite journal. export writes a redacted coding-agent context pack. Journal search/follow output is redacted; promoted turns become deterministic replay fixtures. See observability for lifecycle, retention, privacy, and storage-budget guidance.

Validation

easycat validate quick
easycat validate quick --json
easycat validate socket
easycat validate socket --json
easycat validate stress
easycat validate stress --json
easycat validate contracts
easycat validate contracts --json
easycat validate latency --smoke
easycat validate latency --smoke --json
easycat validate live
easycat validate live --json
easycat validate release
easycat validate release --json
easycat validate report .easycat/validation/latest.json
easycat validate report .easycat/validation/latest.json --json

quick is deterministic and credential-free. socket, stress, and contracts are explicit local lanes; latency and live can use provider credentials and may incur charges. See the validation workflow for lane selection and release requirements.

JSON contract

Commands that support --json return the standard envelope described by:

easycat explain json-schema

The command families include docs routes, template catalogs, scaffold output, doctor environment/check rows, plans, validation runs/reports, bundle list/show/export, inspection, and replay. Command-specific success fields include entries, commands, catalog, audience, audience_filter, available_audiences, available_audience_filters, audience_alias_note, command_note, base_requirement, create_command, repo_create_command, next_step_commands, pyproject_name, run_command, check_command, fix_command, easycat_source, easycat_git, easycat_git_rev, environment, checks, validation, source_path, and fidelity_effective. Errors add fields such as report_path, path, and output_path where relevant.

Replace uppercase or angle-bracket placeholders such as PATH, DIR, TURN_ID, and <session_id> before executing copied commands.