CLI Reference¶
Auto-generated from
cli.py. Do not edit manually.Regenerate with:
uv run python scripts/generate_cli_docs.py
The CLI executable is zen. It is the local/CI interface for the same analysis capabilities exposed through MCP tools. All commands support --quiet to suppress Rich panels and banners.
MCP-first workflow
If you're using an MCP-capable editor or agent, start with MCP Tools Reference. Use the CLI when you need local checks, export artifacts, or CI automation.
Commands at a glance¶
| Command | Purpose |
|---|---|
zen check |
Run zen analysis for a path with optional CI gating and machine output. |
zen export-mapping |
Export rule-to-detector mappings as a Rich table or JSON payload. |
zen init |
Interactively scaffold zen-config.yaml, ignore config, and MCP integration. |
zen list-rules |
Display a table of zen rule IDs, severities, and principle texts. |
zen prompts |
Turn analysis violations into actionable remediation prompts or agent tasks. |
zen reports |
Generate a comprehensive analysis report for a file or directory. |
Analysis Commands¶
zen check {{ #check }}¶
zen check <PATH> [--language <TEXT>] [--config <TEXT>] [--perspective all|zen|dogma|testing|projection] [--as <TEXT>] [--format terminal|json|sarif] [--out <TEXT>] [--fail-on-severity <INTEGER RANGE>] [--show-files] [--enable-external-tools] [--allow-temporary-runners]
Run zen analysis for a path with optional CI gating and machine output.
Options:
| Option | Default | Description |
|---|---|---|
--language <TEXT> |
— | Override language detection |
--config <TEXT> |
— | Path to zen-config.yaml |
--perspective all|zen|dogma|testing|projection |
all |
Perspective to render: all, zen, dogma, testing, or projection (projection requires --as) |
--as <TEXT> |
— | Projection-family target used with --perspective projection |
--format terminal|json|sarif |
terminal |
Output format |
--out <TEXT> |
— | Write output to file |
--fail-on-severity <INTEGER RANGE> |
— | Exit with code 1 when any violation has severity >= this threshold |
--show-files |
— | Include per-file violation details in terminal output |
--enable-external-tools |
— | Opt-in to run available external language tools (no auto-install; missing tools emit recommendations). |
--allow-temporary-runners |
— | Allow temporary runner fallback (for example npx/uvx) when external tools are enabled. |
zen prompts {{ #prompts }}¶
zen prompts <PATH> [--language <TEXT>] [--config <TEXT>] [--perspective all|zen|dogma|testing|projection] [--as <TEXT>] [--mode remediation|agent|both] [--export-prompts <TEXT>] [--export-agent <TEXT>] [--severity <INTEGER>] [--enable-external-tools] [--allow-temporary-runners]
Turn analysis violations into actionable remediation prompts or agent tasks.
Options:
| Option | Default | Description |
|---|---|---|
--language <TEXT> |
— | Override language detection |
--config <TEXT> |
— | Path to zen-config.yaml |
--perspective all|zen|dogma|testing|projection |
all |
Perspective to render: all, zen, dogma, testing, or projection (projection requires --as) |
--as <TEXT> |
— | Projection-family target used with --perspective projection |
--mode remediation|agent|both |
remediation |
Prompt generation mode |
--export-prompts <TEXT> |
— | Write prompts markdown to file |
--export-agent <TEXT> |
— | Write agent JSON to file |
--severity <INTEGER> |
— | Minimum severity threshold |
--enable-external-tools |
— | Opt-in to run available external language tools (no auto-install; missing tools emit recommendations). |
--allow-temporary-runners |
— | Allow temporary runner fallback (for example npx/uvx) when external tools are enabled. |
zen reports {{ #reports }}¶
zen reports <PATH> [--language <TEXT>] [--config <TEXT>] [--perspective all|zen|dogma|testing|projection] [--as <TEXT>] [--format markdown|json|both|sarif] [--out <TEXT>] [--export-json <TEXT>] [--export-markdown <TEXT>] [--export-log <TEXT>] [--include-prompts] [--skip-analysis] [--skip-gaps]
Generate a comprehensive analysis report for a file or directory.
Options:
| Option | Default | Description |
|---|---|---|
--language <TEXT> |
— | Override language detection |
--config <TEXT> |
— | Path to zen-config.yaml |
--perspective all|zen|dogma|testing|projection |
all |
Perspective to render: all, zen, dogma, testing, or projection (projection requires --as) |
--as <TEXT> |
— | Projection-family target used with --perspective projection |
--format markdown|json|both|sarif |
markdown |
Output format |
--out <TEXT> |
— | Write output to file |
--export-json <TEXT> |
— | Write report JSON to file |
--export-markdown <TEXT> |
— | Write report markdown to file |
--export-log <TEXT> |
— | Write log summary to file |
--include-prompts |
— | Include remediation prompts |
--skip-analysis |
— | Skip analysis details in report |
--skip-gaps |
— | Skip gap analysis |
Configuration Commands¶
zen export-mapping {{ #export-mapping }}¶
Export rule-to-detector mappings as a Rich table or JSON payload.
Options:
| Option | Default | Description |
|---|---|---|
--out <TEXT> |
— | Write output to file |
--languages <TEXT> |
— | Filter by languages |
--format terminal|json |
terminal |
Output format |
zen init {{ #init }}¶
mcp-zen-of-languages-cli init [--force] [--yes] [--languages <TEXT>] [--strictness relaxed|moderate|strict] [--mcp-target <TEXT>]
The shorter zen init alias is also available for compatibility.
Interactively scaffold zen-config.yaml, ignore config, and MCP integration.
Options:
| Option | Default | Description |
|---|---|---|
--force |
— | Overwrite existing config |
--yes |
— | Skip prompts and use defaults |
--languages <TEXT> |
— | Languages to include (repeatable) |
--strictness relaxed|moderate|strict |
moderate |
Strictness: relaxed |
--mcp-target <TEXT> |
— | Write MCP client config for target(s): vscode, codex, copilot-local, copilot-global |
zen list-rules {{ #list-rules }}¶
Display a table of zen rule IDs, severities, and principle texts.
Global Options¶
| Flag | Description |
|---|---|
--quiet, -q |
Suppress banner, Rich panels, and decorative output |
--verbose, -v |
Show rich tracebacks with local variable inspection |
--help |
Show help for any command |
--version |
Print version number |
Exit Codes¶
| Code | Meaning |
|---|---|
0 |
Success — no violations above the configured threshold |
1 |
Violations found above the severity threshold |
2 |
Invalid configuration or arguments |