Developer CLI Reference

The zeq CLI provides direct access to the Zeq OS computation engine from your terminal. It supports single computations, batch processing, operator lookups, precision verification, and multi-step pipelines.

Installation

npm install -g @zeq-os/cli
zeq --version   # zeq-cli 6.3.0

Computation Commands

Run a single operator computation. Every result passes through the KO42 Metric Tensioner and returns a Zeqond timestamp.

zeq compute --operator KO501 --params '{"load": 50000, "length": 10}'

{
  "result": 0.024414,
  "precision": 0.00087,
  "ko42_phase": 0.4217,
  "zeqond": 1719432000.777,
  "operator": "KO501",
  "domain": "engineering",
  "elapsed_ms": 12
}

Flag	Description	Default
--operator	Operator ID (e.g., KO501, QM1)	required
--params	JSON string of input parameters	required
--precision	Target precision threshold	0.001
--frequency	HulyaPulse frequency in Hz	1.287
--format	Output format: json, table, csv	json

# Quantum mechanics computation
zeq compute --operator QM1 --params '{"psi": [1,0], "hamiltonian": "H0"}'
# Fluid dynamics with custom precision
zeq compute --operator FD12 --params '{"velocity": 340, "density": 1.225}' --precision 0.0001
# Table output for quick reading
zeq compute --operator KO501 --params '{"load": 50000, "length": 10}' --format table

Operator Commands

Browse, search, and inspect the full registry of 1,576+ operators across 64 categories.

zeq operators --domain engineering    # List operators in a domain
zeq operators --search "beam"         # Search by keyword
zeq operators --id KO501              # Get operator details

Domain listing response:

{
  "domain": "engineering",
  "count": 10,
  "operators": [
    { "id": "KO501", "name": "Beam Deflection", "equation": "delta = PL^3 / 48EI" },
    { "id": "KO502", "name": "Stress Analysis", "equation": "sigma = F / A" },
    { "id": "KO503", "name": "Buckling Load", "equation": "P_cr = pi^2 EI / L^2" }
  ]
}

Search response:

{
  "query": "beam", "matches": 7,
  "operators": [
    { "id": "KO501", "name": "Beam Deflection", "domain": "engineering" },
    { "id": "KO507", "name": "Beam Vibration", "domain": "engineering" },
    { "id": "EM22", "name": "Gaussian Beam Propagation", "domain": "electromagnetism" }
  ]
}

Operator detail (--id KO501):

{
  "id": "KO501", "name": "Beam Deflection", "domain": "engineering",
  "equation": "delta = PL^3 / 48EI",
  "parameters": [
    { "name": "load", "type": "number", "unit": "N" },
    { "name": "length", "type": "number", "unit": "m" }
  ],
  "precision": "≤0.1%", "version": "6.3.0"
}

Batch Processing

Process multiple computations in parallel. Input is a JSON file containing an array of computation requests.

zeq batch --input beam_loads.json --output analysis.json --parallel 16

Input format (beam_loads.json):

{
  "computations": [
    { "operator": "KO501", "params": { "load": 50000, "length": 10 } },
    { "operator": "KO501", "params": { "load": 75000, "length": 12 } },
    { "operator": "KO502", "params": { "force": 50000, "area": 0.05 } }
  ]
}

Output format (analysis.json):

{
  "total": 3, "succeeded": 3, "failed": 0, "elapsed_ms": 38,
  "results": [
    { "index": 0, "operator": "KO501", "result": 0.024414, "precision": 0.00087 },
    { "index": 1, "operator": "KO501", "result": 0.052734, "precision": 0.00091 },
    { "index": 2, "operator": "KO502", "result": 1000000, "precision": 0.00012 }
  ]
}

Flag	Description	Default
--input	Path to input JSON file	required
--output	Path to output JSON file	stdout
--parallel	Max concurrent computations	8
--stop-on-error	Halt batch on first failure	false

Precision Verification

Validate that all results in a file meet the target precision threshold. The Zeq OS standard is <= 0.1% error.

zeq verify result.json --threshold 0.001

Pass (exit code 0):

{
  "file": "result.json", "threshold": 0.001,
  "total_checked": 3, "all_passed": true, "worst_precision": 0.00091,
  "details": [
    { "index": 0, "precision": 0.00087, "passed": true },
    { "index": 1, "precision": 0.00091, "passed": true }
  ]
}

Fail (exit code 1) -- includes "all_passed": false and a "failures" count:

{
  "total_checked": 3, "all_passed": false, "failures": 1, "worst_precision": 0.0042
}

Flag	Description	Default
--threshold	Maximum acceptable precision value	0.001
--format	Output format: json, table, csv	json
--quiet	Only output pass/fail exit code	false

Pipeline Mode

Chain multiple operators sequentially. The output of each step feeds into the next, enabling multi-stage analysis workflows.

zeq pipeline --chain "KO501 -> KO502 -> KO503" --input structure.json

Input (structure.json):

{
  "load": 50000, "length": 10, "area": 0.05,
  "modulus": 200e9, "moment_of_inertia": 8.33e-6
}

Response:

{
  "pipeline": ["KO501", "KO502", "KO503"], "steps": 3, "elapsed_ms": 47,
  "stages": [
    { "step": 1, "operator": "KO501", "result": 0.024414, "precision": 0.00087 },
    { "step": 2, "operator": "KO502", "result": 1000000, "precision": 0.00012 },
    { "step": 3, "operator": "KO503", "result": 16449340.1, "precision": 0.00065 }
  ],
  "final_result": 16449340.1, "final_precision": 0.00065, "zeqond": 1719432000.777
}

