Skip to main content
ralphy setup configures keys and links a project the first time. ralphy doctor verifies env health on every run after that. Together they cover bootstrap, recovery, and CI gating. Both emit JSON by default — the agent reads doctor on session start to decide whether to ask the user for a missing key.

​
ralphy setup

The first-run wizard. Interactive on TTY, scriptable with --non-interactive. Reads OPENROUTER_API_KEY and ELEVENLABS_API_KEY, optionally pings each provider to verify, writes to <project>/.env, optionally imports public profiles. 
# Interactive — TUI walks you through the keys
ralphy setup

# Non-interactive: take keys from env
ralphy setup -y --keys-from-env

# Non-interactive: explicit keys
ralphy setup -y \
  --openrouter-key sk-or-... \
  --elevenlabs-key xi-...

# Read a key from stdin (pipe-friendly)
cat openrouter.key | ralphy setup -y --openrouter-key -

# Re-link to a different project checkout
ralphy setup --link /path/to/ugc-cli
ralphy setup --unlink           # remove the global link

# Capability-only status (no TUI)
ralphy setup --status
The non-interactive path is implied whenever any of --openrouter-key, --elevenlabs-key, --keys-from-env, --project-dir, or --import-profile is set, so you can drop the explicit -y/--non-interactive in CI scripts. By default setup verifies each key with a live API ping. Pass --no-verify to skip; pass --allow-unverified to save a key anyway when verification fails. Full flag detail: /reference/cli/setup.

​
ralphy doctor

Env health check. No prompts, no writes — just a JSON report. 
ralphy doctor
The report includes:
  • ralphy.version and install mode (developer from a repo checkout, binary from a release artifact)
  • ralphy.linkedProject — the path resolved by project auto-detection
  • deps.{bun,ffmpeg} — both are required
  • keys — one boolean per OPENROUTER_API_KEY, ELEVENLABS_API_KEY
  • blockers and warnings — concrete remediation strings
  • versions.{current,latest,update_hint} — when a newer release is available
✦ ralphy v0.3.0
  cwd      /Users/you/work/ugc-cli
  project  /Users/you/work/ugc-cli

▸ Dependencies
  ✓ bun
  ✓ ffmpeg

▸ API keys
  ✓ OPENROUTER_API_KEY      OpenRouter
  ✗ ELEVENLABS_API_KEY      ElevenLabs

▸ Blockers (1)
  ✖ ELEVENLABS_API_KEY missing — ElevenLabs required. Run `ralphy setup`.
Exit code is non-zero when blockers is non-empty — the canonical CI guard. 
ralphy doctor --json | jq -e '.blockers | length == 0'

​
Update checks

doctor checks for a newer release once per 24 hours. The network call is bounded by a 5-second timeout; failure is silent. Disable with: 
export RALPHY_DOCTOR_NO_UPDATE_CHECK=1
# or
ralphy config set doctor.checkUpdates false
When an update is available, versions.update_hint contains the right command for your install (brew upgrade ralphy vs npm update -g @alecs5am/ralphy).

​
Common failures

SymptomRemediation
bun is not installedbrew install bun
ffmpeg is not installedbrew install ffmpeg
OPENROUTER_API_KEY missingralphy setup and paste, or export OPENROUTER_API_KEY=...
ralphy is not linked to a projectcd into your checkout, or ralphy setup --link <path>
Linked project ... has no package.jsonThe project moved. Re-link with ralphy setup --link <new-path>
Every blocker line in doctor’s output names the verb that fixes it. Full error code coverage is on Error catalog.

​
After a fix

Re-run doctor to verify. It’s idempotent and cheap (no model calls): 
ralphy doctor && echo "ready"
When the agent runs doctor on session start and sees a blocker, it walks the user through the remediation and then re-runs doctor until it’s green — that’s all there is to the “core” playbook.