Skip to content

CLI commands

falak help
usage: falak [--json] [--url URL] [--token TOKEN] <command> [args]
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).

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)
4 falak fn deploy: a newer function version exists (use --force)
5 Config as code: the file is invalid
6 Config as code: the run waits for an approval
7 falak drift: the environment drifted
  • Sites: by id or slug (shop).
  • Servers: by id or by name (case-insensitive; must be unique, otherwise use the id).

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

On a terminal without a token, signs in through the browser (v0.12.0): it shows a code, opens the panel’s approval page and waits for your approval; --no-browser prints the link instead. With --token, --token-stdin, FALAK_TOKEN, or a token piped in without a terminal, it stores that token after verifying it. Prompts for the URL when run interactively; it must start with https:// (or http://). See Install and log in.

Forgets the stored token. A token from a browser login is also revoked on the server; a token you pasted in is kept.

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

Lists organizations (a token only sees its own).

ID NAME SLUG ROLE
01k8… Acme acme owner
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.

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 servers stack <server> [--php VERSION] [--php-runtime fpm|frankenphp|cli] [--node VERSION]

Adds PHP and/or Node.js to a server created without them, then re-provisions it (the machine check runs first). Add-only: a runtime the server already has stays as it is.

Flag Meaning
--php Add PHP, e.g. 8.4
--php-runtime fpm or frankenphp on site servers, cli on builders (default: cli on builders, else fpm)
--node Add Node.js: the major version, e.g. 22
Terminal window
falak servers stack builder-1 --php 8.4 # Composer builds on a builder
falak servers stack app-2 --php 8.4 --node 22
ID SLUG DOMAIN RUNTIME STATUS BRANCH
01k8… shop shop.example.com frankenphp ready main

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 <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 <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 <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 <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 <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 <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: trace, debug, info, warn, error, fatal (warning is accepted as warn)
--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 <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.

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

For a shell without SSH (in a site, a container, a database or on a server), use falak console.

falak console <site> [--server NAME|ID] [--service NAME]
falak console --db <instance>
falak console --host <server> [--user NAME]

Opens a console through the terminal relay: a site’s container, a compose service, a native site’s current release as the site user, a database container, or a server shell (root unless --user). No SSH key or port 22 needed; needs terminal.open.

Flag Meaning
--server Site: the server to open it on (default: the site’s leader)
--service Compose site: the service (required when the stack has several)
--db A database container’s shell (instance name or id)
--host A shell on a server (name or id)
--user With --host: the unix user (default root)

Your terminal goes into raw mode; window resizes are forwarded and Ctrl-C goes to the remote shell. The command exits with the remote shell’s exit code. A dropped connection reconnects silently, up to 5 times in a row.

falak net ping <host> [--count N]
falak net traceroute <host> [--max-hops N]
falak net dns <name> [--type A|AAAA|CNAME|MX|TXT|NS|SRV|PTR] [--nameserver IP]
falak net http <url> [--method GET|HEAD] [--connect-to IP] [--insecure]
falak net tcp <host> <port> [--count N]
falak net capture --yes [--interface default|wireguard|docker] [--duration S] [--max-size MiB] [--full]
[--host IP|CIDR] [--port N] [--protocol tcp|udp|icmp] [--direction in|out|both] [-o FILE]

Every falak net command runs on exactly one target: --server NAME|ID (its host network), --site SITE (its container, or the host for native sites; --on SERVER picks a server, --service NAME a compose service) or --db INSTANCE (a database container).

  • Tools (Network tools, network.tools): output prints as it arrives; the exit code is the tool’s (124 on a timeout). --timeout sets 1–60 seconds (default 30).
  • Capture (Packet capture, network.capture): --yes confirms that captures may contain sensitive data. --duration is 1–60 s (default 30), --max-size 1–100 MiB (default 20), --full captures whole packets instead of packet headers. It waits until the capture is ready and downloads it to -o (default falak-capture-<id>.pcap, never overwritten). Ctrl-C cancels.
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.

ID NAME ENGINE STATUS SERVER MEMORY_MB DATABASES
01k8… db postgresql 17 running db-1 1024 2

Lists the organization’s database containers.

falak db delete <instance> --confirm NAME [--delete-volume]

Deletes a database container, by id or (unique) name. --confirm is required and must be the instance’s name. The data volume is kept unless --delete-volume is given.

falak secret set <NAME> [-p PROJECT] [-e ENV]
falak secret set --from-env FILE [-p PROJECT] [-e ENV]
falak secret list [-p PROJECT] [-e ENV]
falak secret delete <NAME> [-p PROJECT] [-e ENV] [--yes]

