Skip to main content

ludus info — Read-Only Queries

What It Does​

The ludus info subcommand group provides read-only queries against the ludus host and the local workspace. Safe for agents — no state changes, no LLM tokens.

Subcommands: status, doctor, cron, images, agents, beads.

(Skipped: logs, observe, replay — these exec into long-running processes and are not suitable for showboat recording.)

Environment​

  • Working directory: ludus/
  • Ludus host reachable via SSH
  • OpenClaw gateway running on the ludus host
  • bd available locally and remotely
  • ludus CLI installed (uv run ludus or ludus)

1. Bare invocation​

The bare ludus command gives a one-line summary with next-step hints.

ludus

Verify​

  • Output contains "Ludus" and a summary line (agents, images, cron jobs, gateway)
  • Exit code 0
ludus --json

Verify​

  • Valid JSON with keys: summary, reachable, agents, images, cron_jobs, gateway
  • reachable is true
  • next array contains hint commands

2. ludus info status​

Full system dashboard — images, agents, sandbox, cron, gateway.

ludus info status

Verify (human)​

  • Output contains sections: "Container Images", "Registered Agents", "Gateway"
  • Exit code 0
ludus --json info status

Verify (JSON)​

  • Valid JSON with status object
  • status.images is a dict mapping image names to booleans
  • status.agents.count >= 1
  • status.gateway is a boolean
  • status.cron.installed is a boolean

3. ludus info doctor​

Health check suite with PASS/FAIL per check.

ludus info doctor

Verify (human)​

  • Output contains "Checking ludus health"
  • Shows green checkmarks or red crosses
  • Shows "Summary: N errors, N warnings"
  • Exit code 0 if all checks pass, 1 if errors
ludus --json info doctor

Verify (JSON)​

  • Valid JSON with errors, warnings, checks, summary keys
  • summary.errors + summary.warnings + summary.ok = total checks
  • Each error/warning has check, ok, detail fields
  • Errors with fix field suggest a remediation command

4. ludus info cron​

Show b4arena crontab entries installed on the ludus host.

ludus info cron

Verify (human)​

  • Output shows cron entries (lines between b4arena-begin and b4arena-end)
  • Or "No b4arena cron entries found" if none installed
  • Exit code 0
ludus --json info cron

Verify (JSON)​

  • Valid JSON with entries array
  • Each entry is a crontab line string
  • If entries exist, at least one mentions beads-watcher

5. ludus info images​

List expected container images on the ludus host with presence check.

ludus info images

Verify (human)​

  • Shows each expected image with a status indicator
  • Expected images: openclaw-sandbox:fedora, openclaw-sandbox-common:fedora, b4arena-base:latest, b4arena-dev:latest
  • Exit code 0
ludus --json info images

Verify (JSON)​

  • Valid JSON with images dict
  • Keys are image names, values are booleans
  • All 4 expected images are listed

6. ludus info agents​

List registered agents from OpenClaw.

ludus info agents

Verify (human)​

  • Output shows registered agent IDs (e.g., main, b4-dev, b4-eng-mgr)
  • Exit code 0
ludus --json info agents

Verify (JSON)​

  • Valid JSON with agents object containing count and agents array
  • count >= 1
  • agents array contains agent ID strings

7. ludus info intercom​

Show shared intercom status on the ludus host — open work, ready, blocked.

ludus info intercom

Verify​

  • Shows "Intercom ()" header
  • Shows summary: Total, Open, In progress, Ready, Blocked counts
  • Exit code 0
ludus --json info intercom

Verify​

  • Valid JSON with intercom object
  • intercom has keys: total, open, in_progress, ready, blocked, issues
  • issues is an array (may be empty)
  • Counts are non-negative integers

8. ludus --version​

ludus --version

Verify​

  • Output matches pattern ludus N.N.N
  • Exit code 0

Edge Cases​

Host unreachable​

If the ludus host is unreachable (e.g., network down), commands should degrade gracefully:

LUDUS_HOST=nonexistent ludus --json 2>&1 || true

Verify​

  • JSON output with reachable: false
  • No stack trace
  • Exit code 0 (bare) or 1 (doctor)