Skip to content

The zeocore command

zeocore lets another service or language use zeocore without importing Python: the ZEOconnect Broker and WEB, a TypeScript pipeline, a shell script. Each call reads JSON on stdin and writes JSON lines on stdout, the result last.

$ zeocore help --json
$ zeocore version
{"cli_protocol": "1", "commands": ["artifact", "connections", "digest", "doctor", "help", "invoke", "login", "logout", "release", "schema", "validate", "version", "whoami"], "ok": true, "schema": "zeocore.version/v1", "zeoconnect_protocol": "1", "zeocore": "…"}
$ zeocore schema list
$ zeocore schema hosted.operation-request
$ echo '{"code": "RATE_LIMITED", "message": "slow down"}' | zeocore validate connections.normalized-error
$ echo '{"b": 1, "a": [1, 2]}' | zeocore digest
{"ok": true, "schema": "zeocore.digest/v1", "sha256": "sha256:…"}

An agent starts with zeocore help --json, the machine catalogue (zeocore.help/v1): every command, its arguments, what it reads on stdin, the exit family and the schema its result names. A test holds the catalogue to each command's parser, so it can't drift from the code. Every answer is JSON already, so zeocore help without --json answers the same.

Commands

Command Reads stdin Answers
help [--json] no the machine catalogue
version no the release, cli_protocol, the ZEOconnect protocol, the commands
doctor [--profile P] no is this machine ready: Python, session store, pairing, ZEOCONNECT_URL, extras; see below
schema list no the stable schema names
schema <name> no that contract as JSON Schema 2020-12
validate <name> yes {"ok": true, "value": …}, the normalized value, or {"ok": false, "errors": [{"loc": […], "type": …}]}
digest yes the sha256 of the value's RFC 8785 canonical bytes
login, logout, whoami, connections, invoke, artifact get see below the ZEOconnect client, for a product running as its own service user; not for seats, which use zeo
release sign, release verify, release tree-digest, release verify-event, release check-approval yes the shared signing step, a bundle's tree digest, the GitHub attestation of a published release event (or, with mechanism: pinned_key, a private repository's pinned-key signature; needs zeocore[release-keys]), and whether a release commit was approved; see Sign and verify a release
release pypi plan \| admit \| apply \| approve \| reconcile \| verify yes the PyPI adapter; see Release to PyPI

Is this machine ready? zeocore doctor

zeocore doctor answers what an agent would otherwise find out by failing. It is local and read-only: no network call, nothing written, and never a token, a path or an environment value in the answer.

