# CLI commands

> Reference for every falak CLI command — login, servers, sites, deploy, rollback, releases, env, logs, ssh and more — with flags, output and exit codes.

Source: https://falak.sh/docs/cli/commands/

```text title="falak help"
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`

```text
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](/docs/cli/install-and-login/).

## `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).

```text
ID                          NAME  SLUG  ROLE
01k8…                       Acme  acme  owner
```

## `falak servers list`

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

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

```text
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`:

```text
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:

```text
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:

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

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

```text
falak releases <site>
```

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

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

```text
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:

```text
Pushed 14 variables to shop (redeploy to apply)
```

## `falak logs`

```text
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>  [server/source] message`. With `--json`, one JSON object per line (NDJSON).

## `falak ssh`

```text
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`.

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

The public API does not return a server's SSH user yet. Pass `--user` if you do not use `falak`. A server without a private network has no private address, so `--private` fails for it.

## `falak open`

```text
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.