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.

Install

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

curl -fsSL https://falak.sh/install-cli.sh | sh

Expected output

==> Downloading falak-darwin-arm64 (latest) from OthmanHaba/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:

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.

Note

falak is the client CLI for your laptop and CI. falak-ctl is a different tool: it runs on the control-plane host, where the installer puts it, and manages the Docker stack (updates, backups, doctor).

Manual install

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

macOS (Apple silicon)

curl -fsSL -o falak https://github.com/OthmanHaba/falak/releases/latest/download/falak-darwin-arm64
chmod +x falak && sudo mv falak /usr/local/bin/falak
falak version

Linux (amd64)

curl -fsSL -o falak https://github.com/OthmanHaba/falak/releases/latest/download/falak-linux-amd64
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.

Create a token

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.

Log in

falak login --url https://falak.example.com
# API token: (paste; input is hidden)

Expected output

Logged in to https://falak.example.com as you@example.com (organization Acme)

Non-interactive variants:

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:

falak whoami

User:          Ada <ada@example.com>
Organization:  Acme
Role:          owner
Token:         laptop
Abilities:     *

Where credentials live

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

Precedence

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

Next steps

CommandsEvery command, flag and output.

Use in CIDeploy from GitHub Actions and friends.