# falak-ctl reference

> Every falak-ctl command for operating a Falak installation — status, logs, doctor, update, prune-images, registry, backup, restore, domain, admin and more.

Source: https://falak.sh/docs/operations/falak-ctl/

`falak-ctl` is installed to `/usr/local/bin/falak-ctl` by the installer. Run it as root on the control plane host.

```text title="falak-ctl help"
falak-ctl status                         containers, health, version, URLs, PHP thread usage
falak-ctl logs [service] [-f]            recent logs (all services, or one)
falak-ctl up | down | restart [svc]      start / stop / restart the stack
falak-ctl update [--version vX.Y.Z]      backup -> pull -> migrate -> restart -> health check,
                                        automatic rollback (previous version + DB restore) on failure,
                                        then removes Falak images older than the previous version
falak-ctl prune-images [--dry-run]       remove Falak images except the current and previous version
falak-ctl registry status                built-in image registry: address, size, answers with its credentials
falak-ctl registry prune [--dry-run]     delete registry images no build or release needs (also daily)
falak-ctl registry gc [--dry-run] [--force]  delete layers no image references (stops the registry briefly; weekly from cron)
falak-ctl backup [--label NAME]          Postgres dump + app storage + Fleet CA + .env -> backups/
falak-ctl restore <file> [--yes]         restore a backup (stops the app while restoring)
falak-ctl doctor                         DNS, certificates, ports, disk, containers, agent API, PHP threads
falak-ctl domain set <domain> [--keep-old]   move the panel to a new domain
falak-ctl admin reset-password <email> [--password=...]
falak-ctl admin create <email>
falak-ctl artisan <args...>              run php artisan in the control-plane container
falak-ctl compose <args...>              raw docker compose with the install's settings
falak-ctl reload-configs                 recreate services whose mounted config files changed on disk
falak-ctl version
```

## Environment

| Variable | Default | Meaning |
|---|---|---|
| `FALAK_DIR` | `/opt/falak` | Install directory |
| `FALAK_PROJECT` | `falak` | Compose project name |
| `FALAK_LOG_TAIL` | `200` | Lines shown by `logs` |

Settings are read from `$FALAK_DIR/.env`.

## `status`

Version, install directory, each service's status and image, the panel/agent API/Grafana URLs, PHP thread usage and the last backup:

```text
==> Falak v0.2.6 at /opt/falak (project falak)
SERVICE         STATUS                   IMAGE
control-plane   Up 2 hours (healthy)     ghcr.io/othmanhaba/falak-control-plane:v0.2.6
…
  panel:      https://falak.example.com
  agent API:  https://agents.falak.example.com/agent/v1
  PHP threads: panel 1/8 busy · agent-api 5/128 busy
  last backup: /opt/falak/backups/falak-backup-20260928T031500Z.tar.gz
```

## `logs [service] [-f]`

`docker compose logs --tail=200` for all services or one (`control-plane`, `agent-api`, `horizon`, `reverb`, `scheduler`, `postgres`, `valkey`, `edge`, `builder`, and the observability services). `-f`/`--follow` streams.

## `doctor`

Checks, in order: **DNS** (public IPs and every Falak hostname, including `registry.`), **Ports**, **Containers**, **Certificates** (warns when one expires within 14 days), **Agent API** (must answer `401` without a client certificate), **Image registry** (`401` without credentials, `200` with them), **PHP threads** (flags a pool at 80 % or saturated, and the 0.2.x `FRANKENPHP_CONFIG` hotfix line), **Disk & memory**, and **Backups**.

## `up`, `down`, `restart [service]`

- `up [timeout]`: start/converge the stack, wait until healthy (default 420 s), recreate services whose mounted config files changed, then health-check.
- `down`: stop the stack (volumes are kept).
- `restart [service]`: restart all services or one.

## `update [--version vX.Y.Z]`

Updates to the latest release or a given tag, with an automatic backup and rollback. Alias: `upgrade`. `--skip-backup` skips the pre-update backup (then there is nothing to roll back to). After a successful update it records the version it came from as `FALAK_PREVIOUS_VERSION` in `.env` and removes older Falak images (see `prune-images`). See [Upgrade](/docs/operations/upgrade/).

## `prune-images [--dry-run]`