Flag	Description	Default
--chain	Operator sequence separated by ->	required
--input	Path to input JSON file	required
--output	Path to output JSON file	stdout
--fail-fast	Stop pipeline on first operator failure	true

REST API Endpoints

The Zeq OS API Gateway runs on port 4000. All endpoints accept and return JSON.

Base URL: http://localhost:4000

All requests require an Authorization: Bearer $ZEQ_API_KEY header.

POST /api/v1/compute

Single operator computation.

curl -X POST http://localhost:4000/api/v1/compute \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZEQ_API_KEY" \
  -d '{"operator":"KO501","params":{"load":50000,"length":10},"precision":0.001}'

200 Response:

{ "result": 0.024414, "precision": 0.00087, "ko42_phase": 0.4217,
  "zeqond": 1719432000.777, "operator": "KO501", "domain": "engineering" }

400 Error: {"error":"INVALID_OPERATOR","message":"Operator 'XYZ999' not found in registry","code":400}

POST /api/v1/batch

Parallel batch processing.

curl -X POST http://localhost:4000/api/v1/batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZEQ_API_KEY" \
  -d '{"computations":[
    {"operator":"KO501","params":{"load":50000,"length":10}},
    {"operator":"KO502","params":{"force":50000,"area":0.05}}
  ],"parallel":16}'

200 Response:

{
  "total": 2, "succeeded": 2, "failed": 0, "elapsed_ms": 28,
  "results": [
    { "index": 0, "operator": "KO501", "result": 0.024414, "precision": 0.00087 },
    { "index": 1, "operator": "KO502", "result": 1000000, "precision": 0.00012 }
  ]
}

422 Error: {"error":"INVALID_BATCH","message":"Field 'computations' must be a non-empty array","code":422}

GET /api/v1/operators

List and search the operator registry. Supports ?domain=, ?search=, and ?id= query parameters.

curl "http://localhost:4000/api/v1/operators?domain=engineering" \
  -H "Authorization: Bearer $ZEQ_API_KEY"
curl "http://localhost:4000/api/v1/operators?search=beam" \
  -H "Authorization: Bearer $ZEQ_API_KEY"
curl "http://localhost:4000/api/v1/operators?id=KO501" \
  -H "Authorization: Bearer $ZEQ_API_KEY"

200 Response (domain query):

{
  "domain": "engineering", "count": 10,
  "operators": [
    { "id": "KO501", "name": "Beam Deflection", "equation": "delta = PL^3 / 48EI" },
    { "id": "KO502", "name": "Stress Analysis", "equation": "sigma = F / A" }
  ]
}

404 Error: {"error":"DOMAIN_NOT_FOUND","message":"Domain 'unknown_domain' does not exist","code":404}

POST /api/v1/pipeline

Multi-step operator chain with state passing.

curl -X POST http://localhost:4000/api/v1/pipeline \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZEQ_API_KEY" \
  -d '{"chain":["KO501","KO502","KO503"],
    "input":{"load":50000,"length":10,"area":0.05,"modulus":200e9,"moment_of_inertia":8.33e-6},
    "fail_fast":true}'

200 Response:

{ "pipeline": ["KO501","KO502","KO503"], "steps": 3, "elapsed_ms": 47,
  "final_result": 16449340.1, "final_precision": 0.00065, "zeqond": 1719432000.777 }

500 Error: {"error":"PIPELINE_STEP_FAILED","message":"Operator KO502 failed at step 2: missing parameter 'force'","failed_step":2,"code":500}

POST /api/v1/verify

Precision verification for a set of results.

curl -X POST http://localhost:4000/api/v1/verify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZEQ_API_KEY" \
  -d '{"results":[
    {"result":0.024414,"precision":0.00087},
    {"result":1000000,"precision":0.00012}
  ],"threshold":0.001}'

200 Response:

{ "threshold": 0.001, "total_checked": 2, "all_passed": true, "worst_precision": 0.00087 }

400 Error: {"error":"INVALID_THRESHOLD","message":"Threshold must be a positive number","code":400}

Configuration

The CLI and API read configuration from environment variables.

Variable	Description	Default
ZEQ_API_URL	Base URL for the API gateway	http://localhost:4000
ZEQ_API_KEY	Authentication token for API requests	none
ZEQ_LOG_LEVEL	Logging verbosity: debug, info, warn, error	info

export ZEQ_API_URL="https://api.zeq-os.dev"
export ZEQ_API_KEY="zeq_sk_your_key_here"
export ZEQ_LOG_LEVEL="debug"

Or create a .env file in your project root (loaded automatically):

ZEQ_API_URL=https://api.zeq-os.dev
ZEQ_API_KEY=zeq_sk_your_key_here
ZEQ_LOG_LEVEL=info

Output Formats

All CLI commands support three output formats via the --format flag.

JSON (default) -- --format json:

{ "result": 0.024414, "precision": 0.00087, "ko42_phase": 0.4217 }

Table -- --format table:

+----------+-----------+------------+
| result   | precision | ko42_phase |
+----------+-----------+------------+
| 0.024414 | 0.00087   | 0.4217     |
+----------+-----------+------------+

CSV -- --format csv:

result,precision,ko42_phase
0.024414,0.00087,0.4217

CSV is useful for piping into other tools:

zeq batch --input loads.json --format csv | sort -t',' -k2 -n > sorted_by_precision.csv