Running & updating

Start, stop, update, and health-check the Alaf Server server itself from the terminal — up, stop, update, install, open, status, and doctor.

These commands run and maintain Alaf Server itself — the server that everything else talks to — rather than your deployed apps. Start the server, keep it up to date, and check that it's healthy.

Two different things called “install”

There are two ways to run Alaf Server, and they don't overlap:

alaf server up runs the self-hosted server (API + dashboard) from the globally-installed CLI. This is what most self-hosters want. alaf server update keeps it current.
alaf server install downloads the desktop app (a .dmg / .AppImage / .zip) — a packaged, double-click version for a single machine. It's a separate artifact from the CLI.

The reporting commands — status, doctor, update, install, and install cache — also accept the global --json flag for machine-readable output:

alaf server status --json

Command summary

Command	Purpose
`alaf server up`	Start the server as a persistent, auto-restarting service.
`alaf server stop`	Stop that service.
`alaf server update`	Update the CLI + bundled server to the latest release.
`alaf server install`	Download and install the Alaf Server desktop app.
`alaf server install cache`	Inspect and clean the desktop-app download cache.
`alaf server open`	Open the 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, context, runtime).

Starts Alaf Server as a persistent service that starts on boot and auto-restarts if it crashes, then keeps running until you alaf server stop. The API is served at /api (default port 4000) and the dashboard on port 3001. On a local box, access over loopback needs no token.

# Start the service (API on :4000, dashboard on :3001)
alaf server up

# Run attached in this terminal instead (Ctrl-C to stop)
alaf server up --foreground

# Preview the service definition without installing it
alaf server up --dry-run

Flag	Purpose	Default
`--port <port>`	API port to listen on.	`4000`
`--data-dir <dir>`	Directory for the embedded database.	`~/.alaf server/data`
`--dashboard-port <port>`	Dashboard port.	`3001`
`--no-ui`	Run the API only — don't download or serve the dashboard.	—
`--ui-version <tag>`	Dashboard release tag to run.	this CLI's version
`-f`, `--foreground`	Run attached in this terminal instead of as a background service.	—
`--dry-run`	Print the service definition that would be installed, then exit.	—

The dashboard is downloaded on first run

Unless you pass --no-ui, the dashboard bundle is lazy-downloaded from GitHub releases the first time you run alaf server up and pinned to match the CLI version. If it can't be fetched, the API keeps serving on its own — retry alaf server up, pass --no-ui, or use alaf server install for the desktop app.

`alaf server stop`

Stops the service started by alaf server up. Once stopped it will not auto-restart or come back on reboot. Takes no flags.

alaf server stop

`alaf server update`

Updates the globally-installed CLI — which bundles the self-hosted server — to the latest published release. This checks GitHub releases (not your Alaf Server API) and re-installs the global package with your package manager. After it finishes, restart the server so it runs the new version.

# Update to the latest release
alaf server update

# Just report current vs. latest — install nothing
alaf server update --check

# Force a package manager
alaf server update --via npm

Flag	Purpose
`--check`	Only report the current + latest version; don't install.
`--via <manager>`	Package manager to update with: `bun` or `npm` (default: `bun` if present, else `npm`).

Restart after updating

alaf server update swaps out the installed files but does not restart a running server. Run alaf server up again afterward to pick up the new version.

`alaf server install`

Downloads the Alaf Server desktop app for your OS and architecture (macOS .dmg, Linux .AppImage, or Windows .zip), verifies it against its published .sha256 checksum, installs it, and launches it. This is separate from the CLI/server — see the callout at the top of this page.

# Install the latest desktop release and launch it
alaf server install

# Pin a specific release, and don't open it after installing
alaf server install --version v1.2.3 --no-launch

Flag	Purpose
`--version <tag>`	Release tag to install (e.g. `v1.2.3`).
`--latest`	Install the latest release (this is the default).
`--force`	Re-download even if a verified copy is already cached.
`--no-verify`	Skip SHA-256 verification (only allowed when no checksum sidecar exists).
`--no-launch`	Install without launching the app.

Checksums are enforced by default

Downloads are verified against a published .sha256 sidecar and the install is fail-closed: if the sidecar is missing, Alaf Server refuses to install unless you pass --no-verify. A checksum mismatch always aborts — the download may be corrupt or tampered with.

`alaf server install cache`

Manages ~/.alaf server/cache, where alaf server install stores downloaded release assets and their checksum sidecars. Runs entirely offline — no API calls. Call it with a subcommand:

Subcommand	Purpose
`path`	Print the cache directory path.
`list` (alias `ls`)	List cached release assets.
`verify [tag]`	Re-hash cached assets and compare to their `.sha256` sidecar (optionally one tag).
`clean [tag]`	Delete cached assets (one tag, or all if omitted).

alaf server install cache list
alaf server install cache verify v1.2.3
alaf server install cache clean          # remove everything

`alaf server open`

Opens the Alaf Server dashboard in your default browser. For a local dashboard it first checks that the API is responding, and warns (without blocking) if it isn't yet.

# Open the active context's dashboard
alaf server open

# Open a specific page on the hosted cloud dashboard
alaf server open --cloud --path /settings

Flag	Purpose
`--cloud`	Open the hosted cloud dashboard (`server.alafteknoloji.com`).
`--dashboard-url <url>`	Dashboard base URL to open.
`--context <name>`	Context whose dashboard URL to open.
`--path <path>`	Path to open on the dashboard (e.g. `/settings`).

`alaf server status`

Prints a snapshot of the active context's API: whether it's reachable, its health, and how it's configured (self-hosted vs. cloud, deploy mode, auth mode, team mode, and host/machine details when present). Exits non-zero if the API can't be reached.

alaf server status
alaf server status --json

Contexts and which one is active are managed with alaf server context; sign-in lives under the auth commands.

`alaf server doctor`

Runs preflight checks so you can confirm the CLI is set up before relying on it — handy in scripts, which can gate on its exit code (non-zero if any check fails). Takes no flags.

It checks:

Check	What it confirms
`config`	The CLI config file exists.
`context`	The active context has a token.
`api`	That context's API is reachable (`GET /api/health`).
`node`	The Node.js runtime version.
`bun`	The Bun runtime version (optional).

alaf server doctor
alaf server doctor --json

Fixing failed checks

If context or api don't pass, you usually just need to sign in or point at a running server — see the auth commands and alaf server up above.