Driving a CLI
Ten states, not two booleans: what Finexia knows about a command-line tool, how a sign-in is started, and what is deliberately refused.
Shipped in the current build. You can do this on your own machine today.
The settings screen used to know two things about a provider: installed, and usable. Two booleans describe a provider at rest. They say nothing about what happens while it is being connected, and they prevent nothing — a connect button on a missing binary, a test launched on a disconnected provider, a cancellation shown for a provider that was doing nothing. Three screens that two booleans let you build without complaint.
#The ten states
They do not fold into each other. Not installed, installed but signed out, and the connection failed are three different situations asking for three different gestures.
| State | What it means | What you do |
|---|---|---|
| unknown | Nothing has been read yet. Not yet looked at is not the same as absent. | Nothing — this state lasts as long as the first read. |
| detecting | Finexia is looking at the path and asking the CLI about its session. | Wait. |
| missing | No binary of that name is on the path. | Install the vendor CLI. |
| signed_out | The binary answers; the session does not. The most common state, and the least well read — it looks like it works. | Sign in. |
| connecting | A sign-in is running. An address is shown only if the CLI printed one and it passed the address filter. | Finish the sign-in in your browser. |
| ready | The binary is there and its session holds. | Nothing. Run a desk. |
| testing | A real request is in flight. | Wait. |
| failed | The last attempt failed, and Finexia says why in its own words — never in the CLI’s. | Read the reason; it names the gesture. |
| timed_out | The attempt ran past its deadline. Distinct from failed: there is nothing to fix, there is something to retry. | Try again. |
| cancelled | You stopped it. Distinct from a failure — nobody broke anything. | Nothing. |
EvidenceOne transition function is the only door between these states. A gesture that makes no sense from the current state is refused there, not somewhere further down where it would already have started a process.
#Signing in
A sign-in is a fixed argument list attached to a vendor identifier, and the front end chooses among three known identifiers — it does not choose a program. There is no string to escape because there is no interpreter, and no argument to validate because no argument comes from the interface.
| Vendor | Sign-in | Where it is allowed to take you |
|---|---|---|
| Anthropic | A fixed sub-command of the claude binary | Two declared hosts, matched whole |
| OpenAI | A fixed sub-command of the codex binary | Two declared hosts, matched whole |
| None — the CLI has no sign-in command | Nowhere. Finexia shows a sentence instead of a button |
LimitThat last row is a fact, not an oversight. Giving a CLI a connect button that leads nowhere is exactly the kind of promise this screen exists to remove.
#The address filter
A sign-in prints many things. One of them may be a page you have to open. Four conditions decide whether Finexia opens it, and failing any one of them means the address does not come through at all — not redacted, not shown greyed out: it does not come through.
- It is https. Nothing else is opened.
- Its host is one of the hosts declared for that vendor, compared in full — a look-alike that merely ends with the right suffix is refused.
- It carries no embedded credentials in the authority. A browser would display them in its address bar, and that is the shape of a forged sign-in page.
- The host is read with the same parser the HTTP client uses. Two parsers that disagree about where a hostname ends are a door, and that door has been found before.
#The deadline
A connection is given three minutes: enough to open a browser, sign in and pass a second factor. Shorter, and an honest sign-in expires under the operator’s fingers; longer, and a CLI waiting for input nobody will type holds a slot for nothing.
EvidenceWhat decides success is a real probe, not the exit code of the sign-in command. A sign-in can exit cleanly and leave no session behind, and a screen that trusted the exit code would report a connection that does not exist.
#What a run actually passes to the CLI
Beyond the sign-in, a card starts the CLI with a fixed set of flags: a structured input and output stream, the declaration of the local tool server, a strict configuration mode, and an explicit approval list. Two of them deserve a sentence.
- Strict configuration mode isolates more than the tool declaration. Measured on 2026-08-26, two of the operator’s own session hooks were injecting an output style and an unrelated tool into the context of a financial analysis card. The same flag also closes the file boundary — without it, one card read a neighbouring card’s journal.
- The approval list on the command line is not the same thing as the deny list in the deposited file. They do the opposite of one another, and both are needed: the deposited approval is ignored until the workspace is approved, which a data room created seconds ago never is.
#Sources
- The provider manifest, generated by the coreFinexiaInternal document, not published
- Finexia OS — product state at 0.0.23FinexiaInternal document, not published