CLI overview

effx check, build, inspect, and graph run the same compiler pipeline over a tsconfig project. dev repeats checks for saved inputs; lsp checks source buffers for one editor project. The long-running commands use the same compiler meaning and add explicit lifetime and executable-coverage policy. lift reads pure Effect source instead and prints suggested declarations; only its explicit --check runs application modules.

Source: scripts/effx.ts, packages/cli/src/commands.ts, docs/specs/0015-config-and-extensions.md.

CommandsCopy Anchor Link

The root command is described as "AOT application compiler for Effect".

Source for the surface check row: main.ts description and packages/cli/src/surface.ts (surfaceCheck, wiringDiagnostics). The comment there states that it never executes the program. Its diagnostic codes and the wiring rules are not described on this page.

effx cedar (packages/cli/src/cedar.ts, docs/specs/0017-effx-cedar.md) projects only; it evaluates no request and issues no lease. It is an opt-in command: check and build never run it or load its validator. Its validator, @cedar-policy/cedar-wasm 4.13.0, is an optional peer dependency of @effx/cli; install it with bun add @cedar-policy/cedar-wasm@4.13.0, otherwise the command fails naming that install. For this command --out-dir is the Cedar output directory (default <tsconfig dir>/.effx/cedar) and --strict-access is not applied. --namespace defaults to Effx. --policies validates application-written .cedar files against the emitted schema (EFFX4102, EFFX4106). The command's own codes are EFFX4101 to EFFX4107; exit status is 1 when any error is reported, or any warning with --deny-warnings.

FlagsCopy Anchor Link

The shared compilation flags below retain the same precedence for one-shot commands and sessions. dev adds --build; lsp adds launch-time --trust-config. Both accept repeatable --exec-file and --exec-dir inputs. See dev coverage and LSP trust before you use executable config.

inspect and graph accept all seven flags and resolve them exactly as check and build do. For example inspect User.Get --strict-access and graph --emit contract both exit 0 (observed by running bun scripts/effx.ts in examples/users). --strict-access changes diagnostic severity, and inspect and graph print no diagnostics, so it does not change their output. --naming-problem-identifier changes problem-contract semantics; see Problems and access for the pattern rules. check --strict-access on the same project turns the two EFFX2504 warnings into errors and exits 1, and check --no-strict-access keeps them as warnings and exits 0 (observed).

Positional arguments:

Literal valuesCopy Anchor Link

The --target and --emit values come from the TargetProfile and EmitMode schemas in packages/compiler/src/Collected.ts. main.ts builds the flags from TargetProfile.literals and EmitMode.literals, so the CLI and compiler cannot disagree.

Both --emit=contract and --emit contract forms are exercised by the CLI tests. See Emit modes and targets for what the values mean.

Defaults when nothing sets a valueCopy Anchor Link

Project configCopy Anchor Link

A project can keep its settings in an effx.config.ts module instead of repeating flags. The module default-exports defineConfig({ ... }) from @effx/cli/config. This page covers how the CLI finds and applies the file. For authoring extensions and the extensions and generators fields, see Extensions.

import { defineConfig } from "@effx/cli/config";

export default defineConfig({
  project: "tsconfig.effx.json",
  outDir: ".effx/generated",
  emit: "contract",
  target: "effect-4.0",
  strictAccess: true,
  naming: { problemIdentifier: "{Group}{Key}Problem" },
});

project, outDir, emit, target, strictAccess and naming are optional (EffxConfig in packages/cli/src/config.ts). Naming is semantic input, unlike generator toggles: use the same pattern in both emit passes (spec 0024 §5).

DiscoveryCopy Anchor Link

Discovery looks beside the tsconfig selected by the flag or the default. If the discovered config sets another project, the CLI does not look for a second config beside that project. When --project is given, the config project is ignored.

The CLI evaluates the selected config and its imports, not application operation modules. A long-running session retains that executable graph until restart. LSP requires explicit --config or launch-time --trust-config before discovered config executes. Coverage is conditional on complete caller declarations; it is not a sandbox.

PrecedenceCopy Anchor Link

Each value takes the first source that sets it, from left to right.

Source: the Resolution table in docs/specs/0015-config-and-extensions.md, checked against resolveProject in packages/cli/src/commands.ts. The spec's extra "programmatic ProjectConfig.projectRoot" source applies to library callers of compile, not to the CLI.

Where relative paths resolveCopy Anchor Link

The .effx directory that holds ir.json, manifest.json and surface.json is <tsconfig dir>/.effx. --out-dir and outDir move only the generated files (effxDir in resolveProject).

Extensions and generatorsCopy Anchor Link

The config can also set extensions and generators. These have no CLI flags. A config extensions array is appended to the built-in extensions. A callback receives the built-ins and returns the whole ordered list. generators toggles (http, rpc, cli, client, foldkit) switch off only the matching built-in file generator. All compilation paths use the resulting extension list. See Extensions for the authoring guide.

For sessions, executableCoverage supplies files and directories relative to the config. Launch declarations resolve from startup cwd and merge by union while retaining logical aliases. See Executable coverage for the exact shape, static package-link examples, and completeness limitation.

Exit behaviourCopy Anchor Link

Source: CheckFailed and UnknownName in packages/cli/src/commands.ts, which are marked errorReported = false so the runtime prints nothing more. The numeric exit code 1 for these two is stated in their doc comments and spec 0003. The exit code for CompilerFault is decided by BunRuntime.runMain and is not specified in the repository docs. A config failure is a CompilerFault built by invalidConfig with stage collect.

Invalid --target or --emit values fail at the CLI boundary, before the compiler runs (CLI test).

Output goes to stdoutCopy Anchor Link

One-shot diagnostics, the summary, inspect text, graph text, explain text and the lift report use stdout. dev prints complete cycle batches. LSP stdout contains only framed JSON-RPC; operational output uses stderr or protocol logs.

Every command writes through the process's standard output and error streams and returns only after the stream accepted the bytes. Output larger than a pipe or socket buffer therefore reaches a slow reader complete, with the same bytes as a redirect to a file. Source: printLines in packages/cli/src/output.ts.

See Diagnostics for the shared diagnostic data.