Each check is one event line, {"event": "check", "check": …, "ok": …, "message": …}. The result is last, with ok, outcome (ready or not_ready), failing (the names of the checks that failed) and checks (the same lines, for a caller that doesn't stream). A failing check carries next, the exact command or step that fixes it, and who when someone other than the caller must act.

Check Passes when When it fails, next is
python Python meets the package's floor, 3.14 uv tool install --python 3.14 zeocore
zeoconnect_url ZEOCONNECT_URL is unset or an allowed Broker origin unset it, or set ZEOCONNECT_DEVELOPMENT=1 for a development Broker
session_store the Keychain (asked for at most 5 s), or the file ZEOCORE_SESSION_FILE names, is readable how to make the store usable, for that refusal
pairing this profile holds a grant that hasn't expired zeocore login, by who: a person, who approves it in ZEOconnect
extra:github zeocore release can load pip install 'zeocore[github]'

Exit 0 when every check passes, 20 when any fails (for doctor, 20 means not ready), 2 for a --profile that can't be used, found before any check prints. Checks print as they finish. A failing zeoconnect_url or session_store also fails pairing, which then says it was not checked: with a bad origin zeocore login would fail too, so no person is named.

The ZEOconnect client

Not for seats: seats use zeo

These commands are for products, and only when the product runs as its own macOS service user, zs-<product> (the first is zs-newsroom-intake). They are not a seat interface: a seat reaches the Broker only through ZEO-RT's front door, with its zeo command (ZEOCORE-SOW-27), and they are deprecated for seats now.

From Broker contract 1.4, the Broker accepts a product's grant only from that product's own service user. From any other user, rodbot and a product author's own login included, it is refused with app_identity_unverified. A seat's grant is refused with door_required, and a grant adopted as no principal with no_principal. zeocore can't tell these apart on one machine, so the Broker enforces them, not this command.

Products reach the ZEOconnect Broker through these commands instead of writing a Broker client of their own. An app never holds a provider token. The machine holds only that app's own device grant, in the macOS Keychain.

Command Reads stdin Does
login [--device-name N] no Pairs this device. Emits {"event": "pair", "verification_url", "user_code", "expires_at"}, waits for a person to approve in ZEOconnect, then stores the grant.
logout no Revokes the grant and deletes it.
whoami no Says whether this profile is paired, with its device id and expiry. Local only: no network, never a token.
connections [--service S] no Lists the grant's connections.
invoke <operation_id> --connection C [--occurrence L] [--wait SECONDS \| --wait-approval SECONDS] the arguments object Runs one operation and answers the Broker's response plus request_key and retry.
artifact get --out PATH an artifact descriptor Downloads an output to a new file and checks its size and digest.

Refusals from Broker contract 1.4.0. Each comes before custody, so nothing happened, and the same grant can't succeed. The answer names it in outcome, with retry: "none" and the way back in message:

outcome Means The way back
door_required a seat's grant seats use zeo, ZEO-RT's front door
app_identity_unverified a product's grant from another macOS user run the product as its own service user, zs-<product>
no_principal a grant adopted as no principal the owner adopts the grant as the product's principal

A stop answers outcome: "stopped" with its control and scope, and a Broker that doesn't speak this zeocore's protocol answers outcome: "upgrade_required".

A product's service user: the named session file. By the operator's ruling of 2026-10-12, a product running as its own service user (zs-<product>) may keep its grant in one named file instead of a Keychain, by setting ZEOCORE_SESSION_FILE to an absolute path, for example in its launchd definition. It is opt-in, never a fallback: without that variable the Keychain is the only store, and a Keychain that can't be read is still exit 12. zeocore refuses the file, with exit 12, unless all of these hold:

  • the directory is owned by that user, mode 0700;
  • the path has no symbolic link;
  • no directory above it is writable by another user unless it is sticky;
  • the file is a regular file owned by that user, with no group or other access.

Writes are atomic, at 0600. The file records the Broker it was paired with and is never sent to another. A session file names one grant, so it can't be combined with --profile. ZEO-RT qualifies it on the real account.

Every client command takes --profile P, or reads ZEOCORE_PROFILE, to choose the grant, so one machine can run several apps, each paired on its own. A profile is attribution, not a security boundary: all profiles of one macOS user can read each other. With no usable Keychain, a command fails closed with exit 12. There is no plaintext fallback.

The origin is the production Broker unless ZEOCONNECT_URL names another. Development origins also need ZEOCONNECT_DEVELOPMENT=1.

Invoking

  • The idempotency key is the request. request_key is derived from the connection, the operation, the canonical arguments and --occurrence, so running the same invocation again is an exact replay of the stored outcome and never a second act. Use a new --occurrence for a deliberate new act.
  • --wait-approval SECONDS handles an effect that needs a person's approval. It emits {"event": "approval", "approval_url", "request_key"} once, then asks again with the same key every 5 s until the answer is no longer approval_required, or the time runs out (exit 10).
  • --wait SECONDS (1 to 3600) waits until the outcome is final, so an agent never has to poll. It asks again with the same key every 5 s through a person's approval, an answer still in flight, and ZEOconnect being unavailable. It emits each kind of wait once: the approval event, then {"event": "waiting", "reason": "in_flight" | "unavailable", "request_key"}. The exit is the final answer's own. At the deadline it is the last answer's: 10 or 11. An ambiguous answer (13), or a Broker that didn't answer at all, is never retried. --wait and --wait-approval can't be combined.
  • retry says what another attempt needs:
  • same_request: ask again as it is;
  • new_occurrence: the failure is recorded, so a retry is a new act;
  • none: change the request.
  • Exit codes:
  • 0 confirmed;
  • 10 approval_required;
  • 11 still in flight, or ZEOconnect is unavailable;
  • 12 not paired, or no session store;
  • 13 ambiguous, or no answer arrived (asking again with the same request is safe);
  • 20 refused, failed_safe or stopped.

Rules every command keeps (cli_protocol 1)

  • stdout is JSON lines and nothing else. Events (a pairing code, a doctor check, an approval link, waiting) carry an event key. The result is always the last line: it carries ok and schema (zeocore.<command>/v1; zeocore.usage/v1 for an unknown command; zeocore.internal/v1 for an internal error) and never event. zeocore schema <name> is the one exception: its answer is the contract itself, named by its own $schema and $id. A command with no events prints exactly one line. Diagnostics go to stderr.
  • Input is strict JSON: no duplicate keys, no NaN or infinities, at most 1 MiB.
  • A failing message ends with the next action. A failing answer's message names what failed, then, after a ;, what to do next: a command to run, a flag to set, or who has to act (for example this device is not paired with ZEOconnect; run zeocore login). Where a layer below gave no next step, the answer adds one chosen by outcome, so every refusal, held and waiting answer carries one. The next action is fixed text and never quotes the input. Only a message zeocore wrote itself, ending in its own action, skips the added one; a message built from an error's text always gets it, however it ends.
  • ZEOCORE_DEBUG=1 explains an internal error. An internal error's message says to rerun the same command with ZEOCORE_DEBUG=1 and report the command, the zeocore version and that output. With the variable set to 1, stderr gets the exception's type and where it happened (file, line and function of each frame). Never its text, arguments, locals or the input. The file paths are absolute, so they can include the installing user's home directory: that is why it is an explicit opt-in, and stderr only. stdout stays one JSON line.
  • Errors never echo input. A validation error is its location and type only. A location keeps declared field names and list positions; any other key (inside a free-form object such as arguments, or an unknown extra) shows as *.
  • Exit status is one family, the same numbers as the YouTube publish command's:
Code Meaning
0 done
2 invalid input or command; nothing was sent
10 approval required
11 waiting: try the same request later
12 not paired: run zeocore login
13 ambiguous; never retried by the command
20 held or refused, including a value that doesn't match its schema; for doctor, not ready
1 internal error in zeocore: {"ok": false, "outcome": "internal", "message": …}, with no detail of the input. For an operation, treat it like 13

A change to these rules is a new cli_protocol, announced like a contract change.

Schemas

Name Contract
connections.normalized-error NormalizedError
connections.observation-artifact ObservationArtifact
hosted.artifact-descriptor HostedArtifactDescriptor
hosted.availability-snapshot AvailabilitySnapshot
hosted.connection-summary one GET /v1/connections entry (HostedConnectionWire)
hosted.operation-request HostedOperationRequest
hosted.operation-response HostedOperationResponse
revolut.account Revolut Account
revolut.transaction-page Revolut TransactionPage
ui.result-card UiCardResult: zeo.ui-result/v1 with one read-only card (zeocore-SOW-42); zeo.ui-result/v1 names it too
proof.report Internal ProofReport, alias zeo.proof-report/v1 (sow: zeocore-SOW-45). A valid structure is not verified supporting evidence or current clearance.
library.view-v2 Metadata-only citation view, alias zeo.library-view/v2; strict 4096-byte input, no receipt pointer or content. NFC and UTF-8 byte limits require the validator; schema x-maxUtf8Bytes is descriptive, not standard JSON Schema enforcement.
access.receipt-v2 Separate citation access receipt, alias zeo.access-receipt/v2; acyclic digest binds exact view bytes and a distinct-read reservation. Shape is not current-read permission.

The proof report is internal, not the library-owned outward proof-view. Its prf_ identity hashes RFC8785 of all immutable fields except proof_id; the returned-byte digest includes that field. The draft binding hashes RFC8785 of the exact four strings from_name, subject, plain_text, html, without Unicode normalization. Item/selection/RAW identifiers are format-checked opaque references, never resolved by this model. Markdown hashes bind exact LF UTF-8 revision bytes, retained hashes exact RAW bytes, and artifact hashes their exact representation bytes. Unknown or unresolved evidence stays unchecked, never verified because its identifier parsed. Current lifecycle, stop/read outcomes and fresh receipts are separate: an unperformed check is not_checked. This static schema performs no reads or freshness checks and authorizes neither creating nor sending a draft. Metadata is NFC with pinned Unicode16 codepoint checks; a host predating Unicode16 conservatively refuses metadata characters unknown to its normalization database. Evidence is unchanged.

  • ui.result-card is the one-card subset of zeo.ui-result/v1. The wire tag zeo.ui-result/v1 selects it in zeocore validate and zeocore schema. The document must have exactly one component of kind card with an empty action_refs; a table, chart, form, button or second component is refused as unsupported, never coerced. Limits are measured on the JSON text as received (response 262,144 bytes, component 65,536 bytes, depth 9); text classes S, D and L are bounded in UTF-8 bytes under the pinned Unicode 16.0.0 tables. The JSON Schema's maxLength counts characters, which is a looser bound than bytes: only zeocore validate applies the byte bounds. The exported schema is necessary, not sufficient: it never refuses a document the validator accepts, and it refuses the structural errors (unknown key, missing key, wrong type for a fact's value_type, an explicit null for an optional key, a second component, any other kind, a non-empty action_refs, counts, id and timestamp shapes). What only zeocore validate checks: UTF-8 byte lengths and the Unicode 16.0.0 text classes, calendar validity (leap days), observed_at not after produced_at and expires_at after observed_at, negative zero and the digits-equal-scale rule, that an integer is written as an integer token (1.0 is an integer to JSON Schema), duplicate keys, the response and component byte limits and the depth bound. Do not treat plain JSON Schema validation as equivalent to zeocore validate.
  • A name is a promise. It keeps naming the same contract until a major version. New names are additive.
  • The files are committed in the repository under contracts/zeocore-v1/ as <name>.schema.json, for callers that vendor files and run no zeocore at all. A test fails if a model and its committed schema drift.
  • Not listed yet: Revolut's TransactionQuery. Its wire field is from (Broker contract §6), but the model's field is from_ with no alias, so its schema would name the wrong field.

Digests

digest is the sha256 of the value's RFC 8785 (JCS) canonical bytes, prefixed sha256:. Two parties that each canonicalize the same JSON value get the same digest without sharing code.

Python consumers of untrusted proof-report bytes use zeo_core.contracts.proof.parse_proof_report(data); it refuses duplicate keys, invalid UTF-8 and non-JSON constants before model validation. Direct ProofReport.model_validate_json is not the strict byte entry point. The caller must bound transport input. The CLI has its separate 1 MiB input cap; a report within all model field bounds can exceed it and cannot use the CLI transport. The valid-maximal fixture exercises populated fields, not every numeric bound. Excerpt-cache digests identify only the cached exact text; they do not establish its relation to a claim or a source span. That verification needs the pinned view bytes at the producer and is not performed by this data-only model.