Removes every tag of the `falak-control-plane`, `falak-edge` and `falak-builder` images except the current version (`FALAK_VERSION`) and the previous one (`FALAK_PREVIOUS_VERSION`, the rollback target). `--dry-run` lists what it would remove.

- Third-party images (Postgres, Valkey, Grafana, …), images still used by a container and volumes are never touched.
- `update` runs this automatically. Set `FALAK_PRUNE_IMAGES=0` in `.env` to keep every image.
- With `FALAK_PULL=0` (images built locally, e.g. `--build-from-source`), `update` never prunes, because removed images could not be pulled again. `prune-images` still works there and warns first.

```text
$ sudo falak-ctl prune-images --dry-run
  would remove ghcr.io/othmanhaba/falak-control-plane:v0.4.2
  …
```

## `registry status | prune | gc`

Operates the [built-in image registry](/docs/operations/install/#the-built-in-image-registry) that Docker builds push to.

- `registry status`: the registry's address, whether it runs, how much it stores, and whether it answers with its credentials. On an install from before the registry it also adds the missing `FALAK_REGISTRY_*` settings.
- `registry prune [--dry-run]`: deletes the images of builds whose artifact was pruned, never one a pending, live or rollback release needs. The control plane runs it daily at 03:45 (`falak:registry-prune`).
- `registry gc [--dry-run] [--force]`: garbage-collects layers and untagged manifests nothing references, which frees the disk space. The registry is **stopped** while it runs. It is skipped while an image build is queued or running (or when the control plane can't tell); `--force` runs it anyway.

`falak-ctl up` and `update` write a weekly cron entry, `/etc/cron.d/falak-registry-gc` (Sunday 04:17, log in `/var/log/falak-registry-gc.log`). Set `FALAK_REGISTRY_GC=0` in `.env` to remove it.

```text
$ sudo falak-ctl registry status
  address: https://registry.falak.example.com  (user falak; password: FALAK_REGISTRY_PASSWORD in /opt/falak/.env)
  ✓ registry running, 1.2G stored
  ✓ https://registry.falak.example.com/v2/ answers with the credentials (200)
```

## `backup [--label NAME] [--quiet]`

Writes `/opt/falak/backups/falak-backup-[-label].tar.gz` (or `.tar.gz.enc` with a passphrase). See [Backup and restore](/docs/operations/backup-restore/).

## `restore <file> [--yes] [--keep-env]`

Restores a backup (a path, or a file name inside `backups/`). Asks for confirmation unless `--yes`; non-interactive runs require `--yes`. `--keep-env` keeps the current `.env` instead of the backup's.

A restore **replaces** the database, app storage, Fleet CA and `.env`.

## `domain set <new-domain> [--keep-old]`

Moves the panel to a new domain. See [Change the domain](/docs/operations/change-domain/).

## `admin reset-password <email> [--password=…]`

Sets a new password (generated and printed when `--password` is omitted).

## `admin create <email> [--organization=…] [--token=NAME] [--name=…] [--password=…] [--json]`

Creates a user with an organization; `--token` also issues a full-access API token and prints it. Runs `php artisan falak:admin`.

## `artisan <args…>`

`php artisan` in the `control-plane` container. Useful commands:

| Command | Purpose |
|---|---|
| `falak:agents [--outdated] [--count]` | Shipped agent build and outdated agents |
| `falak:admin <email> …` | Create or reset admins |
| `telemetry:grafana:provision [--organization=…]` | Re-provision Grafana |
| `templates:render <slug> [--domain=…] [--env-file=…]` | Render a catalog template |
| `projects:backfill [--organization=…]` | Place orphan sites/databases into Default projects |

## `compose <args…>`

Raw `docker compose` with the install's project, env file and profiles, for example `falak-ctl compose ps -a`.

## `reload-configs`

Recreates services whose **mounted config files** changed on disk (`loki.yaml`, `tempo.yaml`, the gateway `Caddyfile`, Grafana provisioning and dashboards). It compares what each running container sees at its Falak mounts with the files on disk:

```text
==> mounted config files changed: recreating loki
  ✓ recreated loki
```

The same check runs on `up`, after a restore, during updates and rollbacks. Run it after editing files under `/opt/falak/observability/` by hand (such edits are replaced by the next update).

## `version`

Prints `FALAK_VERSION`.