Skip to main content

CLI Guide

The alma CLI is how engineers connect to an AlmaForge cluster from their workstation. On Linux, it ships in the same package as the daemon. On macOS, it ships as a signed .pkg installer. Windows is supported through WSL.

Install​

The install.sh script detects your platform (Linux amd64/arm64, or macOS amd64/arm64) and installs AlmaForge using the recommended method (package manager or signed binary). For binary downloads, SHA-256 verification requires shasum or sha256sum, and GPG verification requires both gpg and gpgv. Install those tools before running the script to enable both checks:

Terminal
curl -fL https://get.almaforge.com/install.sh | sh

The script installs the full AlmaForge package, which includes both almad and alma. Operator workstations only run alma. The server binary is installed but remains stopped unless you start it.

Verify the installation:

Terminal
alma version --clientClient Version: v2026.1.26+g5ab8dcffcb

Sign in​

Once alma is installed, sign in against a running cluster. Get the proxy address from your cluster operator. If you are standing up a cluster yourself, follow the Standalone guide first.

Terminal
alma login --proxy=almaforge.example.com:443

A browser opens to the cluster's login page. If the cluster has more than one SSO connector configured, you pick one from the list. Complete the SSO flow in the browser and the cluster issues a short-lived certificate that alma stores under ~/.config/almaforge/ (or $XDG_CONFIG_HOME/almaforge/ when set). On headless workstations, add --no-browser and open the printed URL on another device.

The Proxy's TLS certificate must be trusted by your workstation. The default Let's Encrypt setup uses the existing system trust store. For a privately issued Proxy certificate, obtain its signing CA from your cluster operator and install it before signing in. See operator-supplied certificates. Keep certificate verification enabled when enrolling an identity.

Non-interactive login

CI runners, bots, and services authenticate without a browser through workload identity. The cluster issues short-lived certificates against a join method (GitHub OIDC, GitLab JWT, Kubernetes ServiceAccount, AWS IAM, and others) and the caller passes the resulting identity file with -i. No static credentials, no human in the loop.

Shell completion​

alma and almad ship bash and zsh completion. Press Tab after the binary name to list subcommands. Press Tab after -- to list flags.

Add to ~/.bashrc:

~/.bashrc
eval "$(alma --completion-script-bash)"eval "$(almad --completion-script-bash)"

Add to ~/.zshrc:

~/.zshrc
autoload -Uz compinitcompiniteval "$(alma --completion-script-zsh)"eval "$(almad --completion-script-zsh)"

Reload your shell.

Day-to-day​

If you have used kubectl, the model is familiar. AlmaForge exposes its objects through the same CRUD verbs (get, apply, edit, delete) over the same apiVersion / kind / metadata / spec shape. Common kinds:

  • Targets: node (SSH host), kube (Kubernetes cluster), db (database), app (HTTP application).
  • Identity and policy: role, user, token, connector, lock.
  • Sessions: session (live sessions).

See resource manifests for the full schema.

Terminal
alma status                       # current identity, roles, expiryalma get node                     # list reachable SSH hostsalma get kube                     # list reachable Kubernetes clustersalma get db                       # list reachable databasesalma get session                  # list live sessionsalma get role                     # list all rolesalma get role/devops -o yaml      # full YAML of one resourcealma apply -f role.yaml           # create or update from a manifestalma edit role/devops             # open in $EDITOR, apply on savealma delete role/devops           # removealma ssh <user>@<host>            # SSH to a managed hostalma kube login <name>            # kubeconfig for a Kubernetes targetalma db login <name>              # client cert for a database targetalma logout                       # discard the local identity

The certificate expires automatically. Run login again when it does. The kubeconfig integration obtains credentials for kubectl through alma and can reuse an unexpired credential. See Kubernetes access.

For the full command tree, every subcommand, and every flag, see the CLI reference.

Multiple clusters​

Each successful login writes a profile. Inspect the current profile or select a cluster for one command:

Terminal
alma statusalma --proxy=almaforge.example.com:443 status

alma reads current-profile in the profile directory ($XDG_CONFIG_HOME/almaforge/ or ~/.config/almaforge/) to decide which cluster a bare command targets. Set the proxy explicitly to override for a single command.

Next steps​