The terminal CLI — zeq

The zeq command is a client for your hosted machine — it computes against the framework on our nodes, not on your laptop. This page is the complete command reference: every name the CLI registers, what it does, and the endpoint or action behind it.

One engine, two surfaces. The browser CLI you get on any node page (including /studio/) and the native binary are the same code. The native entry point (apps/zeq-dev/public/pulse/cli/node-entry.js) imports runHeadless from web-cli.js, which imports dispatch and register from commands.js — the same registry the browser mounts. A command that works in one works in the other, minus the handful that need a DOM (noted below).

Install

The framework serves its own download channel — the installer, the single-file zeq binary at /cli/zeq, and its own npm registry at /registry. No npmjs, no third party in the loop. The installer downloads the binary, then verifies it against the published sha256 pin at /cli/zeq.sha256 and aborts on a mismatch:

curl -fsSL https://cli.zeq.dev/install.sh | sh

That is the line https://zeq.me/install.html publishes, and the one to use today.

warning

The per-node install.sh is currently unusable as a one-liner

Every node also serves its own /install.sh, meant to carry that node's origin baked in. Right now it does not: https://zeq.me/install.sh and https://zeqsdk.com/install.sh both ship the build placeholder unsubstituted —

ORIGIN="${ZEQ_ORIGIN:-__ZEQ_BASE_URL__}"

— so piping either straight to sh tries to download __ZEQ_BASE_URL__/cli/zeq and fails. Until the substitution is fixed, either use the cli.zeq.dev line above, or pass the origin yourself:

curl -fsSL https://zeq.me/install.sh | ZEQ_ORIGIN=https://zeq.me sh

Note that the two installers produce different clients. cli.zeq.dev/install.sh installs zeqcli (a zeqcli.mjs bundle, bound to machine.zeq.dev, overridable with ZEQ_NODE). The per-node install.sh installs zeq into ~/.zeq/bin with the sha256 pin, seeds ~/.zeqrc, and is the one this reference is written against. Prefer the node installer once its origin is substituted.

Node 18+ is required either way — the binary is one bundled Node script. Two more clients ship from the same channel:

curl -fsSO https://zeq.me/cli/zeq.py          # Python, one file, stdlib only
npm config set @zeq:registry https://zeq.me/registry && npm install @zeq/sdk

Then let the guided tutorial walk you the whole way:

zeq tutorial   # account → machine → first compute → verify · progress saved

Invocation and global flags

zeq                                interactive session (REPL) — history, tab completion
zeq <command> [args] [--json]      run one command
zeq --script <file>                run a newline/';'-separated script
echo "<command>" | zeq             run piped commands, one per line

Flag	Effect
--origin <url>	Target any Zeq fork. Default $ZEQ_ORIGIN, else the origin seeded at install.
--key <key>	Authenticate with a zeq_ak_… / zsm_… key for this run.
--profile <name>	Use a saved profile (see profile).
--json / -j	Machine-readable output and a typed exit code.
--keep-going	In scripts and pipes, don't stop on the first error.
--help / -h, --version / -v	Usage, version.

Config lives at ~/.zeqrc; REPL history at ~/.zeq/history, scrubbed — a signin line is truncated after the ZID so the equation never reaches disk.

Signing in

There are three ways in, and which one you use decides what the rest of the surface will let you do.

zeq signup "kepler orbits traced in winter starlight"   # new identity
zeq signin ZEQ7MHRBRXTAD9Q1N15KM102G2CJWG               # existing — prompts hidden
zeq mint                                                 # no account: a free demo key

signup runs the wizard that derives your account equation from the phrase (four or more meaningful words), registers only its hash, and mints your ZID, state machine and API key. The equation is shown once — there is no password reset. signin fetches your salt and posts a candidate hash; on the native CLI, omit the equation and it is prompted hidden, never echoed and never stored.

Session versus key

The CLI authenticates two different ways, and the split matters:

	Browser CLI	Native CLI
How it authenticates	Same-origin session cookie from signin / login, plus any saved profile key	Authorization: Bearer from --key, --profile, or the seeded config
Owner-gated routes	Cookie only	The machine's admin key is accepted, scoped to that one machine

