@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
mdx 118 lines 4.14 KB
Raw
1 ---
2 title: CLI
3 description: Run an Api's calls from a terminal, as a person or an agent, against the deployed Api.
4 ---
5
6 An Api's typed client works from Effect code. A person at a terminal, a shell script or a coding agent wants a command line instead. `toCli` from `@alchemy.run/domain/Cli` builds an [Effect CLI](https://effect.website) command from the Api you already have. It calls the deployed Api over its HTTP protocol, so the server runs the same middleware and checks as for every other client.
7
8 ## Build the command
9
10 ```typescript title="packages/cli/src/bank.ts"
11 import * as Domain from "@alchemy.run/domain";
12 import { toCli } from "@alchemy.run/domain/Cli";
13 import { BunRuntime, BunServices } from "@effect/platform-bun";
14 import * as Command from "effect/cli/Command";
15 import * as Config from "effect/Config";
16 import * as Effect from "effect/Effect";
17 import * as FetchHttpClient from "effect/http/FetchHttpClient";
18 import * as Layer from "effect/Layer";
19 import * as Redacted from "effect/Redacted";
20 import { CustomerApi } from "@bank/domain/CustomerApi.api";
21
22 const bank = toCli(CustomerApi, {
23 name: "bank",
24 // The session middleware runs on the server; the CLI sends its token.
25 headers: Config.redacted("BANK_TOKEN").pipe(
26 Effect.map((token) => ({ authorization: `Bearer ${Redacted.value(token)}` })),
27 ),
28 });
29
30 Command.run(bank, { version: "1.0.0" }).pipe(
31 Effect.provide(
32 Layer.mergeAll(
33 Domain.protocolHttp("https://bank.example.com/api").pipe(Layer.provide(FetchHttpClient.layer)),
34 BunServices.layer,
35 ),
36 ),
37 BunRuntime.runMain,
38 );
39 ```
40
41 `toCli` is its own module, so an app that builds no CLI never loads `effect/cli`.
42
43 ## Send a command
44
45 Each command is a subcommand in kebab-case, and its payload and input fields are flags. It prints the receipt as JSON:
46
47 ```sh
48 $ bank deposit-money --target a-1 --amount 1000
49 {
50 "reply": { "balance": 1000 },
51 "stream": "Account/a-1",
52 "version": 1
53 }
54 ```
55
56 `--json` takes the same fields as one object, and any flag you also give wins over it:
57
58 ```sh
59 $ bank deposit-money --json '{"target":"a-1","amount":1000}' --amount 50
60 ```
61
62 It also takes the call's own wire payload, with the input nested, as the HTTP API and MCP tools take it:
63
64 ```sh
65 $ bank deposit-money --json '{"target":"a-1","input":{"amount":1000}}'
66 ```
67
68 ## Read a view
69
70 A view, a stream or an aggregate is a subcommand with one subcommand per read, `get`, `peek`, `list` or `snapshot`:
71
72 ```sh
73 $ bank account-summary get --key a-1
74 { "balance": 1000 }
75 $ bank statement list --key a-1 --order desc --take 20
76 ```
77
78 `watch` and `events` stream, so they aren't commands.
79
80 ## Pass structured values
81
82 A string, a number, a boolean or a set of string literals takes a typed flag. Anything else, such as a struct, an array or a date, takes its JSON:
83
84 ```sh
85 $ bank account-summary get --key a-1 --at-least '{"stream":"Account/a-1","version":1}'
86 ```
87
88 A command whose input has a field named like a payload field, such as its own `target`, takes its whole input as `--input` JSON instead.
89
90 ## Read failures
91
92 The CLI decodes the input against the call's schema before it sends anything, so a bad flag fails without a request:
93
94 ```sh
95 $ bank deposit-money --amount 1000 # exit code 1, nothing sent
96 # stderr: Invalid input for deposit-money, naming the missing `target`
97 ```
98
99 A rejection, or an error of the call's middleware, goes to stderr as its wire JSON, and the run fails with `CallRejected`, exiting with code 1:
100
101 ```sh
102 $ bank withdraw-money --target a-1 --amount 5000 # exit code 1
103 { "_tag": "InsufficientFunds", "balance": 1000, "requested": 5000 }
104 ```
105
106 ## Names the CLI refuses
107
108 Every run dies with a `DefinitionError` when two things the Api serves get one command name, or when a field would take a flag the CLI reserves (`--json`, `--help`, `--version`, `--wizard`, `--completions`, `--log-level`):
109
110 ```typescript
111 class Reserved extends Domain.Command("Reserved", {
112 target: AccountId,
113 input: { json: Schema.String },
114 }) {}
115 // bank reserved ... -> DefinitionError: field `json` would be the flag --json, which the CLI reserves
116 ```
117
118 To give a terminal fewer calls, give it its own Api, as in [Give each kind of client its own Api](/domain/api#give-each-kind-of-client-its-own-api).