💻 CLI Reference

🤠 randal — agent harness v0.2

🎬 Modes

Randal operates in three modes with different execution models:

💻 randal — Interactive OpenCode terminal entrypoint. Spawns the opencode binary with inherited stdin/stdout/stderr. It does not auto-install OpenCode or wait for self-heal before opening the TUI; run randal setup if the binary is missing.

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

🏗️ randal serve — Daemon. Starts the Randal Console, HTTP API, SSE event stream, Postgres-backed job persistence, memory integration, and operational status. Jobs run in the background, and daemon startup does not block on local OpenCode install/self-heal checks.

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

randal --help and randal --version are Randal CLI global flags. Unknown commands remain Randal errors and are not passed through to OpenCode.

🌐 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`

Open the interactive OpenCode terminal experience with inherited stdin/stdout/stderr:

randal

Bare randal requires opencode to be resolvable on PATH. If it is missing, Randal prints an actionable error and exits non-zero without installing anything automatically. Use randal setup for guided runtime setup.

Startup self-heal and diagnostics run in the background after launch. If generated OpenCode config or plugin assets are repaired after the TUI has already loaded, run randal diagnostics and restart Randal/OpenCode when prompted so the current session picks up the repaired config.

🩺 `randal diagnostics`

Read or refresh persistent startup diagnostics:

randal diagnostics
randal diagnostics --json
randal diagnostics --refresh

Diagnostics are stored as redacted JSON under the active workspace at .randal/diagnostics/startup.json, or under the configured Randal state directory when no workspace config is available. Missing connector secrets are reported here with connector IDs, secret names, labels, and remediation commands. Secret values, raw environment values, bearer tokens, signed URLs, and full database URLs are not written to diagnostics.

Use --refresh for explicit troubleshooting. Normal randal and randal serve startup schedules diagnostics in the background instead of waiting for config freshness checks, connector secret scans, Postgres setup, plugin install, or other non-critical repair work.

🔧 `randal init`

Create durable Randal source-of-truth config/persona artifacts in the current directory. Features an interactive onboarding wizard with environment auto-detection; use --full for scripted one-step onboarding that also regenerates the OpenCode runtime wiring.

randal init              # Interactive — QuickStart or Advanced, then offers runtime setup
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 durable config/persona defaults
randal init --from <path> # Bootstrap durable config from existing config
randal init --full       # Scripted one-step init + setup runtime generation

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 local config + scheduler/cache state (preserves .env and Postgres 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`, and `~/.randal`. 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/cron.yaml (cron scheduler state)

Default reset preserves:

.env (contains your API keys)
Postgres data (memory, chat, jobs, mesh, checkpoints, and audit rows)
~/.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
Local Postgres/legacy containers only when explicitly selected by the reset flow

🎯 `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 optional daemon: Randal Console + gateway + runner.

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. Randal Console is available at the root URL. Local direct OpenCode use does not require randal serve; after randal setup, cd any-project && opencode uses the generated MCP config and local Postgres source of truth directly.

randal serve starts the gateway without checking or installing OpenCode first. Non-critical startup diagnostics/self-heal work is scheduled separately and can be inspected with randal diagnostics.

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 Console 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 connector <subcommand>`

Manage optional guided connectors. Built-in connectors currently include tavily, image, and video.

randal connector list
randal connector secret set tavily TAVILY_API_KEY --value "$TAVILY_API_KEY"
randal connector enable tavily
randal connector doctor tavily
randal connector disable tavily
randal connector mcp tavily tavily --config ./randal.config.yaml

Subcommand	Description
`list`	Show built-in connectors and enabled state.
`enable <name>`	Add or update `connectors.<name>` in the file-backed config and enable it for new sessions.
`disable <name>`	Mark the connector disabled without deleting stored secrets.
`secret set <name> <SECRET> [--value <value>]`	Store a connector secret through the configured secret provider. Values are redacted in CLI output. If `--value` is omitted, the value is read from stdin.
`doctor <name>`	Show configured/enabled state and redacted secret presence.
`mcp <name> <server-id>`	Internal standalone OpenCode launcher. Loads connector secrets from the configured `SecretProvider`, then starts or proxies the selected MCP server without printing raw secrets.

Connector CLI commands do not print raw secret values. After enable/disable or secret changes, randal serve can remain running; start a new brain session or reload active work for updated tools/credentials. For standalone local use, run randal setup --config <path> once after connector changes, then open plain opencode; generated MCP entries call randal connector mcp ... --config <path> so connector secrets stay in Randal's local secret provider instead of your shell environment.

The Console provides the guided catalog and setup-assistant flow when users need help finding credentials or understanding settings. See Connectors and Secret Providers.

🧠 `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`

Regenerate/sync disposable OpenCode runtime wiring from durable Randal config/persona artifacts. This command writes opencode.json, MCP/connectors, skills, plugins, symlinks, and local runtime paths. It replaces agent/setup.sh and is idempotent/safe to rerun after connector or config changes.

