CoTrinity fabric CLI (terminal)

Audience: Members and operators who want CoTrinity/OmniLore fabric access from a shell.
As-of: 2026-08-17T17:45Z · CLI version: 0.8.7 (Wave D chat run-control cockpit + Wave C multi-turn REPL)

What it is

A terminal fabric client + doctor for OmniLore seats:

| Is | Is not |
|----|------------|
| doctor, product answers, continuity, allowlisted MCP tools | Full CoTrinity IDE in a terminal |
| Same fabric law as the extension (fail-closed product truth) | Free shell / unrestricted tools |
| Optional VSIX install + tunnel check + seat status | Replacement for VS Code / Cursor CoTrinity |

Primary CoTrinity product remains the IDE extension. See COTRINITY_IDE.md.

Design: ops docs/DESIGN_COTRINITY_CLI_V1_2026-08-12.md.

Install / run

From an ops tree (server SoT or workstation mirror):

# Server
/srv/omnilore/work/ops/bin/cotrinity version

# Workstation mirror
~/omnilore/ops/bin/cotrinity version

# Optional PATH
export PATH="$HOME/omnilore/ops/bin:$PATH"
# Or one-shot:
#   bash ~/omnilore/ops/bin/install-cotrinity-cli-path.sh   # links into ~/.local/bin
# or: ln -s ~/omnilore/ops/bin/cotrinity ~/.local/bin/cotrinity

Alias: omnilore-cotrinity → same binary.

Auth (required for fabric commands)

Preferred: `login` / `logout` / `whoami` (CLI 0.8.3+)

# Owner / WS with SSH tunnel to MCP (loopback)
cotrinity login --loopback --token-file ~/secret/mcp.token
# or interactive hidden prompt:
#   cotrinity login --loopback

# True remote seat — public edge (Bearer required)
cotrinity login --public --token-file ~/secret/mcp.token
# equivalent: transport_mode=public_api → https://api.omnilore.ai/mcp

cotrinity whoami              # live tools/list probe (token masked)
cotrinity whoami --offline    # config only
cotrinity logout              # remove token file

| Flag | Effect |
|------|--------|
| --public | transport_mode=public_api + https://api.omnilore.ai/mcp |
| --loopback | transport_mode=loopback_tunnel + http://127.0.0.1:8421/mcp |
| --api-base | Override API origin (with --public) |
| --mcp-url | Full MCP URL override |
| --no-verify | Save token without live tools/list check |
| --seat-id | Label for logs (laptop-gwen, …) |

Do not point CoTrinity chat provider (coding model) at https://api.omnilore.ai — that host is fabric MCP, not Ollama. Daily coding stays local (http://127.0.0.1:11434) when you have a seat model. Design: ops docs/DESIGN_REMOTE_CODER_SEAT_WS_T2_TEMPLATE_2026-08-17.md.

Manual token (still supported)

mkdir -p ~/.config/omnilore
# Membership / MCP bearer token (same family as CoTrinity extension / Chat)
# Preferred seat path (shared with VS Code/Cursor CoTrinity extension):
#   ~/.config/omnilore/mcp-http-bearer.token
# Or explicit CLI name:
printf '%s\n' "$YOUR_MCP_TOKEN" > ~/.config/omnilore/mcp.token
chmod 600 ~/.config/omnilore/mcp.token
# CLI auto-discovers mcp.token, then mcp_token, then mcp-http-bearer.token

