Homarr Developer CLI

Build and launch local Homarr images and GHCR pull-request builds, then manage them from responsive terminal dashboards.

Requirements

Docker or OrbStack
Go 1.25+ to build from source
GitHub CLI authenticated with gh auth login for pull-request features

Setup

pnpm install

Create .env from .env.example and set DB_URL to an absolute path for the SQLite file before running the migration. In a POSIX shell, use cp .env.example .env; in PowerShell, use Copy-Item .env.example .env. Then run pnpm db:migration:sqlite:run to create or update the database. The migration command also seeds a new database. Use pnpm db:seed explicitly when you need to seed an existing database. Start Redis separately with pnpm docker:dev:up when it is needed. The examples below use pnpm dev:cli -- ..., which works from POSIX shells and PowerShell. If you prefer a global command, install it with pnpm dev:cli:install and add your Go bin directory to PATH.

Build

pnpm dev:cli -- build feature
pnpm dev:cli -- build --pr 6441
pnpm dev:cli -- rebuild feature

Checkout builds are tagged as homarr:<name>. The source checkout and revision are recorded on the image so homarr rebuild and the development dashboard can rebuild it later. PR builds use a temporary checkout and default to homarr:pr-<number>.

Launch

pnpm dev:cli -- run dev
pnpm dev:cli -- run --detach dev
pnpm dev:cli -- run --pr 6441
pnpm dev:cli -- run --pr 6441 --demo
pnpm dev:cli -- run --env FOO=bar --env FEATURE=true dev

PR launches always pull the latest GHCR tag before starting. Local tags remain local. The first launch generates a per-user encryption key in the OS config directory and reuses it for later launches. Set HOMARR_DEV_SECRET_ENCRYPTION_KEY to a 64-character hexadecimal key to override it.

The command reference below assumes the optional homarr installation. Without it, prefix each command with pnpm dev:cli -- (for example, pnpm dev:cli -- dev).

Commands

homarr dash                Interactive instance dashboard
homarr dev                 Interactive local and remote image browser
homarr build <name>        Build this checkout as homarr:<name>
homarr build --pr <number> Build a PR locally from a temporary checkout
homarr rebuild <name>      Rebuild from recorded provenance
homarr list                Script-friendly instance list
homarr logs <container>    Follow logs
homarr open <container>    Open in browser
homarr stop <container>    Stop
homarr restart <container> Restart
homarr remove <container>  Force-remove
homarr doctor              Check Docker and optional CLI integrations

Development Browser

/              Filter by PR number, title, author, branch, CI, image, state, or port
↑/↓ or j/k     Select
Enter or Space Pull latest image and start, or stop when already running
R              Build a remote PR locally or rebuild a local image
p              Pull a remote PR image and redeploy, preserving port and volume
m              Toggle demo mode for the next launch
o              Open PR on GitHub
a              Open running app
l              Toggle inline logs for the selected running PR
f              Follow or pause inline logs
Page Up/Down   Scroll inline logs
b              Show or hide bot PRs
r              Refresh
q              Quit; during a pull, cancel it

Pull progress, layer completion, local build provenance, selected PR details, CI state, image availability, inline logs, and the final port remain inside the TUI.

Instance Dashboard

/              Filter by name, image, state, health, port, or URL
↑/↓ or j/k     Select
l              Toggle inline logs
f              Follow or pause logs
Page Up/Down   Scroll logs
s              Stop
R              Restart
x              Remove with confirmation
o              Open in browser
c              Copy URL
r              Refresh
q              Quit