Imported from tallesborges/zdx (crates/zdx-cli/AGENTS.md). Install upstream with npx skills add tallesborges/zdx --skill zdx-cli. Copyright stays with the author.

zdx-cli development guide

Scope: CLI argument parsing/router, subcommands, and interactive/exec mode entrypoints.

Where things are

• src/main.rs: binary entrypoint
• build.rs: compile-time CLI version/build metadata
• src/cli/: argument structs + command dispatch
• src/cli/commands/automations.rs: automations commands (list, validate, run)
• src/cli/commands/bg.rs: background-process commands (zdx bg list [--json], zdx bg kill <bg_id>); thin wrapper over zdx_engine::background_activity
• src/cli/commands/bot.rs: Telegram bot setup/init command handler (zdx bot init)
• src/cli/commands/daemon.rs: scheduled automations daemon loop
• src/cli/commands/imagine.rs: image generation command handler (zdx imagine)
• src/cli/commands/speak.rs: text-to-speech command handler (zdx speak); thin wrapper over zdx_engine::audio::speak::synthesize_speech
• src/cli/commands/transcribe.rs: speech-to-text command handler (zdx transcribe <file>; --model, --language, --diarize, --json, --list-models); wraps zdx_engine::audio::transcribe::transcribe_audio_detailed + supported_models
• src/cli/commands/memory.rs: native memory indexing/search/read commands (zdx memory index/status/search/get)
• src/cli/commands/mcp.rs: MCP helper commands (servers, tools, schema, call)
• src/cli/commands/stats.rs: usage/cost summary command handler (zdx stats)
• src/cli/commands/quota.rs: live subscription-quota command handler (zdx quota, --json); thin renderer over the shared subscription_quota::fetch_snapshot() API
• src/cli/commands/service.rs: launchd service commands (zdx service install|uninstall|start|stop|restart|status|logs [bot|daemon|all]; restart supports --force); thin wrapper over zdx_engine::service
• src/cli/commands/telegram.rs: Telegram utility commands
• src/cli/commands/worktree.rs: worktree command handler
• src/modes/exec.rs: non-interactive streaming mode
• src/modes/mod.rs: mode exports (exec + feature-gated TUI)
• tests/integration/: CLI integration tests (assert_cmd, fixtures), aggregated into a single test binary via tests/integration/main.rs. Add new test files as tests/integration/<name>.rs and register them with mod <name>; in main.rs (for example threads_export.rs covers zdx threads export, exec_subagent.rs covers zdx exec --subagent, service.rs covers zdx service status/target validation without mutating launchd).

Conventions

• tests/integration/opencode_go_headers.rs covers OpenCode session routing, identity isolation, and stability across requests.

• Keep CLI glue thin; shared behavior belongs in zdx-engine.

• Prefer integration tests in crates/zdx-cli/tests/integration/ for CLI behavior. Do not add top-level tests/*.rs files — they would compile as separate test binaries and slow down just ci.

Checks

• Default final verification after code changes: just ci from repo root
• Intermediate iteration for this crate: cargo test -p zdx-cli --lib --bins --tests
• Use just lint or just test only when intentionally running one half of CI

Maintenance

• Add/move/delete .rs files in this crate: update this file.
• Add/move/delete prompt layer files in this crate: update this file.
• Command behavior contract changes: update docs/SPEC.md as needed.