CLI

The cemi command is the package's command-line entrypoint. It handles the local gateway, workspace, child-process orchestration, and contract verification.

Command summary

Command	Purpose
cemi gateway	Start the local gateway and serve the workspace UI
cemi view	Open the workspace without creating a run
cemi start -- <cmd>	Create a run context, inject env vars, open workspace, and execute a command
cemi verify	Evaluate a run against a contract and exit with pass/fail
cemi stop	Stop background processes started by the CLI
cemi config	Display local CLI configuration
cemi config set <key> <value>	Persist a value in ~/.cemi/config.json
cemi help	Show the command list

---

cemi gateway

Starts the local gateway in the foreground. Serves the embedded workspace UI and the JSON API from disk.

cemi gateway

Custom save directory:

cemi gateway --save-dir /tmp/cemi-demo

Custom port:

cemi gateway --port 3142 --save-dir /tmp/cemi-demo

The gateway binds to 127.0.0.1 and serves:

• Workspace UI at http://127.0.0.1:3141/workspace
• JSON API at http://127.0.0.1:3141/api/...

cemi gateway does not open a browser automatically. Use cemi view if you want the browser opened.

---

cemi view

Opens the workspace in a browser. Starts the gateway in the foreground, waits for it to be ready, then opens a browser tab.

cemi view

Custom save directory:

cemi view --save-dir .cemi

Dev UI mode (opens the Vite dev server instead of the embedded build — for source contributors only):

cemi view --dev-ui

---

cemi start

The main orchestration command. Prepares a local run environment, opens the workspace, injects environment variables, and then runs your training or benchmark command as a child process.

cemi start -- python train.py

With an explicit project and save directory:

cemi start --project compression-engine --save-dir .cemi -- python -m engine.main --config benchmark.yaml

The CLI:

1. Ensures a local gateway is running (starts one in the background if needed)
2. Creates a local run ID
3. Injects the following into the child process environment:
4. CEMI_PROJECT_ID
5. CEMI_RUN_ID
6. CEMI_SAVE_DIR
7. CEMI_LOCAL_SERVER_URL
8. Opens the workspace in a browser
9. Runs the command and waits for it to exit

Your script should call create_writer_from_env() to pick up these injected variables automatically.

---

cemi verify

Evaluates a run against a contract and exits with a machine-readable result. This is the command that turns CEMI from a metrics dashboard into a deployment verification tool.

cemi verify --contract contract.json --run <run_id>

With a custom save directory and JSON output:

cemi verify \
  --contract contract.json \
  --run <run_id> \
  --save-dir .cemi \
  --output json \
  --output-file result.json

Flags

Flag	Description
--contract FILE	Path to the contract JSON file
--run RUN_ID	Run ID to evaluate
--save-dir DIR	Save directory to load runs from (default: .cemi)
--output FORMAT	Output format: table (default) or json
--output-file FILE	Write output to a file instead of stdout

Exit codes

Code	Meaning
0	All gates passed
1	One or more gates failed
2	Contract or run could not be parsed

These exit codes make cemi verify usable directly in CI pipelines:

- name: Verify deployment contract
  run: cemi verify --contract contract.json --run $RUN_ID --output json --output-file result.json

Table output (default)

Contract: accuracy-sla   Run: local-abc123
┌─────────────────┬──────────┬──────────┬───────────┬────────┐
│ Gate            │ Role     │ Metric   │ Value     │ Result │
├─────────────────┼──────────┼──────────┼───────────┼────────┤
│ accuracy-gate   │ quality  │ accuracy │ 0.934     │ PASS   │
│ latency-budget  │ perf.    │ lat_p99  │ 18.4 ms   │ PASS   │
│ memory-limit    │ resource │ peak_ram │ 480 MB    │ FAIL   │
└─────────────────┴──────────┴──────────┴───────────┴────────┘
Verdict: FAIL  (1 gate failed)

JSON output

{
  "contract_id": "accuracy-sla",
  "run_id": "local-abc123",
  "verdict": "fail",
  "generated_at": "2026-04-13T10:00:00Z",
  "gates": [
    {
      "id": "accuracy-gate",
      "role": "quality",
      "metric": "accuracy",
      "verdict": "pass",
      "run_value": 0.934,
      "explain": "0.934 >= 0.90"
    },
    {
      "id": "memory-limit",
      "role": "resource",
      "metric": "peak_ram_mb",
      "verdict": "fail",
      "run_value": 480,
      "explain": "480 > 400"
    }
  ]
}

See Gateway and Contract for the contract schema.

---

cemi stop

Stops background services started by cemi start --dev-ui or cemi view --dev-ui. Reads PID files from ~/.cemi/pids/.

cemi stop

---

cemi config

Display current configuration:

cemi config

Set the default owner:

cemi config set owner "Jane Doe"

Set the default log directory:

cemi config set logdir "/data/cemi"

Configuration is stored in ~/.cemi/config.json.