Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
md 79 lines 5.85 KB
Rendered Raw
1 # Effect CLI in this repository
2
3 The framework lives in `effect/cli`. The installed `effect@^4.1.0` typings determine which interfaces compile. The CLI's registration and invocation modules determine how the repository uses them.
4
5 ## Command registration
6
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
11 The following is the current connections group.
12
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
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
31 ## Flags and arguments
32
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 This standalone framework example demonstrates an optional flag and a positional argument.
36
37 ```ts
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 = {
57 builtIns: [Help, Version],
58 } satisfies Partial<CliConfig.CliConfig.Service>;
59 ```
60
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.