@kolu/surface-cli reference
Project any @kolu/surface as command-line verbs, so a person, a script or a
cron job drives it from a shell. The argv sibling of
@kolu/surface-mcp: the same surface, the same
default-deny allowlist, the same hand-authored verb table and the same flat
names.
The adapter owns only the generic parts: the argv grammar, the output and exit discipline, and the projection. The domain stays behind the surface, the transport stays with your app, and the run edge stays with your binary.
Building the command tree
Everything here is imported from the root @kolu/surface-cli subpath.
| Export | Subpath | What it is |
|---|---|---|
surfaceCommands(opts) | . | Projects a rooted bundle of surfaces as commands. |
surfaceHelp(opts) | . | The parent command’s description, the help page a person reads. |
READER_NAMES | . | The four names this face mounts that are not verbs. |
SurfaceCliBuildError | . | A malformed projection, refused when the tree is built. |
surfaceCommands(opts)
The projection itself: a bundle of surfaces in, a list of commands out.
const commands = surfaceCommands({
// The unprefixed CORE — its verbs and readers sit at the top of the mounted
// tree. A sibling would go in `surfaces`, and its whole projection would be
// mounted under its key as the first argv word (`example outlines ops_run`).
core: {
surface,
// The default-deny map — the same one the MCP face and the wire faces read.
expose: {
load: "resource",
processes: "resource",
"proc.kill": "tool",
},
},
verbs,
endpoint,
// CLI-only ergonomics, BESIDE the verb table rather than inside it: `pid`
// becomes an argv position, so it is `proc_kill 4321`, not `--pid 4321`.
annotate: { proc_kill: { positional: ["pid"] } },
info: { name: "example" },
});
surfaceCommands(opts): ReadonlyArray<Command>.
- It is a pure function to values. It starts nothing, reads no argv and runs no program.
- It mounts four commands that are not verbs (
get,keys,watch,list). - It cannot see what else you mount beside them, because it does not own the parent. A host subcommand of the same name is invisible here, and the parser answers with whichever it meets first.
- The four names are exported as
READER_NAMESso you can assert against them. Better still, mount the projection under a parent of its own (app surface get load), which claims no name at all.
| Option | Meaning |
|---|---|
core? | the unprefixed root, { surface, expose }. Its verbs and readers sit at the top of the mounted tree |
surfaces? | the siblings, keyed: { [key]: { surface, expose, verbs?, annotate? } }. Each is mounted behind its key as the first argv word |
verbs? | hand-authored SurfaceVerbs at the bundle root, by name |
endpoint | the transport seam: { flags?, resolve } |
annotate? | CLI-only ergonomics by verb name, for the core’s and the bundle root’s verbs: { positional?, render? }. A sibling’s live on the sibling |
info | the binary’s identity: name, which fronts every prose diagnostic |
- The core’s
exposeis the default-deny allowlist, the sameExposeMapevery other face takes, checked against its ownspecat build. - Each sibling’s
exposeis checked against that sibling’s own spec. There is no top-levelexpose: one map per surface. verbsis the same recordserveSurfaceAsMcptakes as its top-leveltools.info.namefronts the usage and unreachable sentences, because a user readsolai: no surface at …and never the package’s name. The refusal body is verbatim JSON with no prefix, since anolai:in front of it would stop it being JSON.
The sibling key is the first argv word
This face takes the same rooted bundle the MCP face does, and composes it the way argv already composes. A sibling’s whole projection is mounted under a subcommand named by its key.
example who_get # the core, bare
example outlines ops_run … # the sibling "outlines"
example outlines get entries # its readers, under the same word
- That is the MCP face’s
outlines_ops_runin argv’s own separator, exactly as<ns>.<verb>is already<ns>_<verb>on both faces. - A sibling’s own
verbsare mounted behind its word like everything else it contributes, sooutlines readis here whatoutlines_readis on the MCP face. Only the bundle-rootverbssit bare at the top. - A verb receives the client of the thing it is declared on: a sibling’s
verbsare handedclients[key], and the bundle-rootverbsare handed the whole{ core, clients }bundle. liststays at the top and describes the whole bundle, one listing of what you can address per face.- Each
listrow’snameis what a caller types, in both arms:outlines ops_runfor a verb, and the full address for a readable member,outlines get nodes. - A
keys/watchrow joins them wherever the collection declares them, since those are different addresses. - The sibling is repeated as a
surfacefield and the member key as amemberfield, so a script can group by either without re-splitting a string this face composed. - Why: Why each face spells a name its own way.
What the projection refuses at build
- A bundle with neither a core nor a sibling, which is not a bundle.
- A sibling that exposes nothing and declares no verbs, which would mount an argv word a user can only ever be refused at.
- A sibling key that would be mounted beside a reader command or a root verb of the same name, which the parser would answer with whichever it met first.
- Everything the single-surface projection already refuses, per scope.
A dialled bundle that carries no client for a sibling is exit 3, not a usage
error: the command line was right, and what is missing is on the far side, the
same arm a dead socket lands on.
The endpoint seam
endpoint is one step, not two: resolve reads the flags once and answers with
the endpoint’s name beside the thunk that opens it. The name is needed exactly
when the dial fails, when there is no connection left to ask. A separate
describe(values) beside a connect(values) is two readings of one decision.
| Field | Meaning |
|---|---|
flags? | the flags every generated command carries (--socket, --url, --host). Optional: omit it when your binary declares them on its own parent instead |
resolve(values) | → Effect<{ where, open }>. values is typed from flags, and answers where beside open |
valuesbeing typed fromflagsmakes renaming a flag a compile error here, rather than anundefinedyour app dials.wherenames the endpoint in the app’s own words.open()dials it, returning{ client, dispose }.openrejecting is the honest answer for “nothing is serving there”, and the rejection’s own words reach the user besidewhere.clientis aRootedSurfaceClientsbundle,{ core?, clients? }, each leg aSurfaceClientCallable, whatbuildSurfaceFace(surface, link.dispatch)mints.disposeis required. A CLI dials, does one thing and exits, and the failure that costs a user something is a socket left open in a shell loop. An in-process host passes() => {}.- A
disposethat rejects is ignored rather than allowed to replace the command’s own verdict. resolvereturns an Effect. A resolution order that can come up empty (“no$APP_SOCKET, no runtime dir, nothing to dial”) fails it. That failure, or a throw out of it, is exit3: the same arm as a failed dial, rather than a defect exiting on the runtime’s default.- A host whose flags sit on its own parent reads them from the parent’s context here.
- Why: A face offers only what it can do.
Where the endpoint flags live
That is your decision, and it must not be both at once.
- Declare them in
endpoint.flagsand they are merged into every generated command’s own config, soapp proc_kill 4321 --socket /run/x.sockparses. - Declare them on your own parent instead (
Command.withSharedFlags), soapp --socket X proc_kill 4321parses too. A flag declared on a subcommand only parses after that subcommand’s name. - On that second route, omit
flagshere and read them back inresolve. This face then adds none and nothing collides. - Effect CLI refuses a parent/child flag of the same name outright
(
DuplicateOption).
surfaceHelp(opts)
The parent command’s description: the help page a person reads.
- It is pure over the same options, so it cannot describe a verb the projection does not mount. A group naming a command nothing answers to is refused at build.
- Pipe it through
Command.withDescription. - Passing
helptosurfaceCommandsthen unlists the verbs, so the page is the listing rather than one of two.
READER_NAMES
The four names this face mounts that are not verbs: get · keys · watch ·
list. It is the fact a host needs to check its own subcommands against, since
surfaceCommands cannot see them.
SurfaceCliBuildError
A malformed projection, refused when the tree is built: a positional naming no field, a flag-name collision, a field that cannot be a flag.
How a surface member becomes a command
| Surface member | argv |
|---|---|
procedure "<ns>.<verb>" exposed as a tool | <ns>_<verb> [--field …], the same flat name the MCP face uses, from the same toolName |
a bespoke SurfaceVerb | <name> …, by the same rule over its input |
| cell | get <member> [--follow] |
| stream · event | get <member> [input] [--follow] |
| collection | get <member> <key> [--follow] · keys <member> [--follow] (only when it declares keys) · watch <member> (only when it declares deltas) |
| always | list, this face’s tools/list, answered from the projection itself, so it dials nothing |
A verb’s name is flat and identical on both faces, so a verb cannot mean one thing to an agent and another to a terminal.
--followturns a one-shot read into the subscription itself: one ndjson line per frame, until the stream ends or you interrupt it.- Without it a read takes the opening snapshot frame and stops, which is what every snapshot-then-deltas member opens with.
watchis a delta stream with no one-shot reading, so it takes no--followand always streams.- A host whose transport cannot push declares
endpoint.streaming: false. Thenwatchis not mounted and--followis not declared anywhere, so--helplists only flags that work. - Every other reader still works under that subtraction, because each of them takes the opening snapshot frame and interrupts the rest.
- An event is the one member with no snapshot to take: it is occurrences over
time, so a one-shot
getof it would wait for ever. It is refused (exit 2) naming--follow, which is the only honest reading of an event. - Why: A face offers only what it can do.
Reading one item of a collection
A one-shot read of a collection item is bounded against both membership and a deadline, so a key that is not there answers instead of hanging on a subscription that will never yield. Both bounds are always armed, and they answer differently on purpose.
| answer | exit | means | is it evidence? |
|---|---|---|---|
{"present":true,…} | 0 | the item’s current value | — |
{"present":false,"why":"absent"} | 0 | membership says it is not a member | yes — the item is gone |
| a line on stderr naming the member, the key and the budget | 3 | the read ran out of time | no — a fact about the read, not the item |
"absent"is a completed read whose answer is “not there”, so it is a data frame at exit0like any other answer.- A deadline is not an answer at all: nothing said whether the item is there. A quiet producer, or a collection with no key set to resolve against, reaches it while the item is perfectly alive.
- A deadline therefore takes the endpoint’s arm, exit
3, the same code as a dial that never landed, because in both nothing answered. - A caller reaping on absence acts on the payload it got at exit
0and never has to guess. At exit3there is no payload to misread. - Why: The same split on the command line.
list
listanswers from the projection itself, so it dials nothing. It accepts the endpoint flags anyway, so a script looping over the verbs does not break on the one that would have refused them.- Its aligned table is a summary like any other, so
--jsonasks for the data. - It builds its table when it runs, off the same advertised document the flag table was built from, so no other invocation pays for it and the two cannot describe different verbs.
- Each verb’s
inputis that document in the reading this face takes. For an object input it is the document the MCP face publishes too. - For a scalar, array or union input the wire carries the value under one
property, and MCP publishes that wrapper. argv binds the bare value to a
<value>positional and has no--valueflag. Solistreports the inner node: the shape you can actually type.
Flags and input
| Export | Subpath | What it is |
|---|---|---|
flagsOf(schema, opts?) | . | The argv half of the bridge: an input schema to an InputProjection. |
JSON_FLAG · INPUT_FLAG | . | The two flag names, as data. |
flagsOf(schema, opts?)
Turns a verb’s input schema into the flags that carry it.
flagsOfis driven by the verb’s advertised input schema (inputSchema), not by a second walk of the Effect AST. A field that is a--flaghere is the same field with the same type on the MCP face, so neither can drift from the other’s idea of what the verb takes.- It answers an
InputProjection: the command config, theadvertiseddocument it was built from, plus theassemble(values, stdin)that reads a parsed config back into the verb’s encoded input. advertisedis handed back so a caller that wants it does not walk the schema a second time.stdinis an Effect, described rather than read, so the descriptor is touched only on the--input -path and no caller has to ask first.
| Property | argv |
|---|---|
string | --name <text> (an enum becomes a choice, listed in --help) |
integer · number | --name <n> |
boolean | --name / --no-name, a tristate, so “I did not say” and “I said false” stay different |
| array of scalars | --name <v>, repeated |
Record<string, string> | --name k=v, repeated |
<scalar> | null | --name <value>, plus the word null to clear it |
| anything deeper | --name '<json>', the field’s own JSON |
| a non-object input | the bare <value> positional |
Required fields and defaults
- Every param is optional to the parser, because
--inputcarries the whole input as an alternative to the field flags. A required field projected as a parser-required param would make that escape hatch unspellable: the command would be refused before the assembler saw that--inputwas the answer. - Requiredness is enforced one layer up instead, where both inputs are in view.
A missing required field is named by this face, on exit 2, and only when
--inputis absent. - A
defaultis applied at assembly rather than by the parser, becauseFlag.withDefaultmakes a field the caller never typed indistinguishable from one they did. - Both facts reach
--helpin the line rather than in the shape: a required field says(required), a defaulted one says(default: …).
Clearing a nullable field
A field that can be cleared takes the value, or the word. A removable field is
usually spelled <scalar> | null.
- It takes the scalar’s own spelling, and the bare word
nullclears it. - That is a magic word, and the ambiguity is bounded and named on the flag’s own
help line. A string whose value is literally
nullgoes through--input, which takes the field’s JSON and has no ambiguity at all. - A nullable enum keeps its choice list and gains the word, so
--helplists everything the flag takes. - Only exactly
<scalar> | nullmoves. A wider union has no one obvious spelling and keeps the JSON flag, where a plain line of text is--desc '"the brass ones"'.
Flag names
- Names are not transformed. The flag is the field, spelled the same:
--filePath, not--file-path. - A transformation would be a second name for one thing, and it is not reversible for every field name.
- A field that cannot be spelled as a command-line name is refused when the tree is built, naming the field. It is never shipped as a command nobody can type.
JSON_FLAG · INPUT_FLAG
The two flag names, as data: the whole answer as JSON, and the whole input as JSON.
- Every verb takes
--input '{…}', the whole input as data, or--input -to read it from stdin. --inputis an alternative to the field flags, never a supplement. Passing both is a usage error naming them, rather than a silent precedence nobody can see.--jsonon any command asks for its full JSON output instead of the summary a renderer would print. One name cannot mean the input on the way in and the output on the way out.
Output discipline
- stdout is data. One JSON value for a one-shot read, one compact JSON line per frame for anything streamed. It is indented only when stdout is a terminal, which decides the spacing of a JSON answer and nothing else, never which answer it is.
- One exception is not this package’s. A refusal from the CLI library is
rendered by Effect CLI itself: a rejected flag, an unknown subcommand, a value
outside a choice. It prints the usage document on stdout and the reason on
stderr, before
runEdgemaps it to exit 2. - This face’s own usage errors are one line on stderr and an empty stdout, so a script that captures stdout should branch on the exit code before reading it.
- stderr is prose, with one deliberate exception: a verb’s declared refusal is JSON on stderr, because it is data you can act on that is nonetheless not the verb’s answer.
- A hung-up reader is a complete run.
watch nodes | head -1closes the pipe under a live subscription; that is the reader getting what it asked for, so it exits 0. Every other write failure is reported. - The predicate this arm decides on is exported as
isConsumerHangup, for a host whose own writes sit outside this projection. - An
annotate.renderrenders a verb’s output as text for a human, applied unless the caller passed--json. The flag is the only thing that decides.
Exit codes
EXIT is exported as data, so a host’s docs and a driving script’s tests can
name the codes rather than re-spell the integers.
| Code | Meaning |
|---|---|
0 | the verb did what it was asked |
1 | the verb’s declared error: its refusal, as JSON on stderr |
2 | a usage error: the request never left the process |
3 | nothing is serving the endpoint (the five cases below) |
130 | interrupted (Ctrl-C) |
Exit 3 covers a dial that failed, a transport that died mid-call, a read whose
member opened and closed without its snapshot, and a bounded item read that ran
out of time without ever finding out. It also covers your own resolve
refusing, because “nothing to dial” is the same answer one step earlier.
1and2are the split that matters. A refusal is an answer from the far side and a usage error never reached it, so a loop that retries on1must not retry on2.3is separate again because it is about the endpoint rather than the request. It is the one code that means “try a different--socket”.- A failure carries its own
Runtime.errorExitCode, so the host’sNodeRuntime.runMainteardown reads the number straight off it. - Nothing in this package calls
process.exit.130is Effect’s own: a Ctrl-C interrupts the fiber, the stream’s finalizers unsubscribe, and the connection is released on the way out.
The run edge
One arm of the matrix is not this package’s to raise, which is what these exports are for.
| Export | Subpath | What it is |
|---|---|---|
EXIT | . | the matrix above, as data |
reportingRunEdge | . | the whole run edge as one combinator |
runEdge(error) | . | the decision underneath, for a host that owns its own catch |
isConsumerHangup(failure) | . | did the consumer hang up, or did the write genuinely fail |
SurfaceCliFailure | . | the failure class carrying both the text and the code |
SurfaceCliOptions · SurfaceCliCore · SurfaceCliSibling · EndpointSeam · ResolvedEndpoint · SurfaceCliConnection · VerbAnnotation · InputProjection · Assembled · ProjectedCommand · RunEdgeReport | . | types |
reportingRunEdge
The whole run edge as one combinator. Pipe your program through it at the run
edge, so the exit matrix is true of a real binary, and pair it with runMain’s
disableErrorReporting: true:
NodeRuntime.runMain(
Command.run(root, { version }).pipe(
reportingRunEdge,
Effect.provide(NodeServices.layer),
),
{ disableErrorReporting: true },
)
- It catches the cause, not the failure. A defect is not a failure, so
Effect.catchnever sees one, and the runtime then reports it itself through the default logger, which writes to stdout: a log line in the middle of the data channel. - That case is not exotic. The server’s own per-request refusal crosses the wire
as a defect whenever the
serving face withholds a
member this face’s map offers, and it reaches you as exit
1with the refusal as JSON, like any other declared error. - An interrupt passes through untouched (Ctrl-C, whose
130is the runtime’s own teardown). - The arm’s line is written before the re-fail, because every failure here marks itself already-reported. A host that re-fails without writing it exits with the right code and says nothing at all.
- The flag stays yours because it is
runMain’s own argument. Without it Effect prints a second, differently-worded copy of the line.
runEdge(error)
The decision underneath reportingRunEdge, exported for a host that owns its
own catch.
runEdge(error) → RunEdgeReport: { kind: "write", stderr, failure } or
{ kind: "silent", failure }.
- It is a sum, so “the library already printed this” is a state with a name rather than an empty string every host has to test for.
- It is what makes exit 2 true of a real binary. A refusal from the CLI library (a rejected flag, an unknown subcommand, a value outside a choice) is a usage error by every reading of the matrix. It arrives already rendered and carrying no code of ours, so left alone it takes whatever your catch-all does with it.
--helpand--versionare action flags in the pinnedeffect: they print and return success, so they never reach it.
isConsumerHangup(failure)
Did the consumer hang up (… | head -1), or did the write genuinely fail: the
predicate behind the complete-run discipline above.
- It reads the errno both flat (
{code:"EPIPE"}) and nested ({cause:{code:"EPIPE"}}, the shape a wrapped sink failure actually raises), so a host’s own stdout writes ask the one question once.
SurfaceCliFailure
The failure class carrying both the text and the code.
RootedSurfaceClients · SurfaceCliConnection
The framework’s rules stay the framework’s: messageOf is
@kolu/surface/errors’s,
and SurfaceClientCallable is
@kolu/surface/client’s.
One concept, one import path.
SurfaceClientCallableis the shape each leg of the bundleresolve’sopenreturns has.RootedSurfaceClientsis the one exception, re-exported here for the same reason the MCP face re-exports it:SurfaceCliConnectioncarries it, and a host writing anendpoint.openhas to be able to import the name it names.SurfaceCliConnectionis an alias of that module’sOwnedSurfaceConnection, which is the same shape the MCP face holds, so one connection factory can feed both faces.
What the CLI offers and what the server answers
The serving face’s FaceExposure
decides what the server answers; this ExposeMap decides what the CLI offers.
It is the same arrangement serveSurfaceAsMcp has with restrictHandlers, and
the same reason: a client’s table is ergonomics, never security.
The step-by-step is in How to expose a surface to a terminal.