Manages the secrets that ${{ secrets.NAME }} references resolve to (CLI v0.11.1). Without -e they are project secrets; with -e they belong to one environment, which wins over the project’s. The project comes from -p, then FALAK_PROJECT, then .falak/project.json.

  • set reads the value from a hidden prompt on a terminal, or from stdin (one trailing newline dropped). It never takes the value as an argument, so it stays out of your shell history. Setting a secret that exists adds a version.
  • --from-env FILE imports every KEY=VALUE line of a .env file (comments, blank lines and empty values skipped; export and one pair of quotes allowed).
  • list shows names, kinds and versions, never values.
  • delete asks on a terminal; elsewhere it needs --yes.
Terminal window
falak secret set STRIPE_SECRET -p shop
op read op://vault/stripe/key | falak secret set STRIPE_SECRET -p shop -e staging
falak secret set --from-env .env.production -p shop

A token created with a list of abilities needs secrets.manage (and secrets.view for list).

These commands work with a project’s falak.yaml and need CLI v0.11.0. The project comes from -p (id or name), then FALAK_PROJECT, then .falak/project.json (written by falak init when you pick a project). The environment comes from -e, else the one whose branch is the current git branch. The file defaults to falak.yaml, then falak.yml, then falak.json. Issues print as falak.yaml:12:17: schema: /units/web/deploy/strategy: value must be one of ….

falak init [dir] [--yes] [--stdout] [--json] [--full] [--force] [--dockerfile] [--update [--write]] [-p PROJECT]

Writes a falak.yaml from the code, each value with the reason it was chosen.

Flag Meaning
--yes Accept every default; ask nothing
--stdout Print the file instead of writing it
--json Print the detection report
--full Also write default values
--force Replace an existing falak.yaml
--dockerfile Write a starter Dockerfile for a language Falak doesn’t build natively (Go, Python, Ruby, Rust, Java)
--update Detect again and show what the code adds to the existing file (a diff); --write writes the additions
falak validate [file] [-e ENV] [--format yaml|json] [--offline]

Checks the file offline: schema, environments, references. Logged in with a linked project it also runs the organization checks (servers, secrets, storage, names), unless --offline. Exits 5 if the file is invalid.

falak plan [file] [-e ENV] [-p PROJECT]

Shows what applying the local file would change: + create, ~ update, - delete or detach, ! risky (with the reason).

falak apply [file] [-e ENV] [-p PROJECT] [--allow-destroy] [--wait] [--approve [--yes]]

Applies the local file now and deploys what changed.

Flag Meaning
--wait Stream the deployments until the run finishes
--timeout With --wait: give up after this long (default 30m; the run goes on)
--approve Approve the run’s risky changes (with --yes to skip the prompt, --comment to record a comment)
--allow-destroy Delete what the file removed and created, data included (needs config.destroy)

Exits 6 if the run waits for an approval, 3 if a unit’s deployment failed.

falak runs list [-p PROJECT] [-e ENV] [--limit N]
falak runs show <run>

list shows a project’s config runs, newest first (default limit 20). show shows one run’s plan, approval and deployments.

falak approve <run> [--comment TEXT] [--yes]
falak reject <run> [--comment TEXT] [--yes]

Decides a run waiting for an approval. Needs config.approve.

falak drift [-e ENV] [-p PROJECT] [--check]

Compares the environment with its last applied file and lists the changes a run would make to put the file back. --check checks now instead of reading the last scheduled check. Exits 7 if the environment drifted, 0 if in sync or unknown.

falak config export [project] [-e ENV] [-o FILE] [--format yaml|json]

Writes a project’s current state as a falak.yaml. Pushing it as is changes nothing.

falak config unmanaged [-e ENV] [-p PROJECT]

Lists what runs detached (kept, no longer managed by the file).

falak config source show [-p PROJECT]
falak config source set [-p PROJECT] [--repo OWNER/NAME] [--connection ID] [--path FILE] [--enable|--disable] [--allow-server NAME]…

Shows or changes the repository file a project follows. set changes only what its flags name; a new source is enabled. --allow-server lists a server the file may place units on: repeatable, it replaces the list, "" clears it, admins only.

Terminal window
falak config source set --repo acme/shop --connection <id> --enable
falak config source set --allow-server app-1
falak skill install [--user | --project | --dir DIR] [--force]

Writes the Falak skill for AI agents (SKILL.md and its references) from the copy the CLI ships with.

Flag Meaning
--user ~/.claude/skills/falak (the default)
--project .claude/skills/falak in the working directory
--dir Any other directory, such as another agent’s skills folder
--force Replace files that already exist (otherwise it refuses)

With --json it prints the directory and the files written.

falak update [--version vX.Y.Z] [--check]

Replaces the running falak binary with the latest release’s (CLI v0.11.1), checked against the release’s SHA256SUMS like the install script. --check only reports whether a newer release exists; --version installs a given release. The new binary is written next to the old one and renamed over it; if that directory isn’t writable, re-run with sudo.

Prints the CLI version.