Skip to content

Install and log in

falak is a single static binary that talks to your control plane’s REST API. Use it to deploy, roll back, manage environment files, tail logs and SSH into servers.

Run this on your own machine (macOS or Linux, amd64 or arm64):

Terminal window
curl -fsSL https://falak.sh/install-cli.sh | sh
Expected output
==> Downloading falak-darwin-arm64 (latest) from falak-sh/falak
✓ checksum verified
✓ installed v0.2.6 to /usr/local/bin/falak

The script:

  • picks the binary for your OS and CPU from the latest Falak release,
  • checks it against the release’s SHA256SUMS and stops on a mismatch,
  • installs it to /usr/local/bin when that is writable, otherwise to ~/.local/bin, and tells you if that directory is not on your PATH.

To install and log in in one step, pass your panel URL. The script then asks for the token:

Terminal window
curl -fsSL https://falak.sh/install-cli.sh | FALAK_URL=https://falak.example.com sh
Variable Effect
FALAK_VERSION Install a specific tag, for example v0.2.6. Default: the latest release. Use the version that matches your control plane.
FALAK_INSTALL_DIR Install somewhere else, for example ~/bin.
FALAK_URL Run falak login --url $FALAK_URL after installing.

Run the same command again to upgrade.

Binaries are attached to every release as falak-<os>-<arch>:

OS amd64 arm64
macOS falak-darwin-amd64 falak-darwin-arm64
Linux falak-linux-amd64 falak-linux-arm64
Terminal window
curl -fsSL -o falak https://github.com/falak-sh/falak/releases/latest/download/falak-darwin-arm64
chmod +x falak && sudo mv falak /usr/local/bin/falak
falak version

Verify manual downloads against the release’s SHA256SUMS. On macOS, a binary downloaded with a browser may be quarantined. Run xattr -d com.apple.quarantine /usr/local/bin/falak if macOS refuses to open it.

Already installed? falak update updates the CLI in place (from v0.11.1; older versions re-run the install line).

Since v0.12.0, falak login on a terminal signs you in through the panel. No token to copy:

Terminal window
falak login --url https://falak.example.com
Expected output
Your code: WDJB-MJHT
Opened https://falak.example.com/cli/authorize/WDJB-MJHT
Approve the request there if it shows the same code.
Waiting for the approval…
Logged in to https://falak.example.com as [email protected] (organization Acme)
  1. The browser opens the approval page. Sign in as usual if you aren’t already.
  2. Confirm your password (and your 2FA code when two-factor authentication is on). It’s the same check as creating a token by hand.
  3. Check that the page shows the same code as your terminal, and the machine and address you expect. Pick the organization if you belong to several.
  4. Click Approve. The terminal finishes on its own.

Over SSH or in a container, add --no-browser: the CLI prints the link, and you open it on any device. The request expires after 10 minutes.

The CLI gets its own token, named CLI — your-host, with your role’s permissions in the organization you picked. It expires after 90 days without use, and a year after the login at most. It’s listed under Settings → API tokens, where you can revoke it. falak logout revokes it on the server too.

For scripts and CI, or to choose the abilities yourself, create a token in the panel.

  1. In the panel, open Settings → API tokens.
  2. Name the token (for example laptop or ci-deploys), optionally set an expiry in days (1–3650; empty = never), and choose abilities — All abilities or specific permissions.
  3. Copy the token. It is shown once.

A token is pinned to the organization you are in and never exceeds your role. See API authentication.

Terminal window
falak login --url https://falak.example.com --token "$FALAK_TOKEN"
echo "$FALAK_TOKEN" | falak login --url https://falak.example.com --token-stdin

The token is verified (GET /api/v1/me) before it is saved. Check who you are:

Terminal window
falak whoami
User: Ada <[email protected]>
Organization: Acme
Role: owner
Token: laptop
Abilities: *
File <config dir>/falak/credentials.json, mode 0600 (directory 0700)
macOS config dir ~/Library/Application Support
Linux config dir $XDG_CONFIG_HOME or ~/.config
Override FALAK_CONFIG_DIR (the file is then $FALAK_CONFIG_DIR/credentials.json)

falak logout deletes the file and, for a browser login, revokes the token on the server (a token you pasted in is kept: it may be used elsewhere). To cut off a lost laptop, revoke its token under Settings → API tokens. The CLI stops working at once.

The CLI stores one control plane at a time. For a second one, give it its own directory: FALAK_CONFIG_DIR=~/.falak-staging falak login --url https://staging.example.com.

For the URL and token, the first one set wins:

  1. --url / --token flags
  2. FALAK_URL / FALAK_TOKEN environment variables
  3. The stored credentials