CLI Reference

The effect-analyze CLI analyzes Effect TypeScript files and produces diagrams, metrics, lint findings, health reports, and prioritized improvement plans.

Usage

effect-analyze [path] [options]

When path is a file, the analyzer processes that file. When it is a directory, it processes all TypeScript files within it. Multiple paths can be provided for diff mode.

General Options

Flag	Description	Default
-f, --format <format>	Output format (see All Formats)	auto
-o, --output <file>	Write output to a file instead of stdout	stdout
--pretty	Pretty-print output (overrides --compact)	on
--compact	Compact output (no indentation)	off
--no-color	Disable colored terminal output	color on
--quiet	Suppress verbose status messages	off
--tsconfig <path>	Path to a custom tsconfig.json	auto-detected
--include-trivial	Include trivial programs (schemas, thin wrappers) that are excluded by default	off
--no-metadata	Exclude analysis metadata from JSON output	off
-h, --help	Print help and exit	—

Diagram Options

Flag	Description	Default
--direction <dir>	Mermaid flow direction: TB, LR, BT, RL	TB
--style-guide	Apply style-guide heuristics for cleaner, more readable diagrams	off
--no-style-guide	Explicitly disable style-guide mode	—
--assert-diagram-fidelity	Exit with code 1 when a diagram contains unresolved or ambiguous nodes	off

Analysis Modes

Flag	Description
--diff	Compare two program versions (see Semantic Diff)
--regression	Flag removed steps as regressions (use with --diff)
--watch	Re-analyze when the file changes
--cache	Cache analysis results in watch mode to skip unchanged files
--coverage-audit	Run a project-wide coverage audit (see Coverage Audit)
--migration	Alias for --format migration

Source Linting

Run deterministic source-level lints. See Source Linter for the full rule list and workflow.

Flag	Description
--lint-source	Run deterministic source lints on a file or directory
--tsgo[=<tsconfig>]	Merge official type-aware Effect diagnostics from @effect/tsgo; bare --tsgo uses tsconfig.json (target project requires TypeScript 7+)
--sarif	Emit SARIF 2.1.0 output
--scorecard	Emit a per-file lint scorecard
--baseline <file>	Compare findings against a baseline session/JSON file
--fail-on-new	Exit non-zero when new findings exist vs baseline
--require-suppression-reason	Require a reason after effect-analyzer-disable-next-line comments
--fail-on-stale-suppressions	Exit non-zero when suppression comments are stale
--bundle-output <dir>	Write deterministic artifact bundle (diagnostics, SARIF, summary, rules, session)
--profile <name>	Rule profile: strict, ci, migration, docs

Health Analyzers

Project-wide analyzers that surface structural issues. See Health Analyzers.

Flag	Description
--error-channel	Generic errors, unhandled types, missing catchTag handlers
--service-health	Unsatisfied services, dead services, layer inefficiencies
--performance	Sequential-could-parallel, unbounded concurrency, N+1, large gen blocks, missing batching, unbounded retries, forEach without concurrency
--coupling	Per-file fan-in / fan-out metrics, hub detection, annotation-aware suppression
--coupling-transitive	With --coupling: walk re-exports so importers of a barrel also count toward the barrel’s source modules
--coupling-priority <map>	Override agent-report priorities per coupling issue type (e.g. critical-fanin=P0)
--tsconfig <path>	Read compilerOptions.paths / baseUrl for path-alias resolution (used by --coupling and project-mode commands)

All four health analyzers support --format json for scripting and --output <path> to write to a file. See the Coupling Analyzer reference for the full coupling option surface.

App-Shape Analyzers

Inspect the surface and dependency shape of an Effect app. See App-Shape Analyzers.

Flag	Description
--entry-points	Detect NodeRuntime / BunRuntime / Layer.launch / runFork entry points (single file)
--config-leaks	Flag Config.redacted / Config.secret values that flow into logs or console sinks (single file)
--cli-commands	Extract @effect/cli Command/Args/Options/Prompt structure (single file)
--service-cycles	Detect cycles in the project-wide service dependency graph (directory)

Improvement Workflow

Prioritized, agent-ready improvement plans with optional auto-fixing. See Improve Mode.

Flag	Description
--agent-report	Generate a prioritized improvement backlog (JSON + Markdown) optimized for coding agents
--improve	Apply automated fixes for fixable lint issues
--improve-dry-run	Preview fixes without applying (default for --improve)
--improve-max-fixes <n>	Limit number of fixes to apply
--improve-rule <rule>	Only apply fixes for this rule (repeatable)
--improve-exclude-rule <rule>	Exclude fixes for this rule (repeatable)
--improve-min-priority <P>	Minimum priority level to include: P0, P1, P2, P3

Rule Registry

Inspect and search the deterministic rule registry (source lints, effect-lints, strict diagnostics).

Flag	Description
--list-rules	Print the full rule registry as a docs table
--index-rules	Print searchable rule index entries
--search-rules <query>	Search rules by code, title, description, or example
--explain-rule <code>	Show one rule in detail (description, docs URL, Bad/Good examples)

Test Stub Generation