Owner-gated (cookie-only in the browser) commands are whoami, credits / wallet, send, keys, prd, state / chain, and site / page publishing. Everything the compute path touches — compute, operators, contract, agents, skills — runs on a zeq_ak_ key alone, which is why a headless machine only ever needs keys mint.

The economy group commands need a signed-in ZID: coins, bi / contribute (except policy and census) and audit mine all refuse with "not signed in — run login (or signup) first". transparency, mesh and coins conservation are public reads and work signed out.

The command surface

68 registered command names — 61 from commands.js and 7 from econ-commands.js, which registers onto the same registry. Five of the 68 are aliases (close, wallet, transfer, chain, contribute), so there are 63 distinct behaviours. Every name below was read from the register() calls in the repo source and confirmed byte-identical against what https://zeq.me/pulse/cli/commands.js and /pulse/cli/econ-commands.js actually serve.

Run help for the in-terminal card and help <command> for deep help on one.

Onboarding and meta — 12

Command	Purpose	Behind it
tutorial	Guided 7-step onboarding: the clock, mint your identity and machine, first compute, verify the receipt, the entangled state, link the SDK. Progress saved across sessions.	Drives the other commands
help [command]	The full command card, or deep help for one.	Local
examples	20+ copy-paste real examples across every category.	Local
docs <topic>	Open the SDK page for a topic. Browser opens a tab; native prints the URL. Bare docs lists the topics.	Local topic map
hello	A real one-shot demo — runs compute NM19 mass=5 acceleration=2 and prints the CKO envelope.	POST /api/zeq/compute
hello universe	Three operators across QM, NM and GR in one command (QM5, NM21, GR37). Costs 3 computes.	POST /api/zeq/compute ×3
version	CLI version and framework constants — 1.287 Hz, τ = 0.777 s, ≤0.1%, operator count, α.	Local
welcome	Re-render the welcome card and probe the node.	Health probe
clear	Clear the feed. History is retained.	Local
history [clear]	The last 50 commands; ↑/↓ recalls them.	Local
exit · close	Leave the terminal. Browser closes the drawer; the native REPL ends the session.	Local (close is an alias)
open	Prints that the CLI is already open.	Local

Shell behaviour — 5

Command	Purpose	Behind it
json [on|off|status]	Toggle machine-readable JSON output for every command. Equivalent to --json per call.	Local runtime flag
script <cmd> ; <cmd> …	Run several commands in one line, ;- or newline-separated. Stops at the first error unless --keep-going. Nested script is refused.	Local runner
completion <zsh|bash>	Print a shell completion script for the native CLI. The REPL has Tab completion built in.	Local
theme [name]	Switch CLI theme — cryptopunk, paper, mono.	Local
update	Self-update the installed binary. Native only — in the browser you are always on the deployed version.	Native self-update hook

Identity, session and secrets — 9

Command	Purpose	Behind it
signup "<phrase>" [name]	Create an account: the wizard derives your account equation, registers its hash, mints your ZID, machine and key. Equation shown once.	POST /api/zeq/wizard/auth-bootstrap → POST /api/zeq-auth/register-v3
signin <ZID> ["equation"]	Sign in to an existing identity. Native: omit the equation for a hidden prompt.	GET /api/zeq-auth/salt/:zid → POST /api/zeq-auth/login-v3
login	Interactive sign-in with your .zeq recovery file plus PIN, decrypted in your browser and never uploaded. Browser only.	Local HITE decrypt → POST /api/zeq-auth/login-v3
signout	Sign out of this browser session. The machine survives.	Local
whoami	Current ZID, machine slug, tier and ZEQ balance.	GET /api/tally/account/:zid
machine mint "<equation>" [name]	Mint a new state machine and ZID from an equation you supply — the manual genesis flow. The equation is hashed client-side.	POST /api/zeq-auth/register-v3
keys	List this machine's developer API keys — prefixes and metadata, never raw values.	GET /api/chain/:slug/api-keys
keys mint <name> [read|write|admin]	Mint a headless API key — the Bearer an app or the native CLI uses. Raw key shown once.	POST /api/chain/:slug/api-keys
keys revoke <id>	Revoke a key by id.	DELETE /api/chain/:slug/api-keys/:id
profile [list|add <name> <key> [origin]|use|current|rm|clear]	Saved key + origin profiles, so one CLI can drive several machines or forks. Keys are masked in the listing.	Local store; GET /api/chain/state-machines
settings	One card gathering identity, balance and plan, key count, vault size, publish default, messaging and anchor config.	GET /api/tally/account/:zid, /api/tally/settings/publish-default, /api/zeq-vault/list, /api/msg/settings

