# ALU GUBI CLI — How to Use

Operator guide for the **encrypted binary** distribution of [ALU GUBI](https://github.com/shyamalschandra/alu_gubi)
(Gamified Universal Basic Income for GOs and NGOs). You install via Homebrew; you do not build from source.

**Project of record:** https://github.com/shyamalschandra/alu_gubi  
**Website:** https://shyamalschandra.github.io/alu-gubi-cli/  
**License:** [CCSL-1.0a](https://shyamalschandra.github.io/alu-gubi-cli/license/) · conditioned by [OpenAI ChatGPT note](https://chatgpt.com/share/6a5a6001-5d88-83ea-ac88-7090df3d8e30)  
**The 11 Commandments:** https://shyamalschandra.github.io/alu-gubi-cli/#vision  
**Step-by-step on the site:** [How to use the binaries](https://shyamalschandra.github.io/alu-gubi-cli/#howto) · [Herd demo simulator](https://shyamalschandra.github.io/alu-gubi-cli/#herd-howto)  
**Technical paper:** [alu-gubi-cli.pdf](alu-gubi-cli.pdf) · [embedded preview](https://shyamalschandra.github.io/alu-gubi-cli/#paper)  
**Reference manual:** [reference_manual.pdf](reference_manual.pdf) · [embedded preview](https://shyamalschandra.github.io/alu-gubi-cli/#reference-manual)
**Demo media:** [screenshots + herd movie](https://shyamalschandra.github.io/alu-gubi-cli/#demo-media)

---

## 1. What you are running

ALU GUBI CLI is a single executable that bundles:

| Component | What it does for you |
|-----------|----------------------|
| **In-memory SQLite** | Stores citizens, coupons, points — no Postgres install |
| **GubiVault** | Secrets (API keys, tokens) encrypted at rest |
| **GubiMoby** | Starts **Ollama** without Docker Desktop |
| **Dual Ollama** | `llama3.3` (creative) + `gemma3:1b` (agentic quests) |
| **Bindi ledger** | Tamper-evident attestations on a hash-linked chain |
| **REST API** | HTTP control plane on port **8080** (default) |
| **Async RT scheduler** | Deadline classes, admission control, timeout enforcement, low-power idle policy |
| **PlankServices** | Modular ROS-style pub/sub by Shyamal Chandra — RT topics + logging at every edge |
| **Unicode TUI** | Terminal dashboard (`ui`) |

Data is **ephemeral by default** (in-memory DB). Restarting the process clears local state unless you set `DATABASE_URL` to a file-backed SQLite URL.

---

## 2. Requirements

- **macOS arm64** (Apple Silicon) for the published encrypted binary today
- **Homebrew 6+** (for tap + trust + install)
- **Ollama** (recommended; formula suggests `brew install ollama` if missing)
- Network for first-time model pulls (`ollama-pull`)

Optional for live Census/BLS-style integrations:

- Set `LIVE_INTEGRATIONS=1` and configure secrets (see [§8 Environment variables](#8-environment-variables))

---

## 3. Install

### Option A — Homebrew tap (recommended)

```bash
brew tap shyamalschandra/alu-gubi-cli
brew trust --formula shyamalschandra/alu-gubi-cli/alu-gubi-cli
brew install alu-gubi-cli
```

Tap repo: https://github.com/shyamalschandra/homebrew-alu-gubi-cli

Also install the API driver from the same tap:

```bash
brew trust --formula shyamalschandra/alu-gubi-cli/alu-gubi-driver
brew install alu-gubi-driver
```

### Verify install

```bash
alu-gubi-cli --help
alu-gubi-driver --help
alu-gubi-cli brew          # print tap / trust / install commands again
```

---

## 4. First-time operator checklist

Run these in order on a new machine:

```bash
# 1) Dashboard — confirm stack status (emoji + color bars)
alu-gubi-cli ui

# 2) Start Ollama via GubiMoby (pure Rust; no docker compose)
alu-gubi-cli moby-up -d

# 3) Confirm Ollama container / process
alu-gubi-cli moby-ps

# 4) Pull default AI models (llama3.3 + gemma3:1b)
alu-gubi-cli ollama-pull

# 5) Apply DB schema (in-memory unless DATABASE_URL set)
alu-gubi-cli migrate

# 6) Inspect scheduler contract (offline)
alu-gubi-cli rt-status --profile balanced

# 7) Start the REST API with deadline policy
alu-gubi-cli serve --rt-profile balanced
# alternatives: --rt-profile eco | performance | hard-realtime
```

In another terminal:

```bash
curl -s http://127.0.0.1:8080/health
```

Expected: `{"status":"ok"}`

**Live refresh dashboard:**

```bash
alu-gubi-cli ui --watch
```

### Async real-time scheduler

ALU GUBI uses a cooperative async scheduler policy for application-level real-time behavior:

- **Classes:** critical, interactive, background, idle
- **Profiles:** `eco`, `balanced`, `performance`, `hard-realtime`
- **Controls:** admission slots, deadline/budget timeouts, low-power idle sleep/yield, storage batch hints
- **Telemetry:** `GET /v1/rt/status`, `GET /v1/rt/contract`, `alu-gubi-cli rt-status`, `alu-gubi-driver rt-status`

```bash
export GUBI_RT_PROFILE=hard-realtime
export GUBI_RT_MAX_PARALLEL=4
export GUBI_RT_IDLE_SLEEP_MS=0
export GUBI_RT_STORAGE_BATCH_BYTES=8192
alu-gubi-cli serve --rt-profile hard-realtime --rt-max-parallel 4
```

**Hard-real-time boundary:** these controls enforce deterministic budgets inside the async application. Kernel-enforced hard real-time requires an RTOS/PREEMPT_RT deployment, CPU isolation, and elevated scheduling policy.

### PlankServices (invented by Shyamal Chandra)

ALU GUBI modules communicate over **PlankServices** — a modular, ROS-inspired publish/subscribe **fog network** with a **herd**:

- **Fog network:** many local edge nodes (generators, COL, coupons, points, bindi, …) mesh through Plank hops, aggregate at **`herd-bridge`**, and fan out to logger / viz / sealed pages — edge-first, not a single cloud choke point
- **Nodes:** api, rt, col, coupons, points, bindi, herd-bridge, herd-gen-*, plank-logger, viz
- **Topics:** `/gubi/*` domain events + `/plank/rosout` + `/plank/power` + `/plank/herd/tokens`
- **Edges:** every publisher→subscriber hop emits a ROS-style log (level, stamp, seq, latency_µs, estimated mW)
- **RT constraints:** each topic carries a deadline class (critical / interactive / background / idle)
- **Herd computing:** the virtual population those fog edges coordinate at **`--scale googolplex`** (default), **`infinity`**, or legacy **`finite`** (100B) — never materializing individuals. Compact **RNG JSON tokens** (opaque person ids) are sealed into **Keystone-inspired enclave pages** (AES-256-GCM + homomorphic seal) on ingest. Use **`alu-gubi-driver herd`** for finite batch rounds, or **`alu-gubi-driver herd-stream`** for a **real-time** tick-driven simulator. Add **`--random-walk`** / **`--mode random-walk`** so each token carries Knuth LCG lattice steps (`dx`/`dy`, cumulative `wx`/`wy`) instead of ballistic shower draws. The **stream-agnostic pipeline** frames every source as one NDJSON `PipelineItem` and tees to the same **`--pipe`** sinks on emit and subscribe: `stdout` · `tcp://HOST:PORT` · `unix:///path.sock` · `file:///path` · `plank-ingest`.
- **Citations:** **conversations with Kailash Chandra** (Florida Tech *Intro to Simulation*); **reading Victor R. Lesser online** (UMass Amherst MAS); **reading Keystone online** (Dawn Song et al., Berkeley). See [`CITATIONS.md`](../CITATIONS.md).

```bash
alu-gubi-cli plank-status --pulse
alu-gubi-driver plank-status --pulse
curl -s http://127.0.0.1:8080/v1/plank/herd/status | jq .
alu-gubi-driver herd --scale googolplex --dry-run --raw
alu-gubi-driver herd --scale infinity --dry-run --raw
alu-gubi-driver herd --scale finite --dry-run --raw
alu-gubi-driver herd-stream --scale googolplex --dry-run
alu-gubi-driver herd-stream --dry-run   # default: 32-bit truecolor gfx (Rio/Ghostty)
alu-gubi-driver herd-stream --classic-tui --dry-run
alu-gubi-driver herd-stream --random-walk --dry-run --no-tui --duration 2
alu-gubi-driver herd-stream --mode random-walk --chunk 2 --tick 20 --dry-run
alu-gubi-cli viz --dry-run --random-walk
alu-gubi-driver herd-stream --scale infinity --chunk 2 --tick 20 --dry-run
alu-gubi-driver herd-stream --no-tui --duration 3 --dry-run --pipe stdout
alu-gubi-driver herd-stream --dry-run --no-tui --pipe file:///tmp/herd.ndjson --duration 5
alu-gubi-driver herd-stream --dry-run --no-tui --pipe tcp://127.0.0.1:9797 --duration 5
alu-gubi-driver herd-stream --dry-run --no-tui --pipe unix:///tmp/alu-gubi-herd.sock --duration 5
alu-gubi-driver herd-stream --pipe plank-ingest --scale googolplex
curl -N 'http://127.0.0.1:8080/v1/plank/herd/stream?format=ndjson'
alu-gubi-driver herd-subscribe --format ndjson --pipe stdout
alu-gubi-driver herd-subscribe --format sse --pipe file:///tmp/sub.ndjson
# stream-agnostic: same --pipe sinks for emit and subscribe
```

### mathi-alu-gubi event queue (Knuth–Fisher–Yates)

The driver can also emit a shuffled fake **payment + gamified UBI lifestyle** queue for the **mathi-alu-gubi** agentic client (high temperature / high top_k by default). Queue design cites **both** conversations with **Kailash Chandra** (Florida Tech *Introduction to Simulation*) and online reading of **Victor Lesser** (UMass Amherst MAS) — [`CITATIONS.md`](../CITATIONS.md):

```bash
alu-gubi-driver mathi-queue --raw
alu-gubi-driver mathi-queue --seed-mode operator --seed 42 -n 32 --raw
alu-gubi-driver mathi-queue --seed-mode entropy --priority --push --raw
```

Seed modes: `fixed` | `operator` | `entropy`. Sampling defaults: `MATHI_TEMPERATURE=1.45`, `MATHI_TOP_K=96`.

---

## 4b. Herd demo simulator — step by step

Mirror of the site walkthrough: [**#herd-howto**](https://shyamalschandra.github.io/alu-gubi-cli/#herd-howto) · movie: [#demo-media](https://shyamalschandra.github.io/alu-gubi-cli/#demo-media).

Virtual scales **`googolplex`** (default) / **`infinity`** / **`finite`** never materialize individuals — only compact RNG JSON tokens. The same **`--pipe`** sinks work on emit and subscribe: `stdout` · `tcp://…` · `unix://…` · `file://…` · `plank-ingest`.

### Step 01 — Install the driver

```bash
brew tap shyamalschandra/alu-gubi-cli
brew trust --formula shyamalschandra/alu-gubi-cli/alu-gubi-driver
brew install alu-gubi-driver
alu-gubi-driver herd-stream --help
```

### Step 02 — Dry-run the real-time TUI

No API needed. Keys: `q` quit · space pause · `[` `]` chunk · `-` `+` tick.

```bash
alu-gubi-driver herd-stream --scale googolplex --dry-run
```

### Step 02b — Plank viz token shower (`alu-gubi-cli viz`)

Live operator visualization for the Plank graph node **`viz`** (same shower aesthetic as the demo movie). Tokens fall from shard emitters as colored particles.

```bash
# Offline shower (local emitters):
alu-gubi-cli viz --dry-run

# Live path — Terminal A: API + emit, Terminal B: viz
alu-gubi-cli serve
alu-gubi-driver herd-stream --pipe plank-ingest --no-tui
alu-gubi-cli viz
# keys: q quit · space pause · d toggle dry-run
```

### Step 03 — Try other virtual scales

```bash
alu-gubi-driver herd-stream --scale infinity --dry-run
alu-gubi-driver herd --scale finite --dry-run --raw -g 4 --batch-size 8 -r 1
```

### Step 04 — Tee NDJSON to a file (no TUI)

```bash
alu-gubi-driver herd-stream --dry-run --no-tui \
  --pipe file:///tmp/herd-demo.ndjson \
  --duration 5 -g 8 --chunk 2 --tick 40
head -1 /tmp/herd-demo.ndjson | python3 -m json.tool
```

### Step 05 — Start the API (live path)

**Terminal 1** — leave running:

```bash
alu-gubi-cli serve
# other terminal:
curl -s http://127.0.0.1:8080/health
```

### Step 06 — Emit into Plank (sealed pages)

**Terminal 2** — batches seal into Keystone-inspired enclave pages:

```bash
alu-gubi-driver herd-stream --scale googolplex --pipe plank-ingest \
  --no-tui --duration 8 -g 8 --chunk 4 --tick 30
```

### Step 07 — Subscribe over NDJSON or SSE

**Terminal 3** — same `--pipe` sinks as emit:

```bash
alu-gubi-driver herd-subscribe --format ndjson --pipe stdout --max-messages 5 --raw
# or SSE:
curl -N 'http://127.0.0.1:8080/v1/plank/herd/stream?format=sse'
```

### Step 08 — Confirm status + watch the movie

```bash
curl -s http://127.0.0.1:8080/v1/plank/herd/status | python3 -m json.tool | head -40
open 'https://shyamalschandra.github.io/alu-gubi-cli/#demo-media'
```

---

## 5. Recommended daily workflow

```text
┌─────────────────┐     ┌──────────────┐     ┌─────────────────┐
│  moby-up -d     │ ──► │ ollama-pull  │ ──► │  serve [--live] │
│  (Ollama)       │     │ (models)     │     │  (API :8080)    │
└─────────────────┘     └──────────────┘     └─────────────────┘
         │                                              │
         └────────────────── ui / ui --watch ──────────┘
                              (monitor health)
```

### Field kiosk / demo (one shot)

Runs migrate, vault, optional Moby + models, demo citizen, **local KYC verification**, CoL, coupons, points, Bindi, and an agent quest:

```bash
alu-gubi-cli automate --moby-up --pull-models --zip 94102 --display-name "Demo Citizen"
```

Then start the API if you need HTTP access:

```bash
alu-gubi-cli serve
```

### Shutdown

```bash
# Stop API: Ctrl+C in the serve terminal
alu-gubi-cli moby-down
```

---

## 6. CLI command reference

All commands use **kebab-case** (e.g. `moby-up`, not `moby up`).

### Dashboard & install help

| Command | Purpose |
|---------|---------|
| `alu-gubi-cli ui` | One-shot stack dashboard |
| `alu-gubi-cli ui --watch` | Refresh every 3 seconds |
| `alu-gubi-cli ui --brew-only` | Homebrew install panel only |
| `alu-gubi-cli brew` | Print tap / trust / install script |

### GubiMoby (Ollama runtime)

| Command | Purpose |
|---------|---------|
| `alu-gubi-cli moby-up -d` | Start services detached |
| `alu-gubi-cli moby-down` | Stop services |
| `alu-gubi-cli moby-ps` | List containers / processes |
| `alu-gubi-cli moby-daemon` | Moby Engine API (default `127.0.0.1:2375`) |

### AI models

| Command | Purpose |
|---------|---------|
| `alu-gubi-cli ollama-pull` | Pull `llama3.3:latest` + `gemma3:1b` |

Generative tier: up to **10** parallel cloud calls.  
Agentic tier: up to **64** parallel local instruct calls.  
Tune with `OLLAMA_CLOUD_PARALLEL` and `OLLAMA_LOCAL_PARALLEL`.

### API server

| Command | Purpose |
|---------|---------|
| `alu-gubi-cli serve` | Start API on `0.0.0.0:8080` |
| `alu-gubi-cli serve --live` | Enable live external integrations |
| `alu-gubi-cli serve --host 127.0.0.1 --port 9090` | Custom bind |

### Database

| Command | Purpose |
|---------|---------|
| `alu-gubi-cli migrate` | Apply schema to in-memory or `DATABASE_URL` DB |

### Cost of living (CoL)

| Command | Purpose |
|---------|---------|
| `alu-gubi-cli col-summary` | National zip min/max USD summary |
| `alu-gubi-cli col-seed` | Print embedded zip crosswalk |

### GUBI operations (CLI)

Replace `{uuid}` with a real citizen UUID from `automate` output or your records.

| Command | Example |
|---------|---------|
| Issue coupons | `alu-gubi-cli coupons-issue {uuid} 2026-07 1200.00` |
| Award points | `alu-gubi-cli points-award {uuid} Gym 50 "completed workout"` |
| Bindi attestation | `alu-gubi-cli bindi-attest {uuid} '{"in":1}' '{"out":2}'` |
| Agent quest | `alu-gubi-cli agent-quest {uuid} --zip 94102 --domain Gym` |
| Vault secrets (dev) | `alu-gubi-cli vault-secrets` |

**Point domains** (for `points-award` / `agent-quest`): `Gym`, `Education`, and other domains defined in the binary (use exact spelling; JSON-style names).

---

## 7. REST API quick reference

Base URL (default): `http://127.0.0.1:8080`

### Pure Rust driver client (encrypted binary)

Install from the **same Homebrew tap** as the server CLI (ML-KEM-768 + ML-DSA-65 + homomorphic envelope):

```bash
brew tap shyamalschandra/alu-gubi-cli
brew trust --formula shyamalschandra/alu-gubi-cli/alu-gubi-driver
brew install alu-gubi-driver
```

```bash
# Terminal 1 — API server
alu-gubi-cli serve

# Terminal 2 — continuous ratatui live tour (q to quit)
alu-gubi-driver live --zip 94102 --display-name "Demo Citizen"
# aliases: watch · tui · demo --watch
# one-shot panels: alu-gubi-driver demo
```

The **`live`** command is a fullscreen emoji/unicode/color-block TUI (ratatui). It loops forever by
default and accepts alu_gubi charter args (`--zip`, `--display-name`, `--income-usd`, adversity flags,
`--domain`, `--points`, `--interval`, `--steps`, `--once`, …). Keys: `q` quit · `space` pause ·
`[/]` cycle ZIP. Colors for the one-shot `demo` panels auto-disable when piped or under `NO_COLOR`.

Developers with the private repo may also run from source: `cargo run -p alu-gubi-driver -- live`.

See `crates/alu-gubi-driver/README.md` for all subcommands.

| Area | Endpoints |
|------|-----------|
| Health | `GET /health` |
| CoL | `GET /v1/col/summary`, `GET /v1/col/zip/{zip}`, `POST /v1/col/adjusted` |
| Coupons | `POST /v1/coupons/issue`, `POST /v1/coupons/redeem` |
| Points | `POST /v1/points/award`, `GET /v1/points/balance/{citizen_id}/{domain}` |
| Bindi | `POST /v1/bindi/attest`, `GET /v1/bindi/unlock/{citizen_id}` |
| Agents | `POST /v1/agents/quest`, `POST /v1/agents/quest-batch`, `POST /v1/agents/plan` |
| Vault | `GET /v1/sys/health`, `GET/POST /v1/{mount}/data/{path}` |
| Rewards / gifts / elections / governance | Under `/v1/rewards/*`, `/v1/gifts/*`, `/v1/elections/*`, `/v1/governance/*` |

Example:

```bash
curl -s http://127.0.0.1:8080/v1/col/summary | head
curl -s -X POST http://127.0.0.1:8080/v1/agents/models
```

Use `serve --live` when integrations should call external Census/BLS/Amadeus APIs (secrets via GubiVault).

---

## 8. Environment variables

| Variable | Effect |
|----------|--------|
| `DATABASE_URL` | SQLite URL (default: in-memory) |
| `VAULT_MASTER_KEY` | GubiVault encryption root |
| `JWT_SECRET` | Session tokens; vault fallback |
| `LIVE_INTEGRATIONS` | `1` / `true` on `serve --live` — ensures Ollama models; external APIs used when vault keys are set (local fallbacks otherwise) |
| `OLLAMA_HOST` | Ollama base URL (default local) |
| `OLLAMA_CLOUD_PARALLEL` | Generative concurrency (default 10) |
| `OLLAMA_LOCAL_PARALLEL` | Agentic concurrency (default 64) |
| `GUBI_MOBY_OCI` | Linux OCI path when applicable |
| `RUST_LOG` | Log filter (e.g. `alu_gubi=info`) |

Create a `.env` file in the working directory; the CLI loads it automatically.

---

## 9. Troubleshooting

| Symptom | What to do |
|---------|------------|
| `brew tap` → repository not found | Use tap repo https://github.com/shyamalschandra/homebrew-alu-gubi-cli or direct formula URL (§3) |
| TUI shows Moby / Ollama offline | `alu-gubi-cli moby-up -d` then `alu-gubi-cli ollama-pull` |
| Agent quest errors | Confirm Ollama running; retry after models finish pulling |
| API won't bind | Change port: `alu-gubi-cli serve --port 9090` |
| State lost after reboot | Expected with in-memory DB; export Bindi attestations before shutdown or set `DATABASE_URL` |
| Checksum / install failure | Compare SHA with https://shyamalschandra.github.io/alu-gubi-cli/releases/manifest.json |
| Verify post-quantum manifest | Download `manifest.json`; confirm `format_version` ≥ 2 and run `gubi-pack verify-manifest --path manifest.json` (ML-DSA-65) |

---

## 9b. Post-quantum supply chain (format v2)

Release artifacts use a **hybrid envelope** (similar in spirit to Cloudflare’s PQC rollout):

| Layer | Algorithm | Role |
|-------|-----------|------|
| Key wrap | **ML-KEM-768** (FIPS 203) | Encapsulates the AES-256-GCM data key at pack time |
| Bulk cipher | **AES-256-GCM** | Encrypts the CLI binary |
| Manifest | **ML-DSA-65** (FIPS 204) | Signs canonical `manifest.json` (sorted keys, excluding signature fields) |
| Integrity | Homomorphic seal | Ciphertext tag verified before decrypt |

The published manifest includes `pq_mldsa_public_key` and `pq_mldsa_signature`. Operators can verify integrity without trusting the Pages host alone:

```bash
curl -fsSLO https://shyamalschandra.github.io/alu-gubi-cli/releases/manifest.json
cargo run -p alu-gubi-pack --bin gubi-pack -- verify-manifest --path manifest.json
```

Expected output: `manifest signature OK`.


| Resource | Link |
|----------|------|
| Website + downloads + PDF preview | https://shyamalschandra.github.io/alu-gubi-cli/ |
| **How to use (step-by-step)** | https://shyamalschandra.github.io/alu-gubi-cli/#howto |
| Chief Engineer's Notes | https://shyamalschandra.github.io/alu-gubi-cli/#chief-engineer |
| Release manifest (SHA-256) | https://shyamalschandra.github.io/alu-gubi-cli/releases/manifest.json |
| Industrial paper (PDF) | [docs/alu-gubi-cli.pdf](alu-gubi-cli.pdf) |
| Reference manual (PDF) | [docs/reference_manual.pdf](reference_manual.pdf) · [#reference-manual](https://shyamalschandra.github.io/alu-gubi-cli/#reference-manual) |
| Contact | sapanamicrosoftware@gmail.com |

---

## Quick copy-paste (minimal)

### One command — install and run API

Paste this **single line** in Terminal (macOS arm64). The last step keeps running until you press Ctrl+C:

```bash
brew tap shyamalschandra/alu-gubi-cli && brew trust --formula shyamalschandra/alu-gubi-cli/alu-gubi-cli && brew install alu-gubi-cli && alu-gubi-cli moby-up -d && alu-gubi-cli ollama-pull && alu-gubi-cli serve
```

Verify in a **second terminal** (while `serve` is running):

```bash
curl -s http://127.0.0.1:8080/health
```

Expected: `{"status":"ok"}`

### Step by step (same path)

```bash
brew tap shyamalschandra/alu-gubi-cli
brew trust --formula shyamalschandra/alu-gubi-cli/alu-gubi-cli
brew install alu-gubi-cli
alu-gubi-cli moby-up -d
alu-gubi-cli ollama-pull
alu-gubi-cli serve
```

License: [CCSL-1.0a](https://shyamalschandra.github.io/alu-gubi-cli/license/) · conditioned by [OpenAI ChatGPT note](https://chatgpt.com/share/6a5a6001-5d88-83ea-ac88-7090df3d8e30)