CLI commands

usage: falak [--json] [--url URL] [--token TOKEN] <command> [args]

Global flags and environment

Flag	Env	Meaning
`--json`		Print JSON instead of tables
`--url URL`	`FALAK_URL`	Control plane URL
`--token TOKEN`	`FALAK_TOKEN`	API token
`--version`		Print the version
	`FALAK_CONFIG_DIR`	Where credentials are stored

Global flags can go before the command or among its arguments (falak deploy shop --wait --json).

Exit codes

Code	Meaning
`0`	Success
`1`	Error (API error, network, not found)
`2`	Usage error (bad flags or arguments)
`3`	The deployment or rollback failed (with `--wait`)

Addressing resources

Sites: by id or slug (shop).
Servers: by id or by name (case-insensitive; must be unique, otherwise use the id).

`falak login`

falak login [--url URL] [--token TOKEN | --token-stdin]

Stores a token for a control plane after verifying it. Prompts for missing values when run interactively. The URL must start with https:// (or http://). See Install and log in.

`falak logout`

Forgets the stored token.

`falak whoami`

Shows the user, organization, role, token name and abilities.

`falak orgs`

Lists organizations (a token only sees its own).

ID                          NAME  SLUG  ROLE
01k8…                       Acme  acme  owner

`falak servers list`

ID     NAME   TYPE  STATUS  AGENT   IPV4          PROVIDER  PHP
01k8…  app-1  app   active  online  203.0.113.20  custom    8.4

falak servers alone is falak servers list.

`falak servers show <server>`

Shows id, name, type, status and message, provider, region, IPv4, PHP, agent status and last heartbeat, load, memory and disk usage, and creation time.

`falak sites list`

ID     SLUG  DOMAIN            RUNTIME     STATUS  BRANCH
01k8…  shop  shop.example.com  frankenphp  ready   main

`falak sites show <site>`

Shows id, slug, name, domain, aliases, URL, runtime, build mode, strategy, status, repository, branch, server ids, the current release (id and commit) and creation time.

`falak deploy`

falak deploy <site> [--branch BRANCH] [--wait]

Flag	Meaning
`--branch`	Deploy this branch (default: the site’s branch). The head commit is resolved by the git provider.
`--wait`	Stream the output and wait until the deployment finishes; exit `3` if it fails

Without --wait:

Deployment 01k8… building for shop
https://falak.example.com/sites/01k8…/deployments/01k8…

If the site’s servers are still being prepared, the deployment is waiting and the CLI prints the reason:

Deployment 01k8… waiting for shop
Waiting for 2 servers to finish preparing: web-1, web-2; it starts automatically once they are ready

With --wait, each output line is prefixed with the server and phase:

Deployment 01k8… started for shop
[build] composer install --no-dev …
[web-1 fetch] Fetched artifact into releases/01K8…
[web-1 migrate] Migrating: 2026_09_20_120000_add_wishlists_table
Deployment 01k8… succeeded

With --json --wait, output lines go to stderr and the final deployment JSON to stdout. Transient API errors are retried (up to 5 in a row). Output is polled every 2 seconds.

`falak rollback`

falak rollback <site> [--release ID] [--wait]

Rolls back to --release or, by default, the newest retained release before the current one. --wait behaves as for deploy.

`falak releases`

falak releases <site>

    ID       COMMIT   BRANCH  CREATED
*   01k8…    a1b2c3d  main    2026-09-28T10:00:00+00:00
    01k7…    9f8e7d6  main    2026-09-27T16:12:00+00:00

* marks the active release.

`falak env pull`

falak env pull <site> [--file PATH]

Prints the latest environment as dotenv, or writes it to --file with mode 0600 (and reports the number of variables on stderr). Needs sites.env.view; recorded in the audit log.

`falak env push`

falak env push <site> [--file PATH]

Replaces all variables with the dotenv from --file or stdin. Refuses an empty file. Changes apply on the next deployment:

Pushed 14 variables to shop (redeploy to apply)

`falak logs`

falak logs <site> [--follow|-f] [--since 1h] [--limit N] [--level LEVEL]

Flag	Default	Meaning
`--since`	`1h`	How far back to start (Go duration: `30m`, `6h`, `48h`)
`--limit`	`200`	Lines per request
`--level`		Minimum level: `debug`, `info`, `warn`, `error` (as accepted by the API: `trace`, `debug`, `info`, `warn`, `error`, `fatal`)
`--follow`, `-f`	off	Keep polling every 2 seconds

Lines print as <time> <LEVEL> [server/source] message. With --json, one JSON object per line (NDJSON).

`falak ssh`

falak ssh <server> [--user USER] [--private] [-- ssh args]

Runs ssh <user>@<ipv4> for the server (by id or name), with -p <port> when the server’s SSH port is not 22. --private connects to the server’s private IPv4 instead, e.g. from a machine on the same private network. The user defaults to falak. Everything after -- is passed to ssh.

falak ssh app-1
falak ssh db-1 -- -N -L 5432:127.0.0.1:5432

`falak open`

falak open <site> [--panel]

Prints and opens the site’s URL in your browser, or with --panel the site’s page in the control panel.

`falak version`

Prints the CLI version.