# 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

```sh
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

```sh
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

```sh
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

```text
homarr                     Interactive local and remote image browser
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 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

```text
/              Filter by PR number, title, author, branch, CI, image, state, or port
↑/↓ or j/k     Select
Enter or Space Start the matching local build, otherwise pull remote; stop when running
R              Build a remote PR locally in the background 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
d              Switch to the instance dashboard
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.
Local PR images are folded into their remote PR row only when the recorded revision exactly matches the current GitHub head SHA. They are marked `◆ local` and preferred by Enter; outdated builds remain separate local rows. Navigation and the `d` dashboard toggle remain available while a local build runs.

## Instance Dashboard

```text
/              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
d              Switch to the development browser
q              Quit
```