Vaults — 2

Two different stores, easy to confuse. vault is the per-account encrypted entry store; context is ZSC, the Zeq Secure Context that replaces .env for production secrets — every read of which lands an entangled-state audit row.

Command	Purpose	Behind it
vault [list|get <id>|save <name> <value>|sync]	Your encrypted entries. Values are stored encrypted; the list shows names and metadata only.	/api/zeq-vault/list, /api/zeq-vault/:id, POST /api/zeq-vault/save, GET /api/vault/sync
context [list|info|set|rotate|grant|revoke|audit|delete]	ZSC secrets: set encrypts with AES-256-GCM under the PBKDF2-HULYAS key, rotate re-encrypts with a fresh IV, grant/revoke manage per-ZID permissions, audit <NAME> [N] reads the audit rows, delete is irreversible. Bare context = context list.	/api/zsc/list, /info/:name, POST /api/zsc/set, /rotate/:name, /grant/:name, /revoke/:name, /audit/:name, DELETE /api/zsc/:name

Credits and value — 5

Credits are non-transferable compute fuel; envelopes are the transferable receipt. The distinction is the whole of the economy at a glance.

Command	Purpose	Behind it
credits · wallet	Your credits and ZEQ envelopes, daily spend, recent ledger.	GET /api/tally/credits/:zid (wallet is an alias)
credits swap <btc|eth> <amount>	Swap BTC/ETH into ZEQ from the foundation pot.	Tally swap
credits tally	Open the /tally/ balance viewer.	Local
mint	Mint a free demo key — no account, no signup. Solves a Landauer proof-of-work; rate-limited per network. Refuses if you are already signed in or already hold one.	POST /api/demo-key/mint
send	List the envelope coins you hold.	GET /api/tally/envelopes/:zid
send <token_id> <ZID> [--public|--private] · transfer	Transfer a whole envelope. Visibility follows your machine default unless you override it; the value moves either way.	POST /api/tally/envelopes/transfer (transfer is an alias)
send default [public|private]	View or set this machine's publish default for transfers. Default private.	GET/POST /api/tally/settings/publish-default
send claims · send claim <token_id> <ZID> [origin] · send claim publish <token_id>	Coins homed on another domain: list them, move one onward via your stored claim ticket (no account needed on the home node), or publish its receipt here as a home-anchored public row.	/api/tally/claims/:zid, POST /api/tally/claims/transfer, POST /api/tally/claims/publish

Clock — 2

Command	Purpose	Behind it
pulse · pulse clock	Bare pulse reads the node's live Zeqond, phase and HulyaPulse status beside the local clock. clock renders the tick locally, with no call.	GET /api/zeq/pulse
time	Local time, Unix epoch and the current Zeqond with its phase, side by side.	Local clock — no call

Compute and operators — 4

Command	Purpose	Behind it
compute <op> [k=v …]	Run an operator and get a signed CKO envelope. KO42 is applied automatically. --json for machine-readable output. Complexity-priced in credits.	POST /api/zeq/compute
compute <op> [k=v …] --dry-run	Cost-only preview. Nothing charged, no envelope minted.	GET /api/tally/cost?operators=…
operators [count|list [domain]|search <q>|show <id>|categories|community|propose]	Discover the catalogue: total count, paginated listing by domain, fuzzy search, one operator's detail card, all categories, and the community-proposed set.	GET /api/operators, /api/operators/categories, /api/community-operators, POST /api/community-operators/propose
verify <envelope.json | ->	Re-check a result's ZeqProof from the envelope alone — the fastest way to confirm a result you were handed is genuine without trusting the source.	Local re-check; GET /api/identity, POST /api/attest
conformance	Prove this node computes the golden physics: fetch the content-hashed vector corpus, have the node re-run every vector through its recompute path, and bit-compare (IEEE-754 identity). A single mutated constant fails it.	GET /conformance-golden-vectors.json, GET /api/zeq/conformance, GET /api/chain/seal

Agents and skills — 3

