💻 CLI Reference

🤠 randal — agent harness v0.2

🎬 Two Modes

Randal operates in two modes with different execution models:

🎯 randal run — Local one-shot. Creates a Runner directly, prints to stdout, blocks until done, exits. No server, no persistence, no dashboard.

🏗️ randal serve — Daemon. Starts an HTTP server with REST API, SSE event stream, job persistence (~/.randal/jobs/), memory integration, and a web dashboard. Jobs run in the background.

All other commands (send, status, jobs, stop, context, resume, memory) communicate with a running daemon via HTTP.

🌐 Global Options

Flag	Type	Description
`--config <path>`	string	Path to config file. If omitted, searches for `randal.config.yaml`, `randal.config.yml`, or `randal.yaml` in the current directory.
`--url <url>`	string	Remote server URL. Default: `http://localhost:7600`. Used by remote commands (`send`, `status`, etc.).
`--version`, `-v`	flag	Print version and exit.
`--help`, `-h`	flag	Print help and exit.

📋 Commands

🔧 `randal init`

Scaffold a randal.config.yaml in the current directory. Features an interactive onboarding wizard with environment auto-detection.

randal init              # Interactive — QuickStart or Advanced
randal init --wizard     # Jump straight to Advanced wizard
randal init --persona    # Legacy persona-artifact helper; prefer the standalone script below
randal init --yes        # Non-interactive — auto-detect + defaults
randal init --from <path> # Bootstrap from existing config

See Init Modes for details on each mode.

Primary persona authoring for source-machine -> Mac mini provisioning now lives outside randal init:

bun run scripts/persona-preseed.ts

That standalone Bun script launches a real OpenCode interview session from the repo checkout, writes the reviewed local artifacts into an output directory, and emits the trusted local preseed bundle you hand to the Mac mini.

randal init --persona remains available as a secondary local artifact writer when you only want the identity files without the standalone preseed handoff flow:

.randal/identity/persona.identity.yaml as the machine-readable source of truth
.randal/identity/PERSONA.md for human review and editing
IDENTITY.md as the rendered compatibility artifact used by current config flows

Generated persona artifacts are also recorded in .randal/managed-artifacts.yaml so later reset flows can remove only Randal-managed files.

🧹 `randal reset`

Clear all Randal config and state. Returns to a fresh state ready for randal init.

randal reset          # Remove config + job/cron state (preserves .env and memory data)
randal reset --all    # Aggressive reprovisioning wipe for the same machine/preseed flow
randal reset --yes    # Skip confirmation prompts

Flag	Description
`--all`	Aggressive reprovisioning wipe for the current macOS user: removes `.env`, manifest-tracked generated project artifacts, `~/.config/opencode`, `~/.randal`, and the `randal-meilisearch` Docker container/state. The interactive flow requires explicit machine-wide confirmation.
`--yes`	Skip all confirmation prompts (for scripting). Combinable with `--all`.

Default reset removes:

randal.config.yaml in current directory
~/.randal/jobs/ (all persisted job files)
~/.randal/cron.yaml (cron scheduler state)

Default reset preserves:

.env (contains your API keys)
~/.randal/meili-data/ (Meilisearch indexes and memory data)
~/.config/opencode/

randal reset --all additionally removes:

.env
.randal/managed-artifacts.yaml and the generated project/home artifacts recorded there
~/.config/opencode/ for the current macOS user
~/.randal/ for the current macOS user
Interactive use asks for an explicit machine-wide confirmation before deleting those user-level runtime directories
randal-meilisearch Docker container (if present)

🎯 `randal run <prompt|file>`

Run an agent locally in one-shot mode. If the argument is a path to an existing .md file, its contents are used as the prompt.

randal run "refactor the auth module"
randal run spec.md
randal run "fix tests" --max-iterations 10

Flag	Type	Default	Description
`--agent`	string	Config `runner.defaultAgent` (`opencode`)	Agent adapter name.
`--model`	string	Config `runner.defaultModel` (`anthropic/claude-sonnet-4`)	Model identifier.
`--max-iterations`	number	Config `runner.defaultMaxIterations` (`20`)	Maximum iteration count.
`--workdir`	string	Config `runner.workdir`	Working directory for the agent process.
`--verbose`, `-v`	flag	`false`	Show iteration summaries during execution.