Flag	Description
--test	Write a {programName}.test.ts stub next to each source file
--test-runner <runner>	Test runner: vitest (default), jest, mocha
--test-overwrite	Overwrite existing test files instead of skipping

Directory Mode Options

Flag	Description	Default
--colocate	Write .effect-analysis.md next to each source file	off
--no-colocate	Print a summary to stdout instead of writing files	—
--colocate-suffix <suffix>	Custom suffix for colocated files	effect-analysis
--service-map	Show a deduplicated service registry across the project	on
--no-service-map	Disable the project-wide service map	—
--no-colocate-enhanced	Use standard Mermaid instead of enhanced format for colocated files	—
--max-files <n>	Analyze at most n files (cursor-window mode for huge repos)	unlimited
--cursor <n>	Start from nth file in sorted file list (resumable window)	0

Statechart Options

These flags are used with the statechart formats (mermaid-statechart, svg-statechart, statechart-html, xstate-config, statechart-coverage), which read state machines instead of the Effect IR:

Flag	Description	Default
--min-coverage <n>	With --format statechart-coverage: exit 1 if any machine is below n%	—
--coverage-json	With --format statechart-coverage: emit { machines, summary } for dashboards	off
--open	With --format statechart-html/svg-statechart: open the written page in your browser	off

effect-analyze ./machine.ts --format statechart-html --open
effect-analyze ./src --format statechart-coverage --min-coverage 60

Coverage Audit Options

These flags are used with --coverage-audit:

Flag	Description
--show-suspicious-zeros	Show files with no Effect programs that look suspicious
--show-top-unknown	Show files with the highest unknown node rates
--show-top-unknown-reasons	Include reasons for unknown nodes
--show-by-folder	Aggregate results by folder
--json-summary	Output audit results as JSON
--per-file-timing	Include per-file timing data
--min-meaningful-nodes <n>	Minimum node count to consider a file meaningful
--known-effect-internals-root <path>	Treat local paths as Effect-like
--exclude-from-suspicious-zero <pattern>	Exclude patterns from suspicious-zero reporting
--max-audit-failed-files <n>	Exit 1 when analysis failures exceed n
--max-audit-suspicious-zeros <n>	Exit 1 when suspicious zero-program files exceed n
--min-audit-effect-adoption <percent>	Exit 1 when Effect-bearing files fall below this percentage of discovered files
--min-audit-source-resolution <percent>	Exit 1 when resolved IR nodes fall below this percentage of all IR nodes

Quality Options

Flag	Description
--quality	Compute heuristic diagram readability metrics for each program
--quality-eslint <path>	Ingest ESLint JSON for optional quality hints

OpenAPI Options

Flag	Description
--export <name>	Export name of the HttpApi (with --format openapi-runtime)

Session Envelope

For reproducible CI runs, the analyzer can export and re-import a full session envelope (inputs, options, results metadata).

Flag	Description
--export-session <file>	Export CLI session envelope
--import-session <file>	Import and print a previously exported envelope

Output Formats

Diagrams

auto mermaid mermaid-railway mermaid-paths mermaid-enhanced mermaid-services mermaid-errors mermaid-decisions mermaid-causes mermaid-concurrency mermaid-timeline mermaid-layers mermaid-retry mermaid-testability mermaid-dataflow

Structured

json stats explain summary matrix showcase

API Documentation

api-docs openapi-paths openapi-runtime

Project

migration

Examples

Analyze a single file with auto-detection

effect-analyze src/transfer.ts

Generate a railway diagram and save to file

effect-analyze src/transfer.ts -f mermaid-railway -o transfer.md

Reject an inexact diagram in CI

effect-analyze src/transfer.ts --assert-diagram-fidelity

The command prints each fidelity issue before it exits. See Diagram Fidelity for the checks.

Analyze a directory with colocated output

effect-analyze src/ --colocate

Run a coverage audit with JSON output

effect-analyze src/ --coverage-audit --json-summary

Source lints with SARIF output for code-scanning

effect-analyze src/ --lint-source --sarif -o findings.sarif

Gate CI on new lint findings only

effect-analyze src/ --lint-source --baseline ./.cache/effect-lint-baseline.json --fail-on-new

Inspect a single rule

effect-analyze --explain-rule runSync-on-async

Agent-ready improvement backlog

effect-analyze src/ --agent-report -o backlog.md

Apply safe auto-fixes (dry run first)

effect-analyze src/ --improve --improve-dry-run
effect-analyze src/ --improve --improve-min-priority P1 --improve-max-fixes 20

Project health snapshot

effect-analyze src/ --error-channel --service-health --performance --format json

Detect entry points and config leaks in an app

effect-analyze src/main.ts --entry-points
effect-analyze src/main.ts --config-leaks

Service dependency cycles

effect-analyze src/ --service-cycles --format json

Compare two branches

effect-analyze main:src/transfer.ts feature:src/transfer.ts --diff

Watch mode with caching

effect-analyze src/transfer.ts --watch --cache

Plain-English explanation

effect-analyze src/transfer.ts --format explain

Generate test stubs alongside source

effect-analyze src/ --test --test-runner vitest

OpenAPI spec generation

effect-analyze src/api.ts --format openapi-runtime --export MyApi -o openapi.json