Command	Purpose	Behind it
agents [spawn "<directive>"|tick <id>|kill <id>|mesh <id>]	List, spawn, manually tick, kill an LLM hyper-agent, or show its mesh links. Spawn and tick are complexity-priced; kill writes a contract transition.	/api/zeq/agent/list, POST /api/zeq/agent/spawn, /tick/:id, /kill/:id, /mesh/:id
skills [synthesise "<intent>"]	List synthesised mini-procedures on this machine, or synthesise a new one from natural-language intent.	GET /api/zeq/agent/skills, POST /api/zeq/agent/skills/synthesise
skill [prompt|md|manifest|install <client>|verify|info|endpoints]	The kernel skill — the boot prompt any LLM client can read. Fetch the raw prompt, the full SKILL.md, the JSON manifest with version + sha256, a per-client install snippet, or the sha256 to cross-check your local copy.	/api/kernel/prompt, /api/kernel/skill.md, /api/kernel/skill

Contracts, chain and external APIs — 4

Command	Purpose	Behind it
contract [list|show|deploy|import|export|fire-now|pause|resume|dry-run|preview|next-fires|events|templates|template <id>]	The full contract lifecycle on your machine: deploy from a definition or a template, fire, pause, resume, simulate without committing, preview the reactor, predict the next five firings, export/import JSON, read emit events.	/api/chain/:slug/contracts…, /api/contracts/templates…, /api/chain/:slug/events
state [head|audit [--limit N]|public|explore|verify] · chain	The hash-linked entangled state: top of the log, recent audit rows, the public-tier view, the combined explorer.	GET /api/chain/:slug/explore (chain is an alias)
state verify · chain verify	Proof-of-Elapsed-Zeqonds. Native runs the canonical zero-dependency offline verifier — VDF spine, elapsed Zeqonds, binding, hash links, Ed25519 — and exits non-zero on failure. Browser recomputes the hash-link leg only (tamper-evidence) and points at the full check.	Native verify-zeq-chain.mjs; browser GET /api/chain/seal
apis [list|add <name> <url>|test <id>|remove <id>]	Register external APIs so contracts and agents can call them, and invoke one to test it.	/api/zeq/apis/:slug, POST …/:id/test, DELETE …/:id

Build and host — 3

Command	Purpose	Behind it
site [list|deploy <page> <base64-html> [title]|get <page>|unpublish <page>]	Publish, fetch and retire live pages on your machine — the same path the Workbench uses. html is btoa(yourHTML). Owner-gated.	/api/state-machines/:slug/pages, …/:page/publish, …/:page/unpublish
page [list|new|edit|open|rm]	The build workflow on top of site: new scaffolds a starter page that runs a real computation against /api/zeq/prove on load, then edits, opens or removes it. Needs a ZID and a machine.	Same page endpoints
prd [show|edit "<markdown>"|push|set]	The machine's PRD — the build directive the agent reads. Show it, replace it, or push it to the agent.	GET/PUT /api/zeq/agent/prd/:slug

The API surface — 6

