1
-# effect/cli surface, as used in this repo
1
+# Effect CLI in this repository
2
3
-`@effect/cli` no longer exists. The CLI framework lives under `effect/cli`:
4
-`Command`, `Flag` (was `Options`), `Argument` (was `Args`), `GlobalFlag` (was
5
-`BuiltInOptions`), `CliConfig`, `CliOutput`, `CliError` (was `ValidationError`/
6
-`HelpDoc`). Ground truth for this reference is
7
-`ts/packages/cli/src/cli-config.ts`, `ts/packages/cli/src/cli-main.ts`, and
8
-`ts/packages/cli/src/invocation/invocation.ts` — read their full module docstrings before touching the runner, not just the excerpts below.
3
+The framework lives in `effect/cli`. The installed `effect@4.0.5` typings determine which interfaces compile. The CLI's registration and invocation modules determine how the repository uses them.
4
10
-## Command shape
5
+## Command registration
6
12
-```ts
13
-import { Command } from 'effect/cli';
7
+A command definition declares flags, arguments, descriptions, examples, and its imported handler. A handler accepts a plain params type and returns an Effect. The [contributor guide](../../../../ts/packages/cli/CONTRIBUTING.md) follows a filter through this structure.
8
+
9
+Every group uses `withRegisteredSubcommands` from `src/commands/registration.ts`. This helper supplies command identity and enforces inherited login metadata and supported shared flags. Calling `Command.withSubcommands` directly bypasses that behavior.
10
15
-declare const toolsCmd$List: Command.Command<'list', {}, never, never>;
16
-declare const toolsCmd$Info: Command.Command<'info', {}, never, never>;
11
+The following is the current connections group.
12
18
-export const rootToolsCmd = Command.make('tools').pipe(
19
- Command.withDescription('Browse and inspect tools before executing them.'),
20
- Command.withSubcommands([toolsCmd$List, toolsCmd$Info])
13
+```ts no-check repo-file=ts/packages/cli/src/commands/connections/connections.cmd.ts
14
+import { withCommandMeta } from 'src/invocation/command-identity';
15
+import { Command } from 'effect/cli';
16
+import { connectionsCmd$List } from './list/connections.list.cmd';
17
+import { connectionsCmd$Remove } from './remove/connections.remove.cmd';
18
+import { withRegisteredSubcommands } from 'src/commands/registration';
19
+
20
+export const rootConnectionsCmd = Command.make('connections').pipe(
21
+ Command.withDescription('Inspect and remove connected toolkit accounts.'),
22
+ withRegisteredSubcommands([connectionsCmd$List, connectionsCmd$Remove]),
23
+ withCommandMeta({ requiresLogin: true })
24
);
25
```
26
24
-(`ts/packages/cli/src/commands/tools/tools.cmd.ts`, unchanged shape from v3 apart from
25
-the import path — `Command.make`/`.withDescription`/`.withSubcommands` all carried over.)
27
+The registration supplies its command path after parsing. Root shortcuts can reuse the same definition with different command paths. `withCommandMeta` declares login requirements, invocation hook policy, telemetry family, and unsupported dev shared flags. The selected handler begins after parsing, then runs its enabled hooks, records the invoked event, rejects unsupported flags, and checks login.
28
+
29
+`CommandSurface` supplies root/dev context and dev shared flags. `actingUser()` resolves the acting user and project together. Handlers use these helpers instead of repeating user or project fallback rules. [ADR 0001](../../../../ts/packages/cli/docs/adr/0001-command-identity-after-parse.md) records the identity decision.
30
27
-Flags/arguments: `Flag.String/Boolean/Int/Literals/Directory(...)` (was
28
-`Options.text`/`.boolean`/`.integer`/`.choice`/`.directory`), with the same
29
-`.withDescription`/`.withDefault`/`.withAlias`/`.optional` combinators. `Argument.String(name)`
30
-takes a bare string name, not `{ name }`. Variadic: `Argument.variadic()` must be called
31
-with parens when piped — the bare unapplied reference resolves to the wrong overload.
31
+## Flags and arguments
32
33
-## `CliConfig.builtIns`
33
+Named options use `Flag.String`, `Flag.Boolean`, `Flag.Int`, `Flag.Literals`, or `Flag.Directory`. Positionals use `Argument.String`. Constructors use capital letters, while combinators use lowercase names. `Argument.variadic()` must be called when it is piped.
34
35
-v4's `CliConfig.Service` shrank to one field, `builtIns` — the ordered list of active
36
-global flags. `ts/packages/cli/src/cli-config.ts`:
35
+This standalone framework example demonstrates an optional flag and a positional argument.
36
37
```ts
39
-import { GlobalFlag, type CliConfig } from 'effect/cli';
38
+import { Argument, Flag } from 'effect/cli';
39
+
40
+export const toolkit = Argument.String('toolkit');
41
+export const query = Flag.String('query').pipe(Flag.withDescription('Text search'), Flag.optional);
42
+```
43
+
44
+Optional flags produce `Option` values. Defaults, aliases, and descriptions belong in the declaration so help and parsing agree.
45
+
46
+## Builtins, help and version
47
+
48
+`src/cli-config.ts` enables the repository's Help and Version actions. Both wrap framework actions to record command identity without running a selected handler.
49
50
+```ts no-check repo-file=ts/packages/cli/src/cli-config.ts
51
+import { Help, Version } from 'src/commands/root-help';
52
+import type { CliConfig } from 'effect/cli';
53
+
54
+// Help and version use the framework parser, wrapped to record the command they answer for. The
55
+// help formatter keeps version output bare.
56
export const ComposioCliConfig = {
42
- builtIns: [GlobalFlag.Help],
57
+ builtIns: [Help, Version],
58
} satisfies Partial<CliConfig.CliConfig.Service>;
59
```
60
46
-This drops `--version` (see the next section), `--wizard`, `--completions`, and
47
-`--log-level` (Composio has its own `--log-level` flag on the default command) — the v4
48
-equivalent of v3's `showBuiltIns: false`, scoped to exactly the one builtin Composio wants.
49
-
50
-v3's `autoCorrectLimit` and `isCaseSensitive` have **no v4 config field**, and Composio no
51
-longer reproduces either behavior:
52
-
53
-- The parser always computes "Did you mean?" suggestions internally
54
- (`internal/auto-suggest.ts`) and bakes them into `CliError.UnrecognizedOption` /
55
- `CliError.UnknownSubcommand`'s `message` getter. There is no parser switch to disable
56
- them, and Composio deliberately renders them as-is now — they are useful UX, not a
57
- regression to work around.
58
-- v4's parser performs no case-folding anywhere — flag/subcommand matching is always
59
- exact, so case-sensitivity needs no config.
60
-
61
-`ComposioCliConfig`'s `builtIns` narrowing is the _only_ `CliConfig` customization
62
-Composio makes. There is no custom `CliOutput.Formatter` — `InvocationLive` provides no
63
-`CliOutput.layer(...)` at all, so `Command.runWith` uses v4's own
64
-`CliOutput.defaultFormatter()` for everything: suggestions render as-is. An earlier revision of this file
65
-wrapped `defaultFormatter()` to strip suggestions and flatten `formatVersion` back to a
66
-bare semver; that formatter (`ComposioCliOutputFormatter`, `withoutSuggestions`) was
67
-deleted as a deliberate PR-review decision — do not reintroduce it.
68
-
69
-## `--version`, `-v`, and `composio version` print the same bare semver
70
-
71
-`GlobalFlag.Version` is not in `builtIns`. `src/commands/index.ts`'s
72
-`normalizeVersionFlag` rewrites a leading `--version`/`-v` to the `version` command before
73
-the parser runs, so all three spellings share `src/commands/version.cmd.ts`'s handler and
74
-print the bare `pkg.version`/`DEBUG_OVERRIDE_VERSION` via `ui.output()`. v4's
75
-`CliOutput.defaultFormatter().formatVersion` (`<name> v<version>`) is never reached: keeping
76
-the built-in active would have let `composio <subcommand> --version` render that banner
77
-instead, a second rendering of the same value. `composio <subcommand> --version` is therefore
78
-an unrecognized flag, like any other unknown option.
79
-
80
-## `runWith`, `ShowHelp`, and the no-double-print rule
81
-
82
-v4's `Command.runWith` is not a passive parser: it **renders help and parse/validation
83
-errors itself** (`Console.log`/`Console.error`, via whichever `CliOutput.Formatter` is
84
-in context — v4's default, per above) for the resolved `commandPath`, then re-fails with
85
-`CliError.ShowHelp`. By the time that failure reaches this package's runner, the correct
86
-output has already been printed once, to the correct stream.
87
-
88
-`CliError.ShowHelp` is not a plain tagged error — it carries two `effect/Runtime`
89
-markers set on the class itself (`ts/vendor/.../cli/CliError.ts`):
90
-`[Runtime.errorExitCode] = errors.length ? 1 : 0` and `[Runtime.errorReported] = false`.
91
-Those markers _are_ the contract: "I already printed my own output; don't log me again
92
-(`errorReported`), and here is the process exit code to use (`errorExitCode`)."
93
-`Runtime.makeRunMain` (which `BunRuntime.runMain`/`NodeRuntime.runMain` build on) reads
94
-`errorReported` off the squashed cause to decide whether to auto-log, and
95
-`Runtime.defaultTeardown` reads `errorExitCode` the same way — see
96
-`ts/vendor/effect/packages/effect/src/Runtime.ts`'s `getErrorReported`/`getErrorExitCode`.
97
-
98
-The CLI's own errors use the same contract. A failure a command already printed
99
-(`ReportedFailure` from `src/effects/report-failure.ts`, `ReportedToolExecutionError`,
100
-`ShellSetupAbortError`, `SetupCommandError`, …) or that carries a custom code
101
-(`ChildProcessExited` from `composio run`) declares the markers as getters, and
102
-the CLI's runner (`ts/packages/cli/src/run-main.ts`, built on `Runtime.makeRunMain`) exits
103
-through `Runtime.defaultTeardown`: 0 on success, and otherwise with the squashed failure's
104
-`errorExitCode` (1 when unset). An exit made of interruptions alone after a signal is 128 + the
105
-signal's number instead (130, 143, 129). Nothing in `src/` assigns `process.exitCode`.
106
-
107
-`runInvocation` (`src/invocation/invocation.ts`) skips every failure whose `errorReported`
108
-is false (`ShowHelp` included); when nothing is left it prints nothing. If you add rendering
109
-anywhere in this path, you will double-print — this is the single most important rule when
110
-touching the runner. It prints an expected failure's message, a rejected key's hint, or, for
111
-whatever else is left, the defect report captured via `effect-errors`, then re-fails with the
112
-original `Cause`, so tests still match the typed error. `forRunner` (in `cli-main.ts`'s
113
-pipeline) turns what the invocation printed into a `ReportedFailure` and passes failures
114
-already on screen untouched, so the markers take over. `Command.runWith` never renders the
115
-defect path, so appending help text there is not a double-print.
116
-
117
-## argv preprocessing and the executable-prefix contract
118
-
119
-`Command.runWith(rootCommand, { version })` expects argv **without** the node/bun
120
-executable and script path prefix — unlike v3's `Command.run`, which stripped that
121
-prefix internally. `runInvocation` still passes the _full_ `process.argv` into
122
-`runWithConfig` (from `src/commands`); that module is responsible for slicing
123
-`argv.slice(2)` immediately before calling `Command.runWith`. Do not change this
124
-boundary without updating both sides together.
125
-
126
-Composio also does argv rewriting _before_ the parser ever sees the tokens, for cases
127
-`effect/cli`'s lexer cannot express on its own — e.g. `composio run`'s
128
-passthrough of arbitrary `-`-prefixed tokens to the spawned script (the lexer treats
129
-every `-`-prefixed token as an option unless a literal `--` precedes it, and that `--`
130
-split does not propagate into subcommands). Look at `normalizeRunPassthroughArgs` and
131
-its siblings (`normalizeListenStreamFlag`, `normalizeVersionFlag`,
132
-`normalizeHiddenDebugFlags`) in `src/commands/index.ts` for the established pattern
133
-before inventing a new one.
61
+`src/commands/root-help.ts` defines `helpFormatter()`. It starts from `CliOutput.defaultFormatter()`, keeps version output bare, and appends the root overview. `src/commands/index.ts` provides it as `CliOutput.Formatter`. Suggestions remain the framework's own.
62
+
63
+`--version`, `-v`, and `composio version` print the version without a command-name prefix. A subcommand also accepts the version builtin. There is no version-token rewrite. The CLI declares its own log-level flag, while wizard and completion builtins are not enabled.
64
+
65
+## Invocation and output
66
+
67
+`Command.runWith(rootCommand, { version })` receives argv without the executable and script prefix. `runInvocation` receives full argv. `runWithConfig` removes the first two entries immediately before dispatch.
68
+
69
+Compatibility normalization in `src/commands/argv-compat.ts` handles script tails for `run` and bare `listen --stream`. Effect still owns parsing. New command behavior does not need another argv parser.
70
+
71
+`Command.runWith` renders help and parse failures before failing with `CliError.ShowHelp`. Explicit help and version use stdout. Implicit command help and errors use stderr. A parse failure has an exit code of 1 and records the canonical command path with reason `parse_error`. Help, version, parse failures, and groups that only show help skip selected-command hooks.
72
+
73
+A reported failure carries `[Runtime.errorReported] = false`, which suppresses another print. `[Runtime.errorExitCode]` supplies its code. `runInvocation` reports an unreported expected failure or defect once and preserves the original cause for tests. `forRunner` marks what was printed before the runner exits through `Runtime.defaultTeardown`.
74
+
75
+The runner owns signals. Commands cooperate through `ShutdownSignal`. A stopped subscribed listener exits 0. `run` preserves its child's code or signal. Other interrupted commands exit with 128 plus the signal number. Commands do not assign `process.exitCode` or install signal handlers.
76
+
77
+## Verification
78
+
79
+`bun run validate:cli-skills` checks linked excerpts against source, compiles standalone snippets and the CLI tests, runs the documented command example and existing invocation contracts, then checks Effect diagnostics. Its linked examples and behavior tests are described in the `cli-command` skill's command-example reference. These checks certify the examples and selected contracts, not an agent's ability to solve an unseen task.