# Install and log in

> Install the falak CLI on macOS or Linux with one command, create an API token, log in to your control plane, and manage stored credentials.

Source: https://falak.sh/docs/cli/install-and-login/

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

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

```text title="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](https://github.com/OthmanHaba/falak/releases),
- 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:

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

`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](/docs/getting-started/quickstart/) 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` |

  
    ```bash
    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
    ```
  
  
    ```bash
    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](/docs/api/overview/#authentication).

## Log in

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

```text title="Expected output"
Logged in to https://falak.example.com as you@example.com (organization Acme)
```

Non-interactive variants:

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

```bash
falak whoami
```

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