Exits with code 1 if the job fails.

🏗️ `randal serve`

Start the daemon: gateway + runner + dashboard.

randal serve
randal serve --port 8080

Flag	Type	Default	Description
`--port`	number	Config HTTP channel port (`7600`)	Override the HTTP server port.

The server runs until terminated. Dashboard available at the root URL.

Published-artifact bootstrap is optional. The normal default is still local randal.config.yaml startup. If you want a runtime to start directly from a published artifact instead, set these environment variables before randal serve:

export RANDAL_MANAGED_CONTROL_PLANE_URL=https://control-plane.example
export RANDAL_MANAGED_WORKSPACE_ID=workspace-123
export RANDAL_MANAGED_VERSION_ID=version-7   # optional; omit to use the active published version

Optional override:

export RANDAL_MANAGED_ARTIFACT_URL=https://control-plane.example/api/workspaces/workspace-123/setup-versions/version-7/config-export

Notes:

Managed bootstrap fetches only published artifacts.
Config Studio draft state is never consumed by runtime startup.
GET /instance reports runtime mode as local or managed so the dashboard can surface which path is active.
See docs/config-studio.md for the current file-authoring model and source-of-truth rules.

📨 `randal send <prompt|file>`

Submit a job to a running Randal instance via HTTP. If the argument is a path to an existing .md file, its contents are used as the prompt.

randal send "build the new API endpoint"
randal send spec.md --agent opencode
randal send "fix bug" --url http://remote:7600

Flag	Type	Default	Description
`--agent`	string	—	Agent override.
`--model`	string	—	Model override.
`--max-iterations`	number	—	Max iterations override.
`--workdir`	string	—	Working directory override.

Uses RANDAL_API_TOKEN environment variable for Bearer authentication.

📊 `randal status [job-id]`

Get the status of a specific job, or list all running jobs if no ID is given.

randal status             # List all running jobs
randal status abc12345    # Get details for a specific job

📋 `randal jobs`

List all jobs from the gateway.

randal jobs
randal jobs --status failed
randal jobs --status complete

Flag	Type	Default	Description
`--status`	string	—	Filter by status: `queued`, `running`, `complete`, `failed`, `stopped`.

🛑 `randal stop <job-id>`

Stop a running job.

randal stop abc12345

💉 `randal context [job-id] <text>`

Inject context into a running job. Human text still lands in context.md, and the runner also supports structured context.packet.json and context.updates.jsonl files for machine-readable worker context without breaking the existing CLI flow.

If no job-id is given and exactly one job is running, it targets that job. If multiple jobs are running, an explicit ID is required.

randal context "focus on the payment module first"    # Single running job
randal context abc12345 "skip the tests for now"      # Explicit job ID

🔄 `randal resume <job-id>`

Resume a failed job. Fetches the job's history, builds a prompt containing prior iteration summaries as context, and submits a new job.

randal resume abc12345

🧠 `randal memory <subcommand>`

Memory operations. Requires a running daemon (for search and list) or local config (for add).

`randal memory search <query>`

Search memory by query.

randal memory search "database migrations"
randal memory search "auth" --agent my-agent --limit 10

Flag	Type	Default	Description
`--agent`	string	—	Filter by agent name.
`--category`	string	—	Filter by category.
`--limit`	number	—	Maximum results.

`randal memory list`

List recent memories.

randal memory list
randal memory list --limit 20 --category lesson

Flag	Type	Default	Description
`--agent`	string	—	Filter by agent name.
`--category`	string	—	Filter by category.
`--limit`	number	—	Maximum results.

`randal memory add <content>`

Add a memory entry.

randal memory add "The deploy script requires Node 20" --category fact
randal memory add "User prefers tabs over spaces" --category preference

Flag	Type	Default	Description
`--category`	string	`"fact"`	Memory category: `preference`, `pattern`, `fact`, `lesson`, `escalation`.
`--agent`	string	—	Agent name to associate with the memory.

🔍 `randal audit`

Detect and report ambient host authentication. Scans for SSH keys, GitHub CLI auth, git credential stores, Google Cloud auth, AWS credentials, Docker registry auth, and npm/bun auth tokens.

