CLI overview
Install the alaf server CLI, log in with a token, understand connection contexts, and find every command at a glance.
The alaf server CLI does everything the dashboard does, from your terminal — run the platform, deploy a
project, tail logs, manage domains, and script it all in CI. It's the same binary you use to install and
run Alaf Server itself.
Install it first
This page assumes the alaf server command is already on your PATH. If not, see
Installation — the short version is npm i -g alaf server (or
curl -fsSL https://get.alafteknoloji.com | sh).
Every command supports --help, so when in doubt:
alaf server --help # top-level commands
alaf server deploy --help # flags for one command
alaf server domain add --help # flags for a subcommandLog in with a token
The CLI authenticates with a Personal Access Token (PAT) — a string that starts with opsh_pat_.
You create one in the dashboard, then hand it to alaf server login.
Get a token
In the dashboard, open Settings → Personal Access Tokens and create one. Copy it — the secret is shown
only once. (You can also mint tokens from the CLI with alaf server token create.)
Log in
Running alaf server login with no arguments opens that settings page and waits for you to paste the token.
For scripts and CI, pass it directly:
# Interactive — opens Settings and prompts for a paste
alaf server login
# Non-interactive — pass the token (great for CI)
alaf server login --token opsh_pat_xxxxxxxxxxxx
# Point at a remote instance instead of localhost
alaf server login --token opsh_pat_xxxxxxxxxxxx \
--api-url https://your-host --dashboard-url https://your-hostThe token is validated against the API and saved to ~/.alaf server/config.json.
alaf server login flag | Purpose | Default |
|---|---|---|
--token <token> | PAT (opsh_pat_…) for non-interactive login. | prompt |
--api-url <url> | API base URL to authenticate against. | http://localhost:4000 |
--dashboard-url <url> | Dashboard base URL (opened for the paste flow). | http://localhost:3001 |
--context <name> | Name of the context to store this login under. | default |
Signing out
alaf server logout removes the stored token from the active context.
Global flags
These work on every command.
| Flag | Purpose |
|---|---|
--json | Machine-readable JSON output on stdout (data only — no spinners or prose). Ideal for piping into jq or consuming from scripts. |
--version | Print the CLI version. |
--help | Show help for the CLI or any command / subcommand. |
# Human-readable
alaf server project list
# Same data as JSON for scripting
alaf server project list --json | jq '.[].name'Connection contexts
A context is a named connection: an API endpoint, a dashboard endpoint, and the token to use with them. They let one machine talk to more than one Alaf Server instance — say a local install and a production server — and switch between them without re-authenticating each time.
Contexts live in ~/.alaf server/config.json. The one marked current is what every authenticated command
uses. alaf server login writes to the default context unless you pass --context <name>.
alaf server context # list contexts; the active one is starred
alaf server context use prod # switch the active context to "prod"Managing contexts
| Command | Purpose |
|---|---|
alaf server context (alias ctx) | Show all contexts; the active row is starred. |
alaf server context list (alias ls) | List configured contexts. |
alaf server context use <name> | Switch the active context. |
alaf server context add <name> | Create or update a context's endpoints/token. |
alaf server context rm <name> (alias remove) | Remove a context (you can't remove the active one). |
Flags for alaf server context add:
| Flag | Purpose |
|---|---|
--api-url <url> | API base URL. |
--dashboard-url <url> | Dashboard base URL. |
--token <token> | Personal access token to store. |
--use | Switch to this context immediately after adding it. |
add vs. login
alaf server context add only writes config — it doesn't check the token. Use alaf server login when you want
the token validated against the API before it's saved.
All commands
Twenty-four commands, grouped the same way the reference pages are. Each heading links to the page that
covers those commands in full; run alaf server <command> --help for the flag list of any one.
Running & updating — reference
Operate Alaf Server itself: the local server, the CLI, and the desktop app.
| Command | Purpose |
|---|---|
alaf server up | Run Alaf Server as a persistent service (starts on boot, auto-restarts). Add --foreground for a one-off attached run. |
alaf server stop | Stop the service started by alaf server up (won't restart or return on reboot). |
alaf server update | Update the CLI and bundled server to the latest release. |
alaf server install | Download and install the Alaf Server desktop app for this OS. |
alaf server install cache | Manage the local download cache (list, verify, clean, path). |
alaf server open | Open the Alaf Server dashboard in your browser. |
alaf server status | Show the active context's API health and deployment info. |
alaf server doctor | Diagnose the CLI setup (config, active context, runtime). |
Access & the raw API — reference
Who you are, which instance you're talking to, and an escape hatch to any route.
| Command | Purpose |
|---|---|
alaf server login | Authenticate with a Personal Access Token. |
alaf server logout | Remove the stored token from the active context. |
alaf server context (alias ctx) | Manage connection contexts — see above. |
alaf server token | Manage personal access tokens (list, create, revoke). |
alaf server api | Make an authenticated request to any Alaf Server API route (like gh api). |
Deploying — reference
| Command | Purpose |
|---|---|
alaf server deploy | Trigger a deployment for the current project. |
alaf server deployment (alias deployments) | Manage deployments — list, inspect, redeploy, rollback. |
alaf server logs | View or stream a deployment's logs. |
Projects, services & domains — reference
| Command | Purpose |
|---|---|
alaf server init | Link the current directory to a project (writes .alaf server/project.json). |
alaf server project (alias projects) | Manage Alaf Server projects. |
alaf server service (alias services) | Manage the services in a compose stack (a multi-service project). |
alaf server domain | Manage custom domains, DNS verification, and SSL certificates. |
Self-host infrastructure — reference
| Command | Purpose |
|---|---|
alaf server server | Manage self-hosted SSH servers. |
alaf server system | Instance settings, onboarding, migration, and data transfer. |
alaf server mail | Self-hosted mail server (iRedMail) setup and admin. |
alaf server backup | Manage backups — policies, runs, restores, and destinations. |
Where to next
Running & updating
up, stop, update, install — operate Alaf Server itself.
Deploying
deploy, deployment, logs — the full deploy loop.
Projects, services & domains
init, project, service, and domain commands.
Access & the raw API
login, context, token, api — auth and any route.
Self-host infrastructure
server, system, mail, and backup for instances you run.