CLI Reference

import { Tabs, TabItem } from ‘@astrojs/starlight/components’;

ContextUnity ships three CLI entry points — a unified local development tool, a Router service manager, and a Shield administrator. All are built on Typer with Rich-powered output and auto-completion.

Entry Points

CLI	Package	Description
contextunity	packages/cli	Unified local dev: service orchestration, TUI, Brain export
contextrouter	services/router	Router gRPC server, model testing
contextshield	services/shield	Project PKI, admin tokens, policy management

ContextUnity CLI (contextunity)

The primary entry point for local development. Orchestrates all ContextUnity services from a single command.

Quick Start

# Start all services with the interactive TUI
contextunity local up --tui

# Start services in background (no TUI)
contextunity up

# Start with auto-reload on code changes
contextunity up --reload

See Quick Start for the full bootstrap guide.

Command Tree

contextunity
├── up [--reload] [--tui]           → Start platform (resolves target from config)
├── status                          → Check running services and external integrations
├── version                         → Show CLI version
├── contracts [--json] [--out]      → Show typed command behavior contracts
├── config                          → Configuration management
│   └── show                        → Display active configuration
└── local                           → Local platform management
    ├── up [--reload] [--tui]       → Start local services
    ├── brain-export [--output]     → Export Brain data to portable JSONL archive
    ├── brain-validate <archive>    → Validate a portable Brain archive
    └── create-view-admin           → Create Django superuser for View admin

contextunity up

The up command resolves the target from contextunity.yml configuration:

• local (default) — starts Brain, Router, and Worker as supervised subprocesses
• stack:* — reserved for stack deployments (not yet implemented)

contextunity local up --tui

Launches the Textual TUI — a multi-tab terminal dashboard with per-service log panels, live status indicators, and file watching for auto-reload:

• Each service gets a dedicated log tab with Rich-formatted output
• Services are managed via LocalSupervisor with graceful lifecycle
• File watcher monitors source directories and triggers service restart on changes

contextunity status

Queries the Redis service mesh for registered services and probes external integrations:

contextunity status
# Running Services:
# - router (default) at localhost:50052
# - brain (default) at localhost:50051
#
# External Services
# - Shield localhost:50054 (OK)

contextunity local brain-export

Exports local SQLite Brain data to a portable JSONL archive:

contextunity local brain-export --output ./brain-export-v1 --tenant default

The archive can be imported into a full PostgreSQL Brain deployment.

Configuration

The CLI discovers configuration from a search chain:

CWD/.contextunity/  →  ~/.contextunity/  →  /etc/contextunity/

Override with CU_CONFIG_DIR or CU_CONTEXTUNITY_CONFIG_FILE environment variables. See the Configuration page.

---

ContextRouter CLI (contextrouter)

The Router CLI manages the gRPC server and provides model testing utilities.

Architecture

The CLI uses a registry pattern — each command module registers itself at import time via register_command(name, app), keeping app.py minimal and extensible via plugins.

Commands

contextrouter serve

Starts the ContextRouter gRPC server:

contextrouter serve

The serve command:

1. Loads the manifest from contextunity.project.yaml
2. Bootstraps the SDK (Shield handshake, secrets, signing backend)
3. Registers in the service mesh via Redis discovery
4. Starts the async gRPC server with reflection enabled
5. Enters graceful shutdown on SIGINT/SIGTERM

contextrouter models

Test and validate LLM provider connectivity:

# Test all configured providers
contextrouter models test

# Test a specific provider
contextrouter models test --provider openai

Supported providers and test capabilities:

Provider	Model	Tests
openai	gpt-4o-mini	text, image, audio, stream
anthropic	claude-3-5-haiku-latest	text, image, stream
vertex	gemini-2.5-flash	text, image, audio, video, stream
groq	llama-3.3-70b-versatile	text, stream
openrouter	openai/gpt-4o-mini	text, image, stream

Extending the Router CLI

my_plugin/cli.py

import typer
from contextunity.router.cli.registry import register_command

app = typer.Typer(help="My custom commands.")

@app.command()
def my_command():
    """Do something custom."""
    ...

register_command("my-plugin", app)

Commands are auto-discovered via pkgutil.iter_modules in the contextunity.router.cli package namespace.

---

Shield CLI (contextshield)

The administrative interface for managing the security perimeter, project credentials, policy rules, and cryptographic key rotations.

Command Tree

contextshield
├── project-create <project_id> [--services <svc,svc,...>] [--hmac-secret <secret>]
├── project-list
├── project-rotate <project_id>
├── project-reset-hmac <project_id> [--hmac-secret <secret>]
├── project-delete <project_id>
├── project-policy <project_id> [--ttl <seconds>] [--set <perms>] [--allow <perms>] [--deny <perms>] [--admin-token <token>]
├── admin-create <project_id>
├── admin-delete <project_id>
├── create-view [--hmac-secret <secret>]
├── rotate-master-key
└── serve [--port <port>]

Commands

contextshield project-create

Creates a new project configuration and generates its initial Ed25519 keypair and HMAC secret.

contextshield project-create my-project --services "brain,router"

Options:

• --services: Comma-separated list of services to grant access to (brain, router, worker, shield). If omitted, enters an interactive selection prompt.
• --hmac-secret: Use a specific HMAC secret instead of generating a random one.

contextshield project-list

Lists all registered projects, their key IDs (KID), maximum TTLs, and rotation counts.

contextshield project-list

contextshield project-rotate

Rotates the Ed25519 signing keys for a project, updating the Key ID and generating a new public key.

contextshield project-rotate my-project

contextshield project-reset-hmac

Resets/regenerates the HMAC secret for a project.

contextshield project-reset-hmac my-project

Options:

• --hmac-secret: Set a specific HMAC secret instead of generating a random one.

contextshield project-delete

Deletes a project record, its policy, and keys from the database.

contextshield project-delete my-project

contextshield project-policy

Manages token TTL constraints and allowed permissions for a project.

# View policy locally
contextshield project-policy my-project

# Update permissions locally
contextshield project-policy my-project --set "brain:read,router:execute"

# View policy remotely using an admin token
contextshield project-policy my-project --admin-token "shield-admin:my-project:Abc..."

# Update permissions remotely using an admin token
contextshield project-policy my-project --admin-token "shield-admin:my-project:Abc..." --set "brain:read,router:execute"

Options:

• --ttl: Set the maximum token lifetime (TTL) in seconds.
• --set: Comma-separated list of allowed permissions (completely overrides current permissions).
• --allow: Permissions to append (local-only).
• --deny: Permissions to remove (local-only).
• --admin-token: Connects remotely to the Shield gRPC daemon. If no modification flags are provided, it fetches and prints the current policy.

contextshield admin-create

Generates a new admin token for a project (replaces and invalidates any existing admin token).

contextshield admin-create my-project

contextshield admin-delete

Revokes the admin token for a project, disabling remote policy management.

contextshield admin-delete my-project

contextshield create-view

Bootstraps the internal contextview project with predefined administration permissions (e.g. brain:read, trace:read, worker:*).

contextshield create-view

contextshield rotate-master-key

Re-encrypts all database private keys under a new SHIELD_MASTER_KEY master key.

contextshield rotate-master-key

contextshield serve

Starts the Shield gRPC service daemon.

contextshield serve --port 50054