CLI commands
usage: falak [--json] [--url URL] [--token TOKEN] <command> [args]Global flags and environment
Section titled “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
Section titled “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) |
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 |
Addressing resources
Section titled “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
Section titled “falak login”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.
falak logout
Section titled “falak logout”Forgets the stored token. A token from a browser login is also revoked on the server; a token you pasted in is kept.
falak whoami
Section titled “falak whoami”Shows the user, organization, role, token name and abilities.
falak orgs
Section titled “falak orgs”Lists organizations (a token only sees its own).
ID NAME SLUG ROLE01k8… Acme acme ownerfalak servers list
Section titled “falak servers list”ID NAME TYPE STATUS AGENT IPV4 PROVIDER PHP01k8… app-1 app active online 203.0.113.20 custom 8.4falak servers alone is falak servers list.
falak servers show <server>
Section titled “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 servers stack
Section titled “falak servers stack”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 |
falak servers stack builder-1 --php 8.4 # Composer builds on a builderfalak servers stack app-2 --php 8.4 --node 22falak sites list
Section titled “falak sites list”ID SLUG DOMAIN RUNTIME STATUS BRANCH01k8… shop shop.example.com frankenphp ready mainfalak sites show <site>
Section titled “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
Section titled “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 shophttps://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 shopWaiting for 2 servers to finish preparing: web-1, web-2; it starts automatically once they are readyWith --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_tableDeployment 01k8… succeededWith --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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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: 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
Section titled “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-1falak ssh db-1 -- -N -L 5432:127.0.0.1:5432For a shell without SSH (in a site, a container, a database or on a server), use falak console.
falak console
Section titled “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
Section titled “falak net”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).--timeoutsets 1–60 seconds (default 30). - Capture (Packet capture,
network.capture):--yesconfirms that captures may contain sensitive data.--durationis 1–60 s (default 30),--max-size1–100 MiB (default 20),--fullcaptures whole packets instead of packet headers. It waits until the capture is ready and downloads it to-o(defaultfalak-capture-<id>.pcap, never overwritten). Ctrl-C cancels.
falak open
Section titled “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 db list
Section titled “falak db list”ID NAME ENGINE STATUS SERVER MEMORY_MB DATABASES01k8… db postgresql 17 running db-1 1024 2Lists the organization’s database containers.
falak db delete
Section titled “falak db delete”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
Section titled “falak secret”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.
setreads 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 FILEimports everyKEY=VALUEline of a.envfile (comments, blank lines and empty values skipped;exportand one pair of quotes allowed).listshows names, kinds and versions, never values.deleteasks on a terminal; elsewhere it needs--yes.
falak secret set STRIPE_SECRET -p shopop read op://vault/stripe/key | falak secret set STRIPE_SECRET -p shop -e stagingfalak secret set --from-env .env.production -p shopA token created with a list of abilities needs secrets.manage (and secrets.view for list).
Config as code
Section titled “Config as code”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
Section titled “falak init”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
Section titled “falak validate”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
Section titled “falak plan”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
Section titled “falak apply”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
Section titled “falak runs”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 / falak reject
Section titled “falak approve / falak reject”falak approve <run> [--comment TEXT] [--yes]falak reject <run> [--comment TEXT] [--yes]Decides a run waiting for an approval. Needs config.approve.
falak drift
Section titled “falak drift”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
Section titled “falak config export”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
Section titled “falak config unmanaged”falak config unmanaged [-e ENV] [-p PROJECT]Lists what runs detached (kept, no longer managed by the file).
falak config source show / set
Section titled “falak config source show / set”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.
falak config source set --repo acme/shop --connection <id> --enablefalak config source set --allow-server app-1falak skill install
Section titled “falak skill install”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
Section titled “falak update”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.
falak version
Section titled “falak version”Prints the CLI version.