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

homarr --pr 6441 --env WORKSHOP_WEB_URL=https://app-v2.preview.homarr.dev/
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 installed binary accepts --pr, --demo, --detach, and repeatable --env KEY=VALUE flags directly, so homarr --pr <number> --env KEY=VALUE is shorthand for homarr run --pr <number> --env KEY=VALUE. 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                     Interactive local and remote image browser
homarr --pr <number>       Pull and launch a PR image, with optional --env overrides
homarr dev                 Explicit alias for the main browser
homarr dash                Start on the instance dashboard
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 images              List local images with build provenance
homarr data                List instance data volumes
homarr data rm <volume>    Preview permanent data deletion; add --force to confirm
homarr prune               Remove stopped instances
homarr list                Script-friendly instance list
homarr logs <container>    Follow logs
homarr shell <container>   Open an interactive shell in a running instance
homarr ci [pr] [--watch]   View or watch GitHub CI checks for a pull request
homarr open <container>    Open in browser
homarr stop <container>    Stop
homarr restart <container> Restart
homarr remove <container>  Force-remove
homarr doctor              Check Docker, Engine API, and optional integrations

Development Browser

/              Filter by PR number, title, author, branch, CI, image, state, or port
↑/↓ or j/k     Select row
Enter or Space Start the available image; choose local or remote when both exist; stop when running
R              Build locally in background (or rebuild local image)
p              Pull remote PR image in background and start container
m              Manage mode (chords: b rebuild, i delete image, d delete data, c remove container, p prune)
t              Background tasks overlay (status, progress, cancellation)
Tab            Cycle sidebar tab (logs / build / ci)
l              Toggle sidebar visibility
L              Pin logs to currently selected container
f              Follow or pause logs
Page Up/Down   Scroll logs
M              Toggle demo mode for next launch
b              Toggle bot PRs
o              Open PR on GitHub
a              Open running instance in browser
c              Copy instance URL to clipboard
r              Refresh data
1 / 2 / d      Switch screen (development / instances)
?              Help overlay
q              Quit (cancels background tasks)

Pull progress with live layer bytes, throughput, BuildKit step streaming, local build provenance, CI rollup badges, container health status, and live output streams are non-blocking. When a background pull completes, the sidebar automatically transitions to streaming the running instance's live logs.

Instance Dashboard

/              Filter by name, image, state, health, port, or URL
↑/↓ or j/k     Select row
Enter or Space Start / stop selected instance
s              Stop instance
S              Restart instance
x              Remove container (keeps data)
m              Manage mode for selected instance
t              Background tasks overlay
Tab            Cycle sidebar tab (logs / build / ci)
l              Toggle sidebar visibility
L              Pin logs
f              Follow / pause logs
Page Up/Down   Scroll logs
o              Open running instance in browser
c              Copy URL to clipboard
R              Rebuild from recorded provenance
r              Refresh
1 / 2 / d      Switch screen
?              Help overlay
q              Quit

5.7 KiB Raw Permalink Blame History