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]

A path is a file, a directory, or a glob.

Argument	Behavior
src/transfer.ts	Analyzes that file
src	Walks the directory for .ts and .tsx files, skipping node_modules and .git
src/transfer.ts src/refund.ts	Analyzes each file in turn, so an unquoted shell glob works
'src/**/*.ts'	Quoted, so the CLI expands the pattern itself

A pattern that matches nothing is an error, not an empty run:

$ effect-analyze 'src/**/*.missing'
Error: No files matched: src/**/*.missing

Modes that read one directory (--coverage-audit, --service-cycles), follow one file (--watch, --entry-points), or write one file (--output) say so rather than picking whichever path came first:

$ effect-analyze src/transfer.ts src/refund.ts -o diagram.mmd
Error: 2 paths given. --output writes one file. Drop it, or pass one path.

Diff mode reads its two sources from the positional arguments, so --diff keeps its own <git-ref>:<path> syntax.

Output Streams

The result goes to stdout; progress, counts and warnings go to stderr. Redirecting produces a file that parses, with the status still visible in the terminal:

effect-analyze ./src/transfer.ts --format mermaid > transfer.mmd

--quiet silences the status lines themselves. Over several paths, --format json prints one array rather than a run of separate documents, so | jq works on the whole run.

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
--extensions <list>	Extensions discovered when walking a directory	ts,tsx
--max-depth <n>	How deep a directory walk descends	10
--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	—

An unrecognised value for a flag with a fixed set of choices (--format, --direction, --detail, --profile, --test-runner, --improve-min-priority) is an error, not a fallback to the default:

$ effect-analyze ./src --format nosuchformat --direction sideways
Error: Unknown value for --format: nosuchformat. See --help for accepted values.
Error: Unknown value for --direction: sideways. Accepted: TB, LR, BT, RL.

Every error is reported, then the CLI exits 1 without running. A missing value (the flag last in argv) is reported the same way.

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
--runtime-trace <file>	Overlay a captured trace on --format mermaid (see Diagram Fidelity)	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

Commands

effect-analyze is a drop-in replacement for the effect-tsgo CLI: the same subcommands, the same flags, the same exit codes.

Command	Description
diagnostics	Effect language service diagnostics plus the analyzer’s own rules, in one stream. Superset of effect-tsgo diagnostics
setup	Guided @effect/tsgo setup (forwarded verbatim)
config	Interactive diagnostic severity picker (forwarded verbatim)
patch / unpatch	Manage the patched TypeScript/Oxlint binaries (forwarded verbatim)
get-exe-path	Print the Effect language service executable path (forwarded verbatim)

diagnostics

Flag	Description
--project <tsconfig>	Project to check
--file <path>	Check a single file
--progress	Narrate progress on stderr
--list-files	Report detected/supported Effect versions per file
--format <fmt>	json | pretty | text | github-actions (default: pretty)
--severity <list>	Filter by comma-separated error,warning,message
--strict	Also fail the exit code on warnings
--fail-on <severity>	Override the gate: error, warning, message or none
--lspconfig <json>	Inline JSON replacing the project’s plugin options
--no-analyzer	Language service diagnostics only, omitting the analyzer’s rules

Flags are forwarded to @effect/tsgo untouched — it validates them, applies its own --severity semantics and picks its own exit code — and its output is passed through. Only --fail-on and --no-analyzer are ours. A run with no analyzer findings to add is literally the upstream run: text, pretty and github-actions output is byte-identical, including the summary trailer and the order upstream emitted its diagnostics in.

--format json is re-serialised so that every entry carries source (tsgo or analyzer), whether or not the analyzer contributed any. Upstream’s diagnostics array is preserved entry for entry and in its original order, with analyzer findings appended after it. Analyzer rules carry code: 0, outside the 377xxx Effect range, so a consumer that filters on that range sees exactly what it saw before.

Your project’s configuration is read by @effect/tsgo itself, from the @effect/language-service plugin entry in the tsconfig it is given — the same entry your editor uses, so the CLI and the editor agree. Nothing is synthesised on your behalf, and configured severities (including turning a rule off) are honoured exactly.

tsconfig.json

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "@effect/language-service",
        "diagnosticSeverity": { "floatingEffect": "warning" }
      }
    ]
  }
}

A project with no such plugin entry has the language service disabled, and filesChecked will be 0. That is upstream’s behaviour, and it is reported rather than worked around: check summary.filesChecked if you need to know whether a clean report actually examined anything.

effect-analyze diagnostics --project tsconfig.json --format json
effect-analyze diagnostics --project tsconfig.json --format github-actions --strict
effect-analyze diagnostics --project tsconfig.json --severity error --fail-on=none

Whenever @effect/tsgo does not produce a diagnostics report, its output and its exit status are passed through untouched, and neither --fail-on nor analyzer findings are applied to it. That covers failed invocations — a missing target, an unsupported flag, unparseable --lspconfig — which exit 1 exactly as a run that found errors does, so the status alone cannot tell them apart. It equally covers --help, which prints upstream’s help and exits 0.

--project and --file given together are a union, as upstream treats them.

Exit codes come from effect-tsgo diagnostics itself; analyzer findings can only add a failure it would not have seen, under the same rule (1 when any error is present, and with --strict also when any warning is). --fail-on overrides that gate, and --fail-on=none makes a run purely advisory.

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 <severity>	Exit 1 when a finding is at or above error, warning or info. Omit for an advisory run that never changes the exit status
--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
--no-test	Disable an earlier --test (e.g. from a shared alias or script)

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