Skip to main content

​
Synopsis

feral <command> [options]
The feral CLI is the primary interface for managing the FERAL brain, dashboard, hardware, and development tools.

​
Commands

​
feral start

Start the brain, dashboard, and voice pipeline. 
feral start [options]
OptionDefaultDescription
--no-dashboard—Start brain only, skip the web UI
--no-voice—Disable voice pipeline
--port <n>9090Brain port
--dashboard-port <n>3000Dashboard port
--log-level <level>infodebug, info, warn, error
--detach—Run in background (daemonize)
feral start

​
feral stop

Gracefully stop all running FERAL processes. 
feral stop
Sends SIGTERM to the brain, dashboard, and any voice/hardware processes. Returns exit code 0 on success.

​
feral serve

Start only the brain API server (no dashboard, no REPL). 
feral serve [options]
OptionDefaultDescription
--port <n>9090API port
--host <addr>0.0.0.0Bind address
--workers <n>1Number of uvicorn workers
Useful for production deployments or when running the dashboard separately.

​
feral setup

Run the interactive setup wizard. 
feral setup
Walks through LLM provider selection, API key storage, USER.md creation, and autonomy mode configuration. Safe to re-run — only overwrites values you change.

​
feral status

Show the current state of all FERAL components. 
feral status [--json]

Brain       ● running   ws://localhost:9090   PID 48201
Dashboard   ● running   http://localhost:3000  PID 48215
Voice       ● active    wake word listening
Hardware    ● 2 devices FERAL-Wristband-A3F2, Home-Assistant
Memory      ● sqlite    ~/.feral/memory.db (142 episodes)
Autonomy    ● hybrid    3 safe / 2 risky categories
Use --json for machine-readable output: 
feral status --json

{
  "brain": { "status": "running", "port": 9090, "pid": 48201 },
  "dashboard": { "status": "running", "port": 3000, "pid": 48215 },
  "voice": { "status": "active", "mode": "wake_word" },
  "hardware": { "devices": 2 },
  "memory": { "backend": "sqlite", "episodes": 142 }
}

​
feral doctor

Run diagnostic checks and report issues. 
feral doctor

✓ Python 3.11.8
✓ Node 20.11.0
✓ pip dependencies satisfied
✓ Brain port 9090 available
✓ Dashboard port 3000 available
✓ Ollama detected at localhost:11434
✓ BLE adapter available
✗ Playwright chromium not installed — run: playwright install chromium
✓ Credentials vault readable
✓ Memory database accessible
feral doctor checks:
  • Python and Node versions
  • All pip/npm dependencies
  • Port availability
  • LLM provider connectivity
  • BLE adapter presence
  • Playwright browser (for computer-use)
  • Credential vault integrity
  • Memory database access

​
feral demo

Run a pre-built demo scenario. 
feral demo --scenario <name>
ScenarioDescription
morningSimulated morning routine with health briefing
developerDeveloper flow with screen context and proactive help
meshMulti-device mesh with phone, wristband, glasses
twinDigital twin Q&A session
feral demo --scenario morning

​
feral hardware

Manage hardware devices. 
feral hardware <subcommand>
SubcommandDescription
scanScan for nearby BLE devices
scan --type <type>Scan for specific type (wristband, glasses)
listList all connected devices
pair <device>Pair a device by name or ID
unpair <device>Unpair a device

​
Global Options

OptionDescription
--versionPrint version and exit
--helpShow help for any command
--config <path>Use a specific config file
--quietSuppress non-error output
--verboseIncrease output verbosity

​
Exit Codes

CodeMeaning
0Success
1General error
2Invalid arguments or usage
3Configuration error (missing key, invalid file)
4Port already in use
5LLM provider unreachable
6Hardware error (BLE adapter missing, device not found)
130Interrupted by Ctrl+C