The best way to control Claude Code, Codex and more from any computer or phone
| 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). |