> ## 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`) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.