randal audit              # Human-readable report
randal audit --json       # Machine-readable JSON output

Flag	Type	Description
`--json`	flag	Output JSON format instead of human-readable text.

Does not require a config file. Probes run in subprocesses with short timeouts and are non-destructive (read-only).

🔩 `randal setup`

Generate opencode.json and configure the OpenCode runtime. This command replaces agent/setup.sh and is the recommended way to set up a Randal deployment.

randal setup                  # Generate config, symlink dirs, install plugins
randal setup --preseed ./source-machine-to-mac-mini.preseed.yaml
randal setup --dry-run        # Preview what would be generated (no writes)
randal setup --json           # Output raw JSON to stdout (for piping)
randal setup --verbose        # Show detailed MCP wiring and resolution steps

Flag	Type	Description
`--config <path>`	string	Path to `randal.config.yaml`.
`--preseed <path>`	string	Trusted local wrapper bundle authored on a source machine, then copied to the target Mac mini. Materializes files first, then runs the normal setup pipeline.
`--output <dir>`	string	Output directory. Default: `~/.config/opencode/`.
`--dry-run`	flag	Print generated `opencode.json` and planned symlinks without writing anything.
`--json`	flag	Output raw JSON to stdout for piping to other tools.
`--verbose`	flag	Show which MCP servers are included, why, which capabilities were detected, and identity resolution details.

What it does:

Reads randal.config.yaml (or the file given by --config)
Compiles opencode.json from opencode.base.json + config values (MCP servers, tool permissions, capabilities)
Writes the generated opencode.json to ~/.config/opencode/opencode.json
Symlinks static content (agents/, skills/, lenses/, tools/, rules/, plugins/, package.json, tui.json) from agent/opencode-config/ into the output directory
Runs bun install for plugin dependencies

The command is idempotent — safe to run repeatedly. Existing non-symlink entries are backed up before replacement.

Source-machine -> Mac mini handoff

On your source machine, from the repo checkout, run bun run scripts/persona-preseed.ts.
Review the generated output directory and copy the emitted source-machine-to-mac-mini.preseed.yaml bundle to the Mac mini.
On the Mac mini, run randal setup --preseed ./source-machine-to-mac-mini.preseed.yaml.
If you need to reprovision the Mac mini, run randal reset --all --yes first, then re-run the same preseed bundle.

The preseed format is intentionally local and trusted for v1. Plaintext secrets in the bundle are supported, but the file should stay on machines you control.

Migration from agent/setup.sh: If you previously used bash agent/setup.sh, switch to randal setup. The old script still works but prints a deprecation warning. See Deprecation: agent/setup.sh below.

🩺 `randal doctor`

Validate the current deployment. Runs a series of diagnostic checks and reports pass/fail/warn for each.

randal doctor                 # Run all checks
randal doctor --config ./my-config.yaml   # Check a specific config

Flag	Type	Description
`--config <path>`	string	Path to `randal.config.yaml`.
`--output <dir>`	string	OpenCode config directory to check. Default: `~/.config/opencode/`.

Checks performed:

Check	What it validates
Config	`randal.config.yaml` parses correctly
opencode.json	File exists at `~/.config/opencode/opencode.json`
Config freshness	Generated config matches current `randal.config.yaml` (detects stale configs)
Identity files	All referenced persona, rules, and knowledge files resolve
MCP servers	All MCP server binaries/scripts referenced in `opencode.json` exist on disk
Meilisearch	Health check passes (if memory is configured)
OpenCode CLI	`opencode` binary is available on PATH
Symlinks	Symlinks in `~/.config/opencode/` point to valid targets

Exit codes: 0 if all checks pass, 1 if any check fails.

Example output:

  Randal Doctor — deployment validation

  [PASS] Config: randal.config.yaml parses correctly
  [PASS] opencode.json: opencode.json exists at ~/.config/opencode/opencode.json
  [PASS] Config freshness: opencode.json is consistent with current config
  [PASS] Identity files: All identity files resolve (persona, 3 rules)
  [PASS] MCP servers: All MCP server scripts exist (memory, scheduler, tavily)
  [PASS] Meilisearch: Meilisearch is healthy at http://localhost:7701
  [PASS] OpenCode CLI: `opencode` is available on PATH
  [PASS] Symlinks: 8 symlinks OK (agents, skills, lenses, ...)

  Summary: 8 passed, 0 warned, 0 failed

