> ## Documentation Index
> Fetch the complete documentation index at: https://docs.feral.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> Complete reference for the feral command-line tool — all subcommands, options, and exit codes.

## Synopsis

```bash theme={null}
feral <command> [options]
```

The `feral` CLI is the primary interface for managing the FERAL brain, dashboard, and development tools.

Global connection options apply to all subcommands:

| Option   | Default     | Description                  |
| -------- | ----------- | ---------------------------- |
| `--host` | `localhost` | Brain hostname to connect to |
| `--port` | `9090`      | Brain port to connect to     |

## Commands

### `feral` (no subcommand)

Launch the interactive REPL. Connects to the brain via WebSocket and presents a chat prompt.

```bash theme={null}
feral
```

REPL slash-commands: `/status`, `/devices`, `/skills`, `/identity`, `/quit`.

### `feral "message"`

One-shot mode. Sends a single message to the brain, prints the response, and exits.

```bash theme={null}
feral "search the web for FERAL AI reviews"
```

### `feral start`

Start the brain, wait for health, optionally open the dashboard in a browser, then drop into the interactive REPL. If this is the first run, the setup wizard launches automatically.

```bash theme={null}
feral start [options]
```

| Option             | Default | Description                               |
| ------------------ | ------- | ----------------------------------------- |
| `--serve-port <n>` | `9090`  | Brain server port                         |
| `--no-browser`     | —       | Skip opening the dashboard in the browser |

<CodeGroup>
  ```bash Default theme={null}
  feral start
  ```

  ```bash Custom port, no browser theme={null}
  feral start --serve-port 8080 --no-browser
  ```
</CodeGroup>

### `feral serve`

Start only the brain API server (headless, no REPL, no browser).

```bash theme={null}
feral serve [options]
```

| Option             | Default     | Description  |
| ------------------ | ----------- | ------------ |
| `--bind <addr>`    | `127.0.0.1` | Bind address |
| `--serve-port <n>` | `9090`      | Server port  |

Useful for production deployments or when running the dashboard separately.

<CodeGroup>
  ```bash Default theme={null}
  feral serve
  ```

  ```bash Public bind, custom port theme={null}
  feral serve --bind 0.0.0.0 --serve-port 8080
  ```
</CodeGroup>

### `feral setup`

Run the interactive setup wizard.

```bash theme={null}
feral setup
```

Walks through LLM provider selection, API key storage, USER.md creation, and autonomy mode configuration. Generates a session token on first run. Safe to re-run — only overwrites values you change.

### `feral status`

Show the current state of the running brain (sessions, devices, skills, LLM, audio, sync, memory).

```bash theme={null}
feral status
```

### `feral devices`

List all connected hardware devices.

```bash theme={null}
feral devices
```

### `feral skills`

List all loaded skills.

```bash theme={null}
feral skills
```

### `feral identity`

Show the agent's name, personality, rules, and communication style.

```bash theme={null}
feral identity
```

### `feral pair`

Manage per-node device pairing tokens for session authentication.

```bash theme={null}
feral pair [options]
```

| Option                 | Description                                              |
| ---------------------- | -------------------------------------------------------- |
| `--name <name>`        | Friendly name for the new device (default: "unnamed")    |
| `--list`               | List all paired devices                                  |
| `--revoke <device_id>` | Revoke a device by its ID                                |
| `--prune <seconds>`    | Revoke unclaimed tokens older than N seconds (`0` = all) |

<CodeGroup>
  ```bash Pair a new device theme={null}
  feral pair --name "MacBook Pro"
  ```

  ```bash List paired devices theme={null}
  feral pair --list
  ```

  ```bash Revoke a device theme={null}
  feral pair --revoke abc123def456
  ```

  ```bash Prune unclaimed tokens theme={null}
  feral pair --prune 0
  ```
</CodeGroup>

### `feral access`

Manage pairing access mode and remote tunnel state.

```bash theme={null}
feral access <action>
```

| Action        | Description                                          |
| ------------- | ---------------------------------------------------- |
| `status`      | Show pairing mode + Tailscale status                 |
| `remote-up`   | Enable Tailscale Funnel and switch to remote pairing |
| `remote-down` | Disable Funnel and switch back to localhost mode     |

<CodeGroup>
  ```bash Show current mode theme={null}
  feral access status
  ```

  ```bash Enable Anywhere mode theme={null}
  feral access remote-up
  ```

  ```bash Disable Anywhere mode theme={null}
  feral access remote-down
  ```
</CodeGroup>

### `feral wake-test`

Test wake word detection from your microphone for 10 seconds.

```bash theme={null}
feral wake-test
```

Requires `openwakeword` and `pyaudio`. Reports detection count and mode (ML or energy-based fallback).

### `feral marketplace`

Skill marketplace commands.

```bash theme={null}
feral marketplace <action> [query]
```

| Action               | Description                        |
| -------------------- | ---------------------------------- |
| `search [query]`     | Search for skills (default action) |
| `install <skill_id>` | Install a skill by ID              |
| `list`               | List installed marketplace skills  |

<CodeGroup>
  ```bash Search theme={null}
  feral marketplace search "web scraping"
  ```

  ```bash Install theme={null}
  feral marketplace install weather-skill
  ```

  ```bash List installed theme={null}
  feral marketplace list
  ```
</CodeGroup>

### `feral sync`

Federated memory sync commands.

```bash theme={null}
feral sync <action> [file]
```

| Action          | Description                                                               |
| --------------- | ------------------------------------------------------------------------- |
| `status`        | Show sync engine state, node ID, peer count, vector clock (default)       |
| `peers`         | List discovered peers                                                     |
| `export [file]` | Export memory bundle to a JSON file (default: `feral_memory_export.json`) |
| `import <file>` | Import a memory bundle from a JSON file                                   |

<CodeGroup>
  ```bash Check sync status theme={null}
  feral sync status
  ```

  ```bash List peers theme={null}
  feral sync peers
  ```

  ```bash Export memory theme={null}
  feral sync export backup.json
  ```

  ```bash Import memory theme={null}
  feral sync import backup.json
  ```
</CodeGroup>

### `feral doctor`

Run comprehensive diagnostics and report what's working, what's missing, and suggested fixes.

```bash theme={null}
feral doctor
```

Checks: Python version, FERAL package, config directory, LLM credentials (keys + Ollama), identity files, memory database, port availability, Playwright/chromium, Node.js, local audio backends (faster-whisper, piper), and core dependencies.

## Exit Codes

| Code  | Meaning                            |
| ----- | ---------------------------------- |
| `0`   | Success                            |
| `1`   | General error / connection failure |
| `130` | Interrupted by `Ctrl+C`            |