跳至主要内容

Zeq CLI

The whole kernel from your terminal — 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

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.

zeq version
zeq profile add main <your zeq_ak_ key>    # then: zeq profile use main
zeq compute NM19 mass=5 acceleration=2 --json
echo "compute NM19 mass=5 acceleration=2" | zeq        # stdin / pipe
zeq --script build.zeq                                  # newline/';'-separated script

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 a 5-step walkthrough, 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 guaranteed)
zeqond     : 2294548263
phase      : 0.619
proof      : 7f…64-hex ZeqProof

The command surface​

GroupCommands
Identitywhoami · credits (+ credits swap, credits tally) · keys · keys mint <name> [read|write|admin] · keys revoke <id> · machine mint "<equation>" [name] · signout
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.)

Build a machine, end to end​

# 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​