⬆️ `randal update`

Self-update for git-based installs. Fetches latest tags, compares versions, and optionally applies the update.

randal update              # Fetch, compare, pull if available, reinstall
randal update --check      # Just report if an update is available (exit 0/1)
randal update --pin v0.3.0 # Checkout a specific tag
randal update --dry-run    # Show what would change without applying

Flag	Type	Description
`--check`	flag	Report availability and exit with code 0 (available) or 1 (up to date).
`--pin <version>`	string	Checkout a specific tag version.
`--dry-run`	flag	Show commits that would be applied without making changes.

In container mode, reports the available update and suggests rebuilding the image. Does not modify the container filesystem.

Does not require a config file.

🚀 `randal deploy`

Deploy to Railway. Wraps the Railway deployment scripts with a consistent CLI interface.

randal deploy agent                                    # Deploy single agent
randal deploy agent --dry-run                          # Preview without deploying
randal deploy posse --name my-team                     # Deploy multi-agent posse
randal deploy posse --name my-team --config posse.yaml # Deploy with custom config
randal deploy env                                      # Set Railway env vars only
randal deploy list                                     # List deployed posses
randal deploy delete my-team                           # Delete a posse

Subcommands

Subcommand	Description
`agent`	Deploy a single Randal agent to Railway. Reads `.env`, sets Railway variables, deploys.
`posse --name <name>`	Deploy a multi-agent posse with shared Meilisearch. Requires `--name`.
`env`	Set environment variables on Railway from `.env` without deploying.
`list`	List all deployed posses (local deployment summaries).
`delete <name>`	Delete a deployed posse. Use `--force` to skip confirmation.

Agent Options

Flag	Description
`--dry-run`	Preview what would be set and deployed without making changes.

Posse Options

Flag	Description
`--name <name>`	Posse name (required). Used as the Railway project name prefix.
`--config <file>`	Path to posse config YAML. Default: `examples/railway-posse/full-company.yaml`.
`--dry-run`	Preview without deploying.

Prerequisites

Railway CLI: curl -fsSL https://railway.com/install.sh | sh
Railway auth: railway login
.env file: Must exist in project root with API keys
Posse only: yq and jq must be installed (brew install yq jq)

Examples

# First-time single agent deploy
railway login
randal deploy agent

# Deploy a 10-agent company
randal deploy posse --name acme-corp --config examples/railway-posse/full-company.yaml

# Update env vars without redeploying
randal deploy env

# Clean up
randal deploy delete acme-corp

📚 Skills Commands

`randal skills list`

List all available skills (bundled + workspace).

`randal skills search <query>`

Search skills by name or content.

`randal skills show <name>`

Display a skill's full documentation.

📡 HTTP API Endpoints

When running in daemon mode (randal serve), the following REST endpoints are available. All endpoints except GET / require Bearer token authentication.

Method	Path	Description
`GET`	`/`	📡 Dashboard (HTML)
`GET`	`/health`	💚 Health check: `{ status, uptime, version, updateChannel }`
`GET`	`/audit`	🔍 Ambient auth audit report (JSON)
`GET`	`/instance`	🪪 Instance info: name, posse, status, version, capabilities
`POST`	`/job`	📨 Submit job: `{ prompt, specFile?, agent?, model?, maxIterations?, workdir? }`
`GET`	`/job/:id`	📊 Get job details
`GET`	`/jobs`	📋 List jobs. Optional `?status=` filter.
`DELETE`	`/job/:id`	🛑 Stop a running job
`POST`	`/job/:id/context`	💉 Inject context: `{ text }`
`GET`	`/events`	📡 SSE event stream
`GET`	`/memory/search`	🔍 Search memory: `?q=&limit=`
`GET`	`/memory/recent`	🧠 Recent memories: `?limit=`
`GET`	`/config`	⚙️ Sanitized config (credentials redacted)
`GET`	`/scheduler`	⏰ Scheduler status: heartbeat, cron, hooks
`POST`	`/heartbeat/trigger`	💓 Force an immediate heartbeat tick
`GET`	`/cron`	📅 List all cron jobs
`POST`	`/cron`	➕ Add a runtime cron job: `{ name, schedule, prompt, execution? }`
`DELETE`	`/cron/:name`	➖ Remove a cron job
`POST`	`/hooks/wake`	🪝 Wake hook: `{ text, mode }` (requires hook token)
`POST`	`/hooks/agent`	🤖 Agent hook: `{ message, wakeMode?, model? }` (requires hook token)