randal setup                  # Bootstrap local Postgres, 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	Direct output directory. By default, setup writes to `.randal/opencode/` and symlinks `~/.config/opencode`; `--output` bypasses public symlink management.
`--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.
`--skip-postgres-ensure`	flag	Skip local Postgres bootstrap. Intended for advanced automation/testing only.
`--verbose`	flag	Show which MCP servers are included, why, which capabilities were detected, and identity resolution details.

What it does:

Reads durable randal.config.yaml/persona artifacts (or the file given by --config)
Ensures local Postgres is running, migrated, and writable for the default local profile
Compiles opencode.json from opencode.base.json + config values (MCP servers, tool permissions, capabilities)
Writes the generated opencode.json to .randal/opencode/opencode.json and symlinks ~/.config/opencode
Symlinks static content (agents/, assets/, 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 after connector/config changes, updates, stale generated paths, local runtime repair, or post-rebase path changes. Startup diagnostics may self-heal known missing/stale generated runtime config in the background; inspect with randal diagnostics, and repair explicitly with randal doctor --fix or randal setup --config <path> from a durable checkout. Existing non-symlink entries are backed up before replacement. The default local workflow is randal setup once, then cd any-project && opencode; generated memory/chat/graph/job MCP tools use persistent Postgres without starting the Randal gateway.

Generated OpenCode permissions include external_directory allowances for Randal-managed temp worktrees and macOS temp paths (/tmp, /private/tmp, and per-user temp directories under /var/folders) so local build orchestration does not repeatedly prompt for those paths. Randal does not broadly allow unrelated tool permissions by default.

assets/randal-logo.txt is a Randal-shipped ASCII/dither logo asset based on assets/posse.png. tui.json loads plugins/randal-logo.tsx through OpenCode's supported top-level plugin array; the plugin registers a home_logo slot replacement so the OpenCode home screen renders the Randal logo after setup and a fresh OpenCode start. Randal does not add unsupported logo or banner fields to tui.json.

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 db`

Manage Postgres source-of-truth operations for local, CI, and managed Railway deployments.

randal db start
randal db status --write-check
randal db migrate --config randal.config.railway.yaml
randal db dump --file ./db-dumps/randal.dump --output-dir ./db-dumps
randal db verify-dump --file ./db-dumps/randal.dump
randal db restore --file ./db-dumps/randal.dump --force --confirm restore-postgres
randal db copy --target-url "$TARGET_DATABASE_URL" --force --confirm copy-postgres
randal db scoped-export --file ./project.json --org-id "$ORG_ID" --project-id "$PROJECT_ID"
randal db scoped-import --file ./project.json --force --confirm import-scoped-postgres
randal db scoped-copy --target-url "$TARGET_DATABASE_URL" --force --confirm copy-scoped-postgres

Subcommand	Description
`start`	Starts the local Postgres + pgvector Docker Compose service without deleting volumes.
`status`	Checks database reachability, schema presence, migration version, required extensions, and redacts the URL in output.
`migrate`	Applies portable Postgres migrations idempotently.
`reset`	Drops and recreates the configured schema. Requires `--force --confirm reset-postgres`.
`dump`	Runs `pg_dump --format=custom --no-owner --no-acl`, then writes `<dump>.manifest.json` with redacted database, migration, extension, fingerprint, row-count, checksum, and created-at metadata.
`restore`	Verifies the adjacent dump manifest, checks the target schema for existing source-of-truth rows, then runs `pg_restore --clean --if-exists --no-owner --no-acl`. Requires `--force --confirm restore-postgres`.
`verify-dump`	Validates the adjacent dump manifest version and redaction posture without writing to a database.
`copy`	Dumps the configured/source database and restores into `--target-url`. Requires `--force --confirm copy-postgres`.
`scoped-export`	Writes an application-level JSON snapshot for one org/project across memory, chat, graph, jobs, mesh, artifacts, annotations, delegations, and related metadata. This is distinct from full `pg_dump`.
`scoped-import`	Imports a scoped JSON snapshot into the configured/target database. Non-empty target scopes require `--force --confirm import-scoped-postgres`.
`scoped-copy`	Exports one org/project from the configured/source database and imports it into `--target-url` without invoking `pg_dump`/`pg_restore`. Requires `--force --confirm copy-scoped-postgres`.

Railway operators should source database URLs from Railway secrets or private CLI output, not from logs. The dump manifest deliberately stores only redacted URLs and must not include raw DATABASE_URL, service-role keys, or artifact signed URLs.

Full dump/restore is for whole-database or whole-schema movement. Project/org-scoped movement should use scoped-export, scoped-import, or scoped-copy so one project is not restored over an entire cloud database.

🩺 `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
Postgres	Source-of-truth health, migration, extension, and writeability checks pass when 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] Postgres: source-of-truth database is reachable, migrated, and writable
  [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. New deployments should use shared Postgres for memory, mesh registry, jobs, and audit. 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`	`/`	🖥️ Randal Console (HTML)
`POST`	`/api/sessions`	💬 Create or reuse a Console/custom-relay session
`GET`	`/api/sessions`	💬 List Console/custom-relay sessions
`GET`	`/api/sessions/:id`	💬 Get one session with recent messages
`POST`	`/api/sessions/:id/messages`	💬 Submit a user message and start session work
`GET`	`/api/sessions/:id/events`	📡 Session-filtered SSE event stream
`POST`	`/api/sessions/:id/context`	💉 Inject context into active session work
`POST`	`/api/sessions/:id/stop`	🛑 Stop active session work
`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)
🗄️ Postgres availability for source-of-truth persistence

`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

🎬 Modes

🌐 Global Options

📋 Commands

💻 randal

🩺 randal diagnostics

🔧 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 connector <subcommand>

🧠 randal memory <subcommand>

randal memory search <query>

randal memory list

randal memory add <content>

🔍 randal audit

🔩 randal setup

🗄️ randal db

🩺 randal doctor

⬆️ randal update

🚀 randal deploy