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

# CLI reference

> rockbox and rockboxd — the two binaries you'll interact with.

There are two binaries:

* **`rockbox`** — user-facing wrapper. Starts the server, scans the
  library, opens the web UI, manages the systemd service, runs JS/TS
  scripts, and acts as a Bluetooth client on Linux.
* **`rockboxd`** — the daemon itself. Linked by Zig from the C firmware
  * Rust crates + CPAL. Lives at `zig/zig-out/bin/rockboxd` after a build,
    or `/usr/local/bin/rockboxd` after install.

Most users only ever invoke `rockbox`; `rockboxd` is the underlying
process it spawns.

## `rockbox`

```text theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
rockbox [--rebuild] [SUBCOMMAND]
```

Running `rockbox` with no subcommand starts the server. The subcommands
below are dispatched in `cli/src/main.rs`.

### Global flags

| Flag              | Description                                   |
| ----------------- | --------------------------------------------- |
| `--rebuild`, `-r` | Rebuild the Typesense search index after scan |
| `-h`, `--help`    | Print help                                    |
| `-V`, `--version` | Print the version                             |

### Subcommands

| Subcommand                     | Aliases | Description                                              |
| ------------------------------ | ------- | -------------------------------------------------------- |
| *(none)*                       |         | Start the server                                         |
| `start [-r]`                   |         | Start the server                                         |
| `scan [-d PATH] [-r]`          |         | Scan a library directory; `-r` rebuilds the search index |
| `webui`                        | `web`   | Open the web UI in your browser                          |
| `tui`                          |         | Start the terminal UI                                    |
| `repl`                         | `shell` | Start the Rockbox REPL                                   |
| `run <FILE>`                   | `x`     | Run a JS/TS script via Deno against the local rockboxd   |
| `open <PATH_OR_URL>`           |         | Play a local file or HTTP URL directly                   |
| `clear`                        |         | Clear the current playlist                               |
| `service install`              |         | Install + enable the systemd unit                        |
| `service uninstall`            |         | Disable + remove the systemd unit                        |
| `service status`               |         | Show the unit status                                     |
| `login <handle>`               | `auth`  | Log in to Rocksky (BlueSky handle)                       |
| `whoami`                       | `me`    | Show the currently logged-in user                        |
| `community`                    |         | Open the Discord invite                                  |
| `setup`                        |         | Install host dependencies (CPAL, etc.)                   |
| `bluetooth scan [--timeout S]` |         | Linux only — scan for Bluetooth devices                  |
| `bluetooth devices`            |         | Linux only — list known devices                          |
| `bluetooth connect <ADDR>`     |         | Linux only — connect to a device                         |
| `bluetooth disconnect <ADDR>`  |         | Linux only — disconnect a device                         |

### Examples

```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
# Start the daemon
rockbox start

# Scan the default music_dir, rebuild the search index
rockbox scan -r

# Scan a specific path
rockbox scan -d "/Volumes/Music/Recently Added"

# Play a URL
rockbox open "https://stream.example.com/jazz.mp3"

# Install as a systemd user service
rockbox service install
rockbox service status

# Run a small script against a local rockboxd
rockbox run scripts/scrobble.ts

# Bluetooth (Linux)
rockbox bluetooth scan --timeout 15
rockbox bluetooth connect AA:BB:CC:DD:EE:FF
```

## `rockboxd`

The daemon. Usually you don't run it directly — `rockbox start` or the
systemd unit handles it. When you do need to invoke it manually, most
configuration is driven by environment variables and
`~/.config/rockbox.org/settings.toml`. A small set of subcommands are
also available for account management and settings sync; they exit the
process immediately without starting the Zig firmware or any servers.

```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
rockboxd [SUBCOMMAND]
```

### Subcommands

| Subcommand                              | Description                                           |
| --------------------------------------- | ----------------------------------------------------- |
| *(none)*                                | Start the daemon (server + firmware)                  |
| `login <handle>`                        | Log in to Rocksky with your Bluesky handle            |
| `whoami`                                | Print the currently logged-in Rocksky user            |
| `settings pull [--did <DID_OR_HANDLE>]` | Pull audio settings from Rocksky into `settings.toml` |
| `settings push`                         | Push `settings.toml` audio settings to Rocksky        |

#### `login <handle>`

Opens the Rocksky OAuth authorisation URL in your default browser and
listens on `localhost:6996` for the callback. On success the token is
saved to `~/.config/rockbox.org/token`.

```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
rockboxd login alice.bsky.social
```

#### `whoami`

Reads the stored token and resolves the Rocksky account associated with it.

```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
rockboxd whoami
```

#### `settings pull`

Downloads your audio settings (equalizer, crossfade, replaygain, tone)
from Rocksky and merges them into `~/.config/rockbox.org/settings.toml`.
All other fields in `settings.toml` (e.g. `music_dir`, `audio_output`)
are left untouched. Restart `rockboxd` to apply the new settings.

```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
# Pull your own settings (requires login)
rockboxd settings pull

# Pull another user's settings publicly — no login required
rockboxd settings pull --did alice.bsky.social
rockboxd settings pull --did did:plc:abc123
```

#### `settings push`

Reads the audio sections of `~/.config/rockbox.org/settings.toml` and
uploads them to Rocksky. Requires a stored token (`rockboxd login` first).

```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
rockboxd settings push
```

### Environment variables

| Variable                 | Default                | Description                             |
| ------------------------ | ---------------------- | --------------------------------------- |
| `RUST_LOG`               | `info`                 | Tracing filter (per-crate supported)    |
| `ROCKBOX_TCP_PORT`       | `6063`                 | HTTP REST bind port                     |
| `ROCKBOX_GRAPHQL_PORT`   | `6062`                 | GraphQL bind port                       |
| `ROCKBOX_RPC_PORT`       | `6061`                 | gRPC bind port                          |
| `ROCKBOX_MPD_PORT`       | `6600`                 | MPD bind port                           |
| `ROCKBOX_LIBRARY`        | `$HOME/Music`          | Default music library path              |
| `ROCKBOX_ADDR`           | (auto-detected LAN IP) | Address advertised to external players  |
| `ROCKBOX_UPDATE_LIBRARY` | unset                  | When `1`, rebuild Typesense on startup  |
| `HOME`                   | (system)               | Used to derive config and library paths |

### Stdout / stderr

* **Stderr** — `tracing` log output. Always safe to redirect or filter.
* **Stdout** — normally empty, **except** when `audio_output = "fifo"`
  with `fifo_path = "-"`, in which case stdout is raw S16LE 44.1 kHz PCM.

```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
rockboxd | ffplay -f s16le -ar 44100 -ac 2 -
```

### Logging

```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
RUST_LOG=debug rockboxd
RUST_LOG=rockbox_airplay=debug,rockbox_slim=debug,info rockboxd
```

Never use `eprintln!` / `println!` from inside the codebase — they
bypass the structured filter and pollute stdout (which breaks FIFO
mode). Use `tracing::{debug,info,warn,error}!` in Rust code.

### Files

| Path                                      | Purpose                                  |
| ----------------------------------------- | ---------------------------------------- |
| `~/.config/rockbox.org/settings.toml`     | Persistent configuration                 |
| `~/.config/rockbox.org/library.db`        | SQLite library + listening stats         |
| `~/.config/rockbox.org/playlists/`        | Saved playlists                          |
| `~/.config/rockbox.org/token`             | Rocksky OAuth token (written by `login`) |
| `~/.config/systemd/user/rockboxd.service` | systemd unit (after `service install`)   |