📅 Cron Commands

`randal cron list`

List all registered cron jobs on a running instance.

randal cron list
randal cron list --url http://remote:7600

`randal cron add`

Add a runtime cron job.

randal cron add my-job --schedule "0 8 * * *" --prompt "Morning briefing" --isolated
randal cron add check --schedule 30m --prompt "Check health"

Flag	Type	Description
`--schedule`	string	Cron expression, duration (30m), or ISO datetime
`--prompt`	string	The prompt to execute
`--isolated`	flag	Use isolated execution (default: main/heartbeat)
`--model`	string	Override model

`randal cron remove`

Remove a cron job by name.

randal cron remove my-job

💓 Heartbeat Commands

`randal heartbeat status`

Show heartbeat state: last tick, next tick, tick count, pending wake items.

randal heartbeat status

`randal heartbeat trigger`

Force an immediate heartbeat tick (bypasses active hours).

randal heartbeat trigger

🔧 Init Modes

`randal init` (default)

Interactive onboarding with environment auto-detection. Presents a choice between ⚡ QuickStart (3 questions, smart defaults) and 🔧 Advanced (full wizard walking through every config section).

Auto-detects:

🖥️ Platform (macOS / Linux)
🔌 Installed agent CLI (opencode)
🔍 Running Meilisearch instance

`randal init --wizard`

Jump straight to the Advanced wizard flow (bypasses QuickStart/Advanced selection).

`randal init --from <path>`

Bootstrap from an existing config file. Validates, fills gaps with defaults, and writes a merged result.

randal init --from ~/backups/randal.config.yaml

`randal init --yes`

Non-interactive mode. Uses auto-detected values and all defaults. Useful for Docker builds and CI.

🌐 Mesh Commands

`randal mesh status`

Show all instances in the mesh with health, load, specialization, and reliability scores.

randal mesh status
randal mesh status --url http://remote:7600

`randal mesh route <prompt>`

Dry-run the routing algorithm and show which instance would handle the task and why.

randal mesh route "build a React component"

📊 Analytics Commands

`randal analytics scores`

Show reliability scores broken down by agent, model, and domain.

randal analytics scores
randal analytics scores --url http://remote:7600

`randal analytics recommendations`

Show current actionable recommendations based on annotation patterns.

randal analytics recommendations

🎙️ Voice Commands

`randal voice status`

Show active voice sessions with duration and transcript length.

randal voice status

⚠️ Deprecation: `agent/setup.sh`

The agent/setup.sh script is deprecated and will be removed in a future version. Use randal setup instead.

Migration:

# Old way (deprecated)
bash agent/setup.sh

# New way
randal setup

randal setup is a superset of agent/setup.sh with several improvements:

Config-driven: Generates opencode.json from randal.config.yaml instead of using hardcoded paths
Dynamic MCP wiring: MCP servers are included based on your capabilities and config, not hardcoded
Cross-platform: TypeScript-based, not bash-only
Dry-run support: Preview changes before applying with --dry-run
Validation companion: Pair with randal doctor to verify your deployment

The old script continues to work but prints a deprecation warning. If the randal CLI is available on PATH, it will suggest using randal setup instead.

CLI reference

💻 CLI Reference

🎬 Two Modes

🌐 Global Options

📋 Commands

🔧 randal init

🧹 randal reset

🎯 randal run <prompt|file>

🏗️ randal serve

📨 randal send <prompt|file>

📊 randal status [job-id]

📋 randal jobs

🛑 randal stop <job-id>

💉 randal context [job-id] <text>

🔄 randal resume <job-id>

🧠 randal memory <subcommand>

randal memory search <query>

randal memory list

randal memory add <content>

🔍 randal audit

🔩 randal setup

🩺 randal doctor

⬆️ randal update

🚀 randal deploy