Command	Purpose	Behind it
api · api groups · api total · api show <group> · api search <q>	Browse the node's endpoint surface from the terminal: every capability domain and namespace with its endpoint counts, open a group's SDK page, or search for one.	Generated catalog (sdk-surface.js)
api <GET|POST|PUT|PATCH|DELETE|QUERY> /api/… [json-body]	Call any public endpoint directly with your key. QUERY is the RFC 10008 safe GET-with-a-body. /api/admin/* is refused from the terminal.	Direct fetch
catalog [q]	Search all public endpoints by substring, with method and description.	POST /api/mcp → the zeq_api_catalog tool
explorer	Open the API Explorer app on this node. With arguments it falls through to catalog.	/apps/api-explorer/, /api/endpoints
endpoints	Convenience: dispatches to catalog when given a query, to api when bare.	See above
protocols [themes|domains|show <n|name>|search <q>]	The protocol taxonomy — thematic chapters with their anchor operators, the domain list, and search.	Local taxonomy
families [list|show <slug>]	The operator-family taxonomy with ID ranges, and the SDK page for one family.	Local taxonomy

Node health and utility — 6

Command	Purpose	Behind it
health	api-core health probe.	GET /api/health
doctor	Diagnose this install: origin health, clock drift in Zeqonds, auth state, the binary against the origin's published sha256 pin, and the conformance surface. Every ✗ carries its remedy.	GET /api/health, /api/zeq/pulse, /api/zeq/conformance, /cli/zeq.sha256
oracle [history N]	Transparency Oracle now — supply, foundation, BTC/ETH price, active machines — or the last N Zeqonds of supply state.	GET /api/transparency/now, /api/transparency/history
web <url>	Fetch a URL through the SDK proxy, same-origin.	Proxy fetch
sdk	SDK quickstart wired to your key and this origin — REST curl, JavaScript, Python, the MCP server, the kernel skill and the native install.	Local, using your stored key
zone	Stub. Prints that the zone API now lives in the Pulse tab.	No call

Economy, mesh and audit — 7

These are the econ-commands.js group. They are same-origin: api/… hits this node, so a fork answers for itself. Ticks are always rendered from genesis (Z+N), never as a raw Unix-scale number.

Command	Purpose	Behind it
transparency [now|pool|breakdown|revenue|history|snapshot <zeqond>]	The truthful economy fields — treasury_pool, issuer_undistributed, foundation_envelopes, zeqond_now. now is the canonical read. Public.	GET /api/tally/transparency, /api/pool, /api/transparency/breakdown, /revenue, /history, /snapshot?zeqond=
coins <balance|conservation|mint <amt>|split <id> <amt>|merge <a> <b>|transfer <id> <zid>|export <id>|redeem <blob>|height <id>>	ZEQ Coin as a bearer token: mint from balance, split, merge, transfer, export to hold offline, redeem on any mesh node, read a coin's spend-seq height. conservation proves nothing was created or lost — and is the one subcommand that is public; the rest need a ZID.	/api/tally/envelopes/:zid, …/conservation, POST …/mint-from-balance, …/:id/split, …/merge, …/transfer, …/:id/export, …/redeem, …/:id/height
bi [status|policy|census|mode <on|off>|bond <amt>|release|heartbeat] · contribute	Basic Income / contribute-to-earn: 95% of issuance pro-rata to CPU contributors. mode on opts this account in; heartbeat proves a live contributor seat. policy and census are public.	/api/contribute/policy, /census, /status, POST /mode, /bond, /release, /heartbeat (contribute is an alias)
mesh [quorum|peers|self|issuance [zeqond]|anchor|replication|status]	The super-machine mesh: WORM quorum and divergence, peer heights, this node's own identity, what was issued at a given tick, anchors, and the replication cursor. Public.	/api/worm/quorum, /api/mesh/peers, /api/mesh/self, /api/mesh/issuance/at, /api/worm/anchor, /replication, /status
audit [mine|explore <slug>|events <slug>|at <slug> <zeqond>|source list]	Audit-everything: every framework action lands on the caller's own machine chain. Read your rows, explore another machine's, list its events, time-machine a read to a given Zeqond, or list the source-audit adapters.	/api/chain/:slug/explore, /events, /at?zeqond=, /api/zeq/audit-source/list
plan [show [zid]|set <zid> <free|starter|pro|enterprise>]	Read or change an account's plan. Admin-only — it calls an /api/admin/* route, so it will not answer for an ordinary key, and the change is audited on the admin's own chain.	GET/POST /api/admin/accounts/:zid/plan

note

plan reaches a route the api command blocks

api <METHOD> /api/admin/… is refused from the terminal by design. plan calls /api/admin/accounts/:zid/plan through the shared client instead, so it is gated by the server's admin check rather than by the CLI. Expect it to fail for a normal account.

Exit codes

With --json, commands return a typed exit code, so scripts can branch on them:

Code	Meaning
0	Success
1	Runtime failure — a call failed, a verification failed, a chain link broke
2	Usage error — wrong or missing arguments, or an empty command
127	Unknown command (with a did-you-mean suggestion)

zeq --script <file> and piped input stop at the first non-zero code unless you pass --keep-going; the process exits with the last failing code.

Read next

• The MCP server — the same node as callable tools, for agents.
• Language SDKs — when you want a typed client inside an app.
• Quickstart — the same first steps, shown as raw HTTP calls.
• Proofs — what zeq verify and zeq chain verify are actually checking.
• The economy at a glance — the two ledgers the economy commands read.