Skip to main content

Zeq CLI (web app)

Looking for the terminal CLI?

→ /cli/ — the sha256-pinned install one-liner, the full command reference, and the single-file Python SDK (zeq.py). This page documents the web CLI app at /apps/zeq-cli/ — the same command core, running in your browser.

The whole kernel as a terminal in your browser — and a clean JSON contract under every command, so you can script it or build an app on top of it.

  • Source → shared/pulse/src/cli/ (web-cli.ts · commands.ts · api-client.ts · help.ts · sdk-surface.ts), bundled by esbuild to /pulse/cli/* and /pulse.js.
  • Three mount points, one codebase → the standalone terminal at /apps/zeq-cli/, the Workbench dock, and the native zeq binary all run the same command core.
  • Substrate operator → KO42 (the 1.287 Hz carrier) rides under every compute.

Three ways to run it​

SurfaceWhereInstall
Web CLI — standalone/apps/zeq-cli/ — a full terminal in the browsernone — just open the page
Web CLI — Workbench dockthe terminal panel under every Workbench stepnone — built in
Native zeq binaryyour own shell; drive any fork with --originone-line self-hosted install (below)

All three run the same commands.ts core, so any recipe works identically across them — and there's no npm in the loop.

Install the native CLI (self-hosted — no npm)​

The native zeq is a single bundled Node script the framework serves and versions itself — the download channel is ours, not a public registry:

curl -fsSL https://zeqapi.com/install.sh | sh
Run the one-liner — don't paste the script

Run that one line in your terminal. Don't open install.sh in the browser and paste its contents — zsh trips over raw script text (zsh: event not found: /bin/sh).

The installer downloads /cli/zeq, fetches the origin's published pin from /cli/zeq.sha256, and verifies the download against it before installing — a mismatch aborts. This drops zeq into ~/.zeq/bin/ and pins this origin as its default. Needs Node 18+ (the binary runs the same commands.ts core as the browser CLI — zero surface drift). Point it at any fork with --origin <url>, $ZEQ_ORIGIN, or a profile. Full install notes, zeq doctor, and profiles: /cli/.

zeq tutorial                          # guided onboarding — 7 steps, progress saved
zeq signup "four memorable words"     # identity + machine + api key from the terminal —
                                      # the wizard issues your ACCOUNT EQUATION (shown once)
zeq                                   # interactive session (REPL): ↑ history, Tab completion
zeq compute NM19 mass=5 acceleration=2 --json
zeq compute GR37 mass=1.98892e30 --json > sun.json && zeq verify sun.json
zeq sdk                               # quickstart wired to YOUR key
echo "compute NM19 mass=5 acceleration=2" | zeq        # stdin / pipe
zeq --script build.zeq                                  # newline/';'-separated script
zeq update                                              # atomic self-update from your origin

Account lifecycle, entirely in the terminal​

  • signup "<phrase>" [name] — the 7-step wizard derives your account equation from the phrase (≥4 meaningful words), registers only its HMAC hash (the server never sees the raw equation), and mints your ZID + state machine + api key. Native installs save it as the active profile, so the very next zeq command runs as your new machine. The issued equation is the credential — shown once, unrecoverable; the phrase is not (the same phrase at a different Zeqond derives a different equation).
  • signin <ZID> [@file | -] — equation login. Account equations are multi-line blobs, so the native CLI takes @equation.txt, stdin (-), or a hidden multi-line paste prompt (finish with a lone . — nothing is echoed, nothing reaches shell history).
  • signout — clear the local session.

Profiles live in ~/.zeqrc; --origin lets one install drive any fork. Prefer to grab the binary directly? It's at https://zeqapi.com/cli/zeq.

What it solves​

Command-line ergonomics for the whole machine: run operators, check your credits and ZEQ envelopes, mint developer keys, spin up new state machines, deploy and fire state contracts, and read the entangled state — all without leaving the prompt. It's a thin, honest transport over the live api-core; there are no hidden routes.

Type help for the full surface, tutorial for the 7-step guided onboarding (progress persists across sessions), or examples for copy-paste recipes.

Programmable — the JSON contract​

Every command resolves to a typed result:

{ "ok": true, "exitCode": 0, "command": "compute", "data": { /* … */ } }
  • Append --json (or -j) to any command for machine-readable output; toggle it persistently with json on / json off.
  • Exit codes: 0 ok · 1 error · 2 usage · 127 unknown command.
  • Headless: on any page that mounts the CLI, window.zeqCli.runJson("compute NM19 mass=5 acceleration=2") returns that JSON contract directly — the seam an app or agent builds on.

Run an operator​

The compute form is a positional operator id followed by scalar key=value inputs. KO42 is applied automatically as the carrier.

compute NM19 mass=5 acceleration=2            # signed CKO envelope, charged in credits
compute NM19 mass=5 acceleration=2 --dry-run  # cost-only preview — nothing charged, no envelope
compute NM19 mass=5 acceleration=2 --json     # same compute, machine-readable

Abbreviated envelope:

operator   : NM19  (carrier KO42)
value      : 10  N
precision  : 0.0004        (≤ 0.001 bound)
zeqond     : 2294548263
phase      : 0.619
proof      : 7f…64-hex ZeqProof

The command surface​

GroupCommands
Onboardingtutorial (7 steps, persisted; next|back|reset|exit|<n>) · signup "<phrase>" [name] · signin <ZID> [@file|-] · sdk · update (sha256-pin-verified) · doctor · completion <zsh|bash>
Identitywhoami · credits (+ credits swap, credits tally) · keys · keys mint <name> [read|write|admin] · keys revoke <id> · machine mint "<equation>" [name] · signout
Trustverify <envelope.json | -> — Ed25519 + independent recompute via the verifier mesh · conformance — the node re-runs the content-hashed golden corpus; the CLI bit-compares (IEEE-754 identity) · chain verify — Proof-of-Elapsed-Zeqonds: native runs the canonical zero-dependency offline verifier (VDF spine, elapsed Zeqonds, binding, hash links, Ed25519)
Computecompute <op> [k=v …] (+ --dry-run, --json) · operators count|list|search|show|categories
Pulse / timepulse · pulse clock · pulse status · time
State contractscontract list|show|deploy <json>|import <json>|fire-now|dry-run|pause|resume|preview|next-fires|export|events
Entangled statestate head|audit|public|explore
Agents / skillsagents (+ spawn|tick|kill|mesh) · skills (+ synthesise)
External APIsapis · apis add <name> <url> · apis test <id> · apis remove <id>
Hosting / PRDsite list|deploy|get|unpublish · prd show|edit|push
Systemhealth · oracle (+ history) · web <url> · version

(help <command> prints deep help for any one of these. This table is a working subset — the full, current reference from the live registry, including examples, families, protocols, skill, context (ZSC), and the native-only profile commands, lives at /cli/commands/.)

Python & other languages​

Python — a single-file SDK, standard library only (no pip, no registry — self-hosted like the CLI itself):

curl -fsSO https://zeqapi.com/cli/zeq.py
from zeq import Zeq

z = Zeq("https://zeqapi.com", key="zeq_ak_...")     # or z.demo_key() for a free taste
env = z.compute("NM19", mass=5, acceleration=2)    # KO42 carrier added automatically
print(env["result"]["value"])                      # 10
print(z.verify(env)["attestation"]["verdict"])     # "agree" — Ed25519 + independent recompute

It also runs as a command: python3 zeq.py pulse · python3 zeq.py compute NM19 mass=5 acceleration=2 · python3 zeq.py verify envelope.json.

Every other language has two first-class paths:

  1. REST — the entire kernel is plain HTTPS + JSON. POST /api/zeq/compute with a Bearer key returns the signed envelope; POST /api/attest verifies it. Works from Go, Rust, Java, C#, R, curl — zeq sdk prints ready-to-paste snippets wired to your key and origin.
  2. The --json bridge — shell out to the CLI: every command returns typed JSON with honest exit codes (0/1/2/127), so subprocess.run(["zeq", "compute", "NM19", "mass=5", "acceleration=2", "--json"]) (or the equivalent in any language) is a complete integration.

Build a machine, end to end​

# 0. Or let the wizard do all of this: signup "<phrase>" creates identity + machine + key
# 1. Spin up a NEW state machine from an equation (the equation is the identity secret)
machine mint "F = m*a" My Machine

# 2. Mint a developer key the app/native client will send as its Bearer
keys mint my-app write

# 3. Deploy a state contract from the catalogue's JSON (or write your own)
contract deploy {"name":"heartbeat","version":"1.0","states":{"running":{"initial":true}},"transitions":[{"from":"running","to":"running","operator":"KO42","proof_required":false,"auto":false,"trigger":{"kind":"recurring","every_zeqonds":60},"post_actions":[{"type":"emit","event":"tick"}]}],"observers":[],"audit_clock":true,"zeqond_tick_rate":1}

# 4. Watch it
contract list
contract next-fires <id>
state explore

Deploying from the ready-made catalogue is easier still — see State Contracts for the template library (including the domain-agnostic Foundations set) and the Contract IDE.

Scripting & integration​

  • Pipe --json output into jq and chain calls.
  • Drive it headlessly from an app via window.zeqCli.runJson(...) — the typed contract + exit codes make it safe to script.
  • Authenticate a headless/native client with a key from keys mint; that Bearer is what /api/zeq/compute expects.

Seeds​

  • Reproducible research CLI — every operator invocation is a signed row on the entangled state; replay the log to reproduce.
  • Agent-driven CLI — an agent reads the JSON contract, decides, and issues the next command.
  • Native build — point a native client at any Zeq origin and the same command surface works against that fork.

Papers​