Or: OMNILORE_MCP_TOKEN_FILE, OMNILORE_MCP_URL (default http://127.0.0.1:8421/mcp),
OMNILORE_API_BASE, OMNILORE_TRANSPORT_MODE (loopback_tunnel | public_api | lan).

Optional config: ~/.config/omnilore/cotrinity-cli.json (never stores raw token — only mcp_token_file path).

Workstation tunnel

On ws-t2 (or any seat that is not the MCP host), tunnel first:

ssh -N -L 127.0.0.1:8421:127.0.0.1:8421 omnilore-server
# then:
cotrinity tunnel-check
cotrinity login --loopback --token-file ~/.config/omnilore/mcp-http-bearer.token
cotrinity doctor

See ops docs/COTRINITY_MCP_TUNNEL_HARDENING.md.

Commands

Hygiene

| Command | Purpose |
|---------|---------|
| cotrinity login | Store MCP bearer + transport; optional live verify |
| cotrinity logout | Remove stored token |
| cotrinity whoami | Masked auth view + MCP probe |
| cotrinity doctor | Python, ops root, VSIX, IDE CLI, token, transport, MCP TCP/HTTP, tools/list |
| cotrinity doctor --offline | Skip live MCP HTTP/auth |
| cotrinity --json doctor | Machine-readable (global --json before subcommand) |
| cotrinity tunnel-check | Loopback :8421 listening |
| cotrinity vsix | Path to extension VSIX under ops |
| cotrinity install [--host auto\|code\|cursor] | code/cursor --install-extension |
| cotrinity seat status | Delegates to omnilore-desk status |
| cotrinity seat profile list | List transport profiles |
| cotrinity seat profile use remote-member | Apply public API profile (api.omnilore.ai/mcp) |
| cotrinity seat profile use ws-t2-owner | Apply Owner tunnel loopback profile |

Fabric (needs token)

| Command | Purpose |
|---------|---------|
| cotrinity status | fabric_health summary |
| cotrinity answer "What is OmniLore?" | product_answer only — product truth (one-shot) |
| cotrinity chat | Wave C+D multi-turn cockpit — OmniLore product + programming agent + /diff approval law |
| cotrinity mcp tools | List tools (allowlist by default; --all for full) |
| cotrinity mcp call <tool> [--arg k=v] | Allowlisted tool only |
| cotrinity --profile coding mcp call forge_read_file --arg ... | Coding allowlist |

Continuity Memory

| Command | Purpose |
|---------|---------|
| cotrinity continuity pack [query] | Budgeted continuity inject |
| cotrinity continuity search <query> | Search personal continuity facts |
| cotrinity continuity write --key K --value V | Store preference (user_stated) |
| cotrinity continuity forget --key K | Tombstone fact |
| cotrinity continuity status | Store / manage metrics |

Continuity is personal — not product SoT. See CONTINUITY_MEMORY.md.

Security (member-safe)

| Rule | Behavior |
|------|----------|
| Allowlist default | product_answer, fabric health, continuity, session feed, posture, … |
| Hard deny | ops_run, free submit, forge write/merge, tribal_share, … |
| Tokens | Never printed in full (*** last 4) |
| Product questions | Use answer — do not invent from local models |

Examples

cotrinity doctor
cotrinity answer "What is OmniLore?"
cotrinity chat --mode auto                 # multi-turn REPL
cotrinity chat --mode omnilore --once "What is OmniLore?"
cotrinity chat --mode agent --once "add a healthcheck"
cotrinity continuity pack "my project next steps"
cotrinity mcp call architecture_card
cotrinity mcp call ops_run --arg recipe=x   # denied (exit 3)

Chat REPL + run-control cockpit (Wave C+D — LIVE 0.8.7)

Multi-turn terminal chat with a session + approval cockpit (same fabric law as the extension):

| Mode | Free-text does | Mutations |
|------|----------------|-----------|
| omnilore | product_answer (SoT product truth) | none |
| agent | Read-only agent plan (SoT-grounded when product-truth) | /edit, /run + /approve (digest-bound) |
| auto (default) | Routes product-looking questions → omnilore; else agent | same |

cotrinity chat --workspace .
cotrinity chat --tui --workspace .          # optional Textual panes (needs [tui])
cotrinity chat --recover --journal PATH     # reopen journal after crash
# slash: /help /panel /diff /files /tests /why /resume <id>
#        /mode /answer /plan /edit /run /approve /reject /quit
# journal: .cotrinity/chat/session-*.jsonl

Cockpit law: never /approve a digest without /diff (chat refuses blind approve).
Is: multi-turn REPL + pending-run panel + source trace.
Is not: full IDE CoTrinity Chat parity, free shell, or silent apply.

Closeouts: CLOSEOUT_COTRINITY_CHAT_REPL_WAVE_C_2026-08-17.md · CLOSEOUT_COTRINITY_CHAT_COCKPIT_WAVE_D_2026-08-17.md.

IDE: COTRINITY_IDE.md
Features: FEATURES_USER.md
Desktop seat: DESKTOP_SEAT_CAPTURE.md
Positioning: ops PRODUCT_POSITIONING_FRONT_DOOR_AND_COTRINITY_2026-08-11.md

End.

Agent plane (v1 LIVE — 0.8.2)

A bounded coding agent ladder (plan → propose diff → explicit apply → allowlisted test → optional RepoHub helpers) is designed in ops:

docs/DESIGN_COTRINITY_AGENT_CLI_V1_2026-08-12.md

IDE Agent Runs: digest-bound Agent Runs Approve (extension ≥1.0.39) resumes orch via cotrinity agent spawn path.

LIVE (0.8.2) — agent v1 ladder + context auto/prepare + review:

cotrinity agent plan "add a healthcheck endpoint"
cotrinity agent edit "add a healthcheck endpoint"   # propose only
cotrinity agent apply <id>                          # explicit approve
cotrinity agent test -- python3 -m pytest -q tests  # allowlisted (no free shell)
cotrinity agent test -- make test                   # expanded builtin prefixes (F-31)
cotrinity agent test -- cargo test
cotrinity agent test -- ruff check .
cotrinity agent test --recipe unit                  # project .cotrinity/recipes.v1.json
cotrinity agent recipes                             # list project recipes
cotrinity agent recipes --example                   # sample recipes.v1.json
cotrinity models list
cotrinity models use coder
cotrinity context build "add healthcheck"   # deterministic source pack
cotrinity agent prepare "add healthcheck"   # auto build/refresh context + plan
cotrinity agent review --since HEAD~1 --closeout latest  # source-read-only QA (+ local .cotrinity/reviews)
cotrinity agent review --no-artifact  # strict audit: no review artifact write
cotrinity agent plan "add healthcheck" --context auto
cotrinity agent edit "add healthcheck" --context auto
cotrinity agent plan "add healthcheck" --context latest
cotrinity agent edit "add healthcheck" --context latest
# missing/stale context fails closed; optional: --allow-stale-context
cotrinity agent plan "…" --llm          # local Ollama via alias (fallback: template)
cotrinity agent plan "…" --llm --stream # stream tokens to stderr; parse after complete
cotrinity agent edit "…" --llm --stream
# Composer (propose-only edit; no free shell):
#   /plan --llm --stream <goal>
#   /edit --llm --stream [--file PATH] <goal>
# optional: OMNILORE_AGENT_MODEL_NAME=llama3.2:1b for a small model
# Design: DESIGN_COTRINITY_LLM_TOKEN_STREAM_V1_2026-08-14.md
cotrinity forge status                              # RepoHub connectivity
cotrinity forge projects
cotrinity forge pulls owner/repo
cotrinity forge branches owner/repo
cotrinity forge branch owner/repo feat/x --from main   # needs MCP forge-write
cotrinity forge pr owner/repo --title "…" --head feat/x

Honesty bounds

| True | Still false |
|------|-------------|
| Plan without mutate; apply-with-approval | Free shell / ops_run |
| Path jail on edit/apply | Full IDE CoTrinity parity |
| Allowlisted tests + project recipes (F-31) | Free shell / model-composed bash -c |
| Allowlisted tests | Unattended multi-hour autonomy |
| Local dual-seat models aliases | “All foundation model providers” |
| RepoHub forge via MCP coding profile | GitHub.com native account CLI |
| Bounded orchestrator + line TUI (below) | Detach from a live engine and claim stopped |

Bounded orchestrator + TUI (LIVE — Phase 2–5)

Same fail-closed engine family as the IDE agentRuntime plane. Mutations need digest-bound Owner approve.

cotrinity orch run --goal "add hello.txt" --file hello.txt::hello\\n --workspace .
cotrinity orch runs --workspace .
cotrinity orch show <run_id> --json --workspace .
cotrinity orch resume <run_id> --approve --workspace .
cotrinity orch resume <run_id> --reject --workspace .
cotrinity orch tui --line --workspace .          # full facts without Textual
cotrinity orch tui --composer --workspace .      # interactive prompt (P1)
cotrinity orch tui --line --composer --workspace .
# Composer P1/P2 (no free shell): /help  /run <goal>  free-text goal  /approve  /reject
#   /plan [--llm] [--stream]  /edit [--llm] [--stream] [--file PATH]
#   /test --recipe unit  /recipes  /show  /runs  /quit
#   P2: live event lines stream during /run and /approve (observe→plan→propose…)
#   LLM tokens: /plan|/edit --stream → stream_write (propose-only; apply still digest-bound)
# Design: DESIGN_COTRINITY_TUI_COMPOSER_V1_2026-08-14.md
cotrinity orch doctor --json --workspace .
# Optional Textual: pip install 'cotrinity-cli[tui]'

| Exit | Meaning |
|------|---------|
| 0 | done |
| 10 | wait_owner / paused |
| 12 | cancelled |
| 14 | needs recovery |

Dogfood: bash bin/dogfood-cotrinity-agent-phase5.sh

Always RepoHub (repohub.omnilore.ai), never “GitHub” for forge.

CoTrinity Chat (agent ≥ 1.0.41 recommended): “my projects on RepoHub” → forge_list_projects; “build a dashboard webpage for these projects” → scaffold_repohub_dashboard (writes repohub-dashboard/ under the open workspace after confirm; http(s) links only). Not local home directory listing.