AlmaForge CLI Reference

This page covers the two AlmaForge command-line binaries:

• alma is the user CLI. Use it for login, resource access, configuration, admin tasks, and audit workflows. RBAC determines what each user can see and do.
• almad is the server daemon. It runs the Auth, Proxy, and resource services.

For installation, sign-in, shell completion, and the kubectl-style day-to-day workflow, see the CLI guide. This page is the reference for common commands and their flags. Use alma <command> --help for the complete list in your installed version.

alma

alma is the user-facing CLI for day-to-day cluster access and administration. The flags below are accepted by every alma subcommand. Subcommand-specific flags are documented alongside each command.

Global flags

Flag	Description
--proxy	Proxy address.
--ttl	Minutes-to-live for the issued session.
-i, --identity	Identity file to use instead of the local profile.
-d, --debug	Verbose logging to stdout.
--auth-server	Address of the Auth Service to connect to directly, bypassing the Proxy. Uses the local admin identity from --data-dir, which has a default path.
--data-dir	Path to the data directory holding the local admin identity (default /var/lib/almaforge).

Authentication

alma login

Log in to a cluster and receive a certificate.

text

alma login [flags] [cluster]

Flag	Description
-o, --out	Write identity to file instead of the local profile
-f, --format	Identity format: file, openssh, kubernetes
--overwrite	Overwrite existing identity file
--ca-pin	sha256:<hex> pin of the CA the Proxy presents, such as its self-signed certificate. Repeatable. The Proxy is trusted when that CA matches a pin, and the profile keeps the pins for later commands. Env: ALMA_CA_PIN.
--request-roles	Request one or more extra roles
--request-reason	Reason for requesting additional roles
--request-reviewers	Suggested reviewers for role request
--request-nowait	Finish without waiting for request resolution
--request-id	Login with the roles requested in the given request, named by ID or a unique prefix
--browser	Open a browser during login (default). Use --no-browser to print a sign-in URL for another device. This is a Boolean flag. A following value is treated as the cluster name.
--breakglass	Create a one-time recovery link with the local admin identity. Must run on an Auth host. Ignores every other login flag.
--kube-cluster	Name of the Kubernetes cluster to login to
-v, --verbose	Show extra status information

alma logout

Log out of the current cluster, removing local certificates.

text

alma logout

alma status

Show the current session and cluster status.

text

alma status [flags]

Flag	Default	Description
-f, --format	text	Output format: text, json, yaml
-v, --verbose		Show extra detail

---

Resource Access

alma ssh

Start an SSH session or run a command on a remote node.

text

alma ssh [flags] [user@]host [command...]

Flag	Description
-l, --login	Remote host login
-p, --port	SSH port on the remote host
-A, --forward-agent	Forward SSH agent
-L, --forward	Local port forwarding (local:remote)
-D, --dynamic-forward	SOCKS5 dynamic forwarding
-t, --tty	Force TTY allocation
--local	Execute command on localhost after connecting to SSH node
-N, --no-remote-exec	No remote command (port forwarding only)
-c, --cluster	Target cluster
-X, --x11-untrusted	Untrusted X11 forwarding
-Y, --x11-trusted	Trusted X11 forwarding
--x11-untrusted-timeout	Timeout for untrusted X11 forwarding
--request-reason	Reason for automatic access request
--disable-access-request	Disable automatic resource access requests
--log-dir	Directory for per-node command output logs

alma scp

Copy files to or from a remote node.

text

alma scp [flags] src dest

Flag	Description
-l, --login	Remote host login
-r, --recursive	Recursive copy
-P, --port	Remote port
-p, --preserve	Preserve timestamps
-q, --quiet	Quiet mode
-c, --cluster	Target cluster

alma node ls

List SSH nodes.

text

alma node ls [flags] [labels]

Alias: alma node list

alma app

Application access commands.

Command	Description
alma app ls	List applications
alma app login <app>	Get short-lived app certificate
alma app logout [app]	Remove app certificate
alma app config	Print app connection info

alma db

Database access commands.

Command	Description
alma db ls	List databases
alma db login <db>	Retrieve database credentials
alma db logout [db]	Remove database credentials
alma db env	Print database environment variables
alma db config	Print database connection info
alma db connect <db>	Connect to a database

Flag	Description
-c, --cluster	Target cluster

alma kube

Kubernetes access commands.

Command	Description
alma kube ls	List Kubernetes clusters
alma kube login <cluster>	Log in to a Kubernetes cluster
alma kube credentials	Get kubectl credentials (exec plugin)
alma kube sessions	List active Kubernetes sessions

alma proxy

Start a local TLS proxy for tunneled access.

Command	Description
alma proxy ssh	Local proxy for SSH
alma proxy db	Local proxy for database connections
alma proxy app	Local proxy for application connections
alma proxy kube	Local proxy for Kubernetes

alma request

Manage access requests.

Command	Description
alma request ls	List access requests
alma request show <id>	Show request details
alma request create	Create an access request
alma request review <id>	Review an access request
alma request search	Search for requestable resources
alma request drop	Drop access requests from current identity
alma request assume <id>	Assume an approved access request

For recurring credential delivery to files or Kubernetes Secrets, use alma export -c <file>. See Credential Export.

Resource filtering

Listing commands such as alma node ls, alma db ls, alma app ls, and alma kube ls accept --search and --query flags to filter results.

--search runs a fuzzy match against resource fields. For example, --search=mac matches any resource containing mac.

--query accepts a predicate expression for precise filtering on labels and fields.

You can combine both with a trailing comma-separated label selector.

Terminal

# List all nodesalma node ls
# List nodes by labelalma node ls env=staging,os=mac
# Fuzzy search across fieldsalma node ls --search=staging,mac
# Predicate query on labelsalma node ls --query='labels["env"] == "staging" && equals(labels["os"], "mac")'

---

Resource Configuration (CRUD)

These commands follow kubectl conventions and work across resource types. RBAC determines which resources each user can manage.

alma get

List resources or show one resource.

text

alma get <kind> [name] [flags]
alma get <kind>/<name> [flags]
alma get all

Flag	Default	Description
-o, --format	text	Output format: text, yaml, json
-v, --verbose		Full label output
--with-secrets	false	Include secrets (CAs, connectors)
--search		Fuzzy search keywords
--query		Predicate language filter

Supported resource types include role, user, node, app, db, kube, token, lock, session (active sessions), recording (finished sessions, the same set as alma recording ls, with a single recording read using alma recording play), connector (auth connectors), AuthConfig, NetworkConfig, RecordingConfig, alert, bot, and more. Run alma get --help for the full list.

alma apply

Create or update a resource, like kubectl apply.

text

alma apply -f resource.yaml
alma apply resource.yaml       # positional filename also accepted

Flag	Description
-f, --filename	Resource definition file (stdin if omitted)

The filename can be passed as a positional argument or with -f.

alma update

Patch resource metadata fields.

text

alma update <kind>/<name> [flags]

Flag	Description
--set-labels	Replace labels with a comma-separated key=value list
--set-ttl	Set resource TTL

alma create

Create a resource. The command fails if the resource already exists. Use apply to overwrite an existing resource.

From a file:

text

alma create -f resource.yaml

Imperative shortcuts:

Command	Description
alma create token --services=<services>	Create an invitation token
alma create bot <name> --roles=<roles>	Create a certificate renewal bot

alma delete

Delete a resource.

text

alma delete <kind> <name>
alma delete <kind>/<name>

Aliases: alma rm, alma del

alma edit

Open a resource in $EDITOR and apply changes on save.

text

alma edit <kind>/<name>

---

Audit

alma audit

List audit events, newest first. Use --type to select an event type. Repeat the flag to include multiple types.

Terminal

alma audit --last=1h --type=UserLoginalma audit -f -o json

alma recording

Session recording commands.

Command	Description
alma recording ls	List recordings
alma get recordings	List recordings, same set as recording ls
alma recording play <id>	Replay a recorded session

The audit and recording listing commands share these options:

Flag	Description
-f, --follow	Keep watching for new results until interrupted.
-o, --format	Output format: text, json, or yaml. Defaults to text.
--from-utc	Start date in YYYY-MM-DD format, at midnight UTC. Defaults to 24 hours ago.
--to-utc	End date in YYYY-MM-DD format, at midnight UTC. Defaults to the current time.
--last	Look back by a duration such as 1h30m. Cannot be combined with date bounds.
--limit	Maximum number of initial results. Defaults to 50.

Both commands list the most recent results first. The initial range cannot exceed 365 days or include future dates. With --follow, omit --to-utc. The command prints up to --limit initial results and then continues with new arrivals. Use --limit=0 to follow without printing existing history.

Terminal

alma recording ls --last=1h -o jsonalma recording ls -f --limit=0

Following checks for new results every five seconds, including records that arrive late. JSON output consists of successive arrays, one per batch. YAML output uses separate documents. Query work and memory grow with the number of records in the selected range.

---

Admin

Tokens

Invitation tokens for enrolling agents.

Command	Description
alma create token --services=<services>	Create an invitation token
alma get token	List tokens
alma delete token/<name>	Remove a token

Bots

Certificate renewal bots.

Command	Description
alma create bot <name> --roles=<roles>	Create a bot and print its enrollment command
alma get bot	List bots with the user and roles behind each one
alma delete bot/<name>	Remove a bot, along with the role created with it

alma create lock

Create a new cluster lock to disable a user, role, login, request, or server.

text

alma create lock [flags]

Flag	Description
--target-user	User to disable
--role	Role to disable
--target-login	Local UNIX user to disable
--access-request	Access request UUID to disable
--server-id	Server UUID to disable
--message	Message for locked-out users
--expires	Lock expiry (RFC3339)
--lock-ttl	Lock TTL duration

alma auth

Certificate authority operations.

Command	Description
alma auth export	Export public CA keys
alma auth sign	Create identity file(s) for a user
alma auth rotate	Rotate certificate authorities
alma auth ls	List connected auth servers
alma auth crl	Export certificate revocation list
alma auth pin	Print the CA pins used to verify the Auth Service during a join

alma get instance

Command	Description
alma get instance	List the instances registered with the cluster

alma alert

Cluster alert management.

Command	Description
alma alert ls	List alerts (alias: alma alert list)
alma alert create <message>	Create a cluster alert
alma alert ack <id>	Acknowledge an alert
alma alert ack ls	List acknowledged alerts

alma get cluster

Show the cluster you are connected to.

text

alma get cluster [flags]

Flag	Default	Description
-o, --format	text	Output format: text, yaml, json

---

Misc

alma version

Print the client and server version.

text

alma version [flags]

Flag	Default	Description
-f, --format	text	Output format: text, json, yaml
--client		Client version only (no server required)

alma get license

Show license status and current usage.

text

alma get license

almad

almad is the AlmaForge server daemon. One binary runs every cluster service: Auth, Proxy, SSH Node, Database, Application, Kubernetes, and the built-in access-request plugins. Role flags, environment variables, and resource files decide which services start.

almad does not have process-wide global flags. Each subcommand defines its own flags. almad start carries the longest flag list. Run almad <command> --help to inspect the exact flags for a subcommand.

Commands

Command	Purpose
almad start	Run almad in the foreground with services selected by service flags, environment variables, or resource files.
almad status	Print the active SSH session metadata when invoked from inside an almad SSH session.
almad version	Print the binary version. Add --raw for the bare version string.
almad install systemd	Render a systemd unit file for almad.
almad install script	Render a shell script that installs an agent on a fresh node.
almad join openssh	Enroll an existing OpenSSH server into the cluster without running the daemon.

Run almad <command> --help for the full flag list of any subcommand.

Starting a cluster

Set environment variables or place resource files under /etc/almaforge/almad.d, run the daemon, and optionally wire it into systemd. Use this flow to bring up a new Auth/Proxy or run almad as a long-lived service on any node.

almad start

almad start runs in the foreground and exits when interrupted. For production deployments, put resource files in /etc/almaforge/almad.d and set daemon defaults in the environment. The CLI flags below are most useful for bootstrapping and one-off invocations.

General

Flag	Default	Description
-d, --debug		Verbose stderr logging. Env: ALMA_DEBUG.
--log-level	info	Log severity: debug, info, warn, error. Env: ALMA_LOG_LEVEL.
--log-output	stderr	Log destination: stderr, stdout, syslog, or a file path. Env: ALMA_LOG_OUTPUT.
--log-format	text	Log line format: text for human-readable output, json for one JSON object per line. Env: ALMA_LOG_FORMAT.
--config-dir	/etc/almaforge/almad.d	Path to the config directory or file. Loaded on every start to apply typed resources (StorageConfig, roles, tokens, etc.). Env: ALMA_CONFIG_DIR.
--data-dir	/var/lib/almaforge	Directory for local state and the embedded SQLite store. Env: ALMA_DATA_DIR.
--pid-file		Write the process PID to this path.
-t, --test		Resolve the configuration and exit without starting any service.
--license-file		Path to the AlmaForge license file. Env: ALMA_LICENSE_FILE.
--permit-user-env		Read environment variables from ~/.ssh/environment, the OpenSSH PermitUserEnvironment file, when starting a session.

Services

Flag	Description
--auth-service	Run the Auth service. --no-auth-service turns it off. Env: ALMA_AUTH_SERVICE.
--proxy-service	Run the Proxy service. --no-proxy-service turns it off. Env: ALMA_PROXY_SERVICE.
--ssh-service	Run the SSH Node service. --no-ssh-service turns it off. Env: ALMA_SSH_SERVICE.
--database-service	Run the Database service. --no-database-service turns it off. Env: ALMA_DATABASE_SERVICE.
--app-service	Run the Application service. --no-app-service turns it off. Env: ALMA_APP_SERVICE.
--kubernetes-service	Run the Kubernetes service. --no-kubernetes-service turns it off. Env: ALMA_KUBERNETES_SERVICE.
--jira-service	Run the built-in Jira access-request plugin. --no-jira-service turns it off. Env: ALMA_JIRA_SERVICE.
--slack-service	Run the built-in Slack access-request plugin. --no-slack-service turns it off. Env: ALMA_SLACK_SERVICE.
--pagerduty-service	Run the built-in PagerDuty plugin. --no-pagerduty-service turns it off. Env: ALMA_PAGERDUTY_SERVICE.
--telegram-service	Run the built-in Telegram plugin. --no-telegram-service turns it off. Env: ALMA_TELEGRAM_SERVICE.

Cluster join

Flag	Description
--auth-server	Address of the Auth Service, for a Proxy joining an Auth fleet. An agent cannot use it: agents open no port and are reached through a tunnel they hold to a Proxy. Env: ALMA_AUTH_SERVER.
--proxy	Address of the Proxy Service. What every agent joins with. Env: ALMA_PROXY.
--client-id	Resource name (metadata.name) of the provisioning Token, or a path to a file containing it. Env: ALMA_CLIENT_ID.
ALMA_CLIENT_SECRET	Plaintext shared secret for the static join method. Environment-only (no CLI flag), keeping the value out of command-line arguments.
--ca-pin	sha256:<hex> pin of the Auth Server CA. Repeatable. Used on first join. Env: ALMA_CA_PIN.
--join-method	Join method: static, aws, ec2, kubernetes, azure, gcp, github, gitlab, circleci, spacelift. Env: ALMA_JOIN_METHOD.
--nodename	Override the node name (defaults to the host's hostname). Env: ALMA_NODE_NAME.
--labels	Comma-separated key=value static labels for this node. Env: ALMA_LABELS.

Networking

--listen is the shared TLS listener: one TLS port that serves every proxy protocol via SNI/ALPN. It is the only listener bound by default. Dedicated listener flags can add an entry point or move a protocol to another port. See how dedicated ports change access.

Each listener is paired with its advertise flag immediately below it.

Flag	Default	Description
--listen	0.0.0.0:443	Shared TLS listener. Bound when the Proxy Service or Auth Service is enabled. Env: ALMA_LISTEN.
--advertise		Canonical endpoint advertised to clients (alma.example.com:443). Used for SSO redirects, ACME, and as the fallback for every --*-advertise override. Env: ALMA_ADVERTISE.
--kube-listen		Optional dedicated kube SNI port. The kube SNI route on the shared TLS listener is on by default. Set this only to add a separate listener. Env: ALMA_KUBE_LISTEN.
--kube-advertise		Override for alma kube login config server URL. Env: ALMA_KUBE_ADVERTISE.
--tunnel-listen		Optional dedicated reverse tunnel port. Env: ALMA_TUNNEL_LISTEN.
--tunnel-advertise		Override for agent reverse-tunnel reconnect URL. Env: ALMA_TUNNEL_ADVERTISE.
--mysql-listen		Optional native MySQL wire-protocol port. Env: ALMA_MYSQL_LISTEN.
--mysql-advertise		Override for MySQL client connection display. Env: ALMA_MYSQL_ADVERTISE.
--postgres-listen		Optional native Postgres wire-protocol port. Env: ALMA_POSTGRES_LISTEN.
--postgres-advertise		Override for Postgres client connection display. Env: ALMA_POSTGRES_ADVERTISE.
--mongo-listen		Optional native Mongo wire-protocol port. Env: ALMA_MONGO_LISTEN.
--mongo-advertise		Override for Mongo client connection display. Env: ALMA_MONGO_ADVERTISE.
--ssh-listen		Optional dedicated proxy SSH port (alma ssh raw-SSH path). Configures the Proxy Service ingress, not the SSH Node service. Env: ALMA_SSH_LISTEN.
--ssh-advertise		Override for the proxy's SSH ingress public address. Env: ALMA_SSH_ADVERTISE.
--peer-listen		Proxy-to-proxy peering listener for HA proxy clusters. Env: ALMA_PEER_LISTEN.
--peer-advertise		Address this proxy advertises to peer proxies. Env: ALMA_PEER_ADVERTISE.
--diag-listen		Diagnostics endpoint (/healthz, /readyz, plus /debug/pprof/* under --debug). Also serves /metrics while --metrics-listen is unset. Operator-only. No advertise. Env: ALMA_DIAG_LISTEN.
--metrics-listen		Prometheus metrics endpoint (/metrics). Operator-only. No advertise. Env: ALMA_METRICS_LISTEN.
--metrics-tls-cert		Certificate the metrics listener presents. Env: ALMA_METRICS_TLS_CERT.
--metrics-tls-key		Private key for --metrics-tls-cert. Env: ALMA_METRICS_TLS_KEY.
--metrics-client-ca		CA a scraper must present a certificate from. The metrics listener serves mutual TLS or plaintext, so these three go together with --metrics-listen and a subset fails at startup. Env: ALMA_METRICS_CLIENT_CA.
--real-ip-from		Networks a client-supplied source address is believed from (comma-separated CIDRs or bare IPs). Empty believes none. Env: ALMA_REAL_IP_FROM.
--real-ip-header	proxy_protocol	The one channel a trusted proxy may use to give the client address (proxy_protocol / X-Forwarded-For / X-Real-IP / off). Env: ALMA_REAL_IP_HEADER.
--proxy-protocol		Whether a PROXY protocol header is required on the multiplex listener (on / off). Unset allows one without requiring it. Believing the address it carries is controlled by --real-ip-from and --real-ip-header. Env: ALMA_PROXY_PROTOCOL.
--tls-cert		Path to a TLS certificate for the Proxy. Env: ALMA_TLS_CERT.
--tls-key		Path to the matching TLS private key. Set both or neither. Half a pair fails at startup. Without a supplied pair or ACME, the Proxy uses a self-signed certificate. Env: ALMA_TLS_KEY.
--tls-reload-interval		How often the Proxy re-reads --tls-cert, for example 1h. Set it to pick up a renewal issued out of band without restarting. Unset loads the certificate once at startup. Env: ALMA_TLS_RELOAD_INTERVAL.
--acme		Enable ACME / Let's Encrypt certificate provisioning on the Proxy. Env: ALMA_ACME_ENABLED.
--acme-email		Registration email for ACME. Env: ALMA_ACME_EMAIL.
--acme-uri	Let's Encrypt production	ACME directory to use. Point it at a staging directory while testing so experiments do not consume the production rate limit, or at a private CA. Env: ALMA_ACME_URI.

Storage backends

Each flag holds a single URI parsed into a typed StorageConfig. The URI grammar (schemes, query keys) is documented in Storage backends → URI format.

Flag	Description
--state-uri	Cluster state backend URI. Examples: sqlite:///var/lib/almaforge/backend, postgres://user@host/db, dynamodb://table?region=us-east-1. Env: ALMA_STATE_URI.
--audit-uri	Audit events sink URI. Examples: dynamodb://events?region=us-east-1, postgres://user@host/audit, file:///var/log/almaforge/audit. Env: ALMA_AUDIT_URI.
--recordings-uri	Session recordings storage URI. Examples: s3://bucket/prefix?region=us-east-1, gs://bucket/prefix, file:///var/lib/almaforge/records. Env: ALMA_RECORDINGS_URI.

For multi-sink audit fan-out, use typed StorageConfig documents under --config-dir instead of the single-URI flag.

CA keystore

Where the Auth Service keeps its CA private keys. Name the driver explicitly: settings for a driver you did not select are a startup error rather than a silent fall back to software keys.

Flag	Default	Description
--ca-keystore	software	Keystore driver: software, pkcs11 or gcp_kms. Env: ALMA_CA_KEYSTORE.
--pkcs11-module		Path to the PKCS#11 module. Required for pkcs11. Env: ALMA_PKCS11_MODULE.
--pkcs11-slot		Slot number holding the token. Give this or --pkcs11-token-label. Env: ALMA_PKCS11_SLOT.
--pkcs11-token-label		Label of the token to use. Give this or --pkcs11-slot. Env: ALMA_PKCS11_TOKEN_LABEL.
--pkcs11-pin		PIN for the token. An absolute path is read as a file holding the PIN, which keeps it out of the process environment. Env: ALMA_PKCS11_PIN.
--gcp-kms-keyring		Fully qualified GCP KMS keyring name. Required for gcp_kms. Env: ALMA_GCP_KMS_KEYRING.
--gcp-kms-protection-level	SOFTWARE	GCP KMS protection level: HSM or SOFTWARE. Env: ALMA_GCP_KMS_PROTECTION_LEVEL.

Tracing

Flag	Default	Description
--traces-otlp-uri		OTLP endpoint traces are exported to. Naming an endpoint is what turns tracing on. Env: ALMA_TRACES_OTLP_URI.
--traces-sampling-rate	1.0	Fraction of traces recorded, from 0.0 to 1.0. Requires --traces-otlp-uri. Env: ALMA_TRACES_SAMPLING_RATE.

Application service

Run almad start --app-service and define AppTarget resources under /etc/almaforge/almad.d.

The flags below describe a single application on the command line instead, which is what the join command printed by alma create token --services=app uses. --app-name is required as soon as any of the others is set.

Flag	Description
--app-name	Name of the application to serve.
--app-uri	Internal address the application is reachable at.
--app-advertise	DNS name clients reach the application by. Routing is by name on the web proxy port, so a port or a literal IP is rejected.

Database service

Run almad start --database-service and define DatabaseTarget resources under /etc/almaforge/almad.d.

The flags below describe a single database on the command line instead, which is what the join command printed by alma create token --services=database uses. --db-name is what turns them on: without it the rest are ignored and the service starts with no database.

Flag	Description
--db-name	Name of the proxied database.
--db-protocol	Wire protocol: postgres, mysql, mongodb, cockroachdb, redis, snowflake, cassandra, elasticsearch, opensearch, dynamodb, clickhouse or clickhouse-http.
--db-uri	Address the database is reachable at.
--db-ca-cert	Path to the CA certificate the database's own certificate is checked against.
--db-aws-region	AWS region the database runs in. Required for RDS and Aurora.

Kubernetes service

Flag	Description
--kubeconfig	Path to a kubeconfig used to register external Kubernetes clusters. Env: ALMA_KUBECONFIG.

Resource matching

Flag	Description
--match-labels	Label matcher for dynamically registered databases, applications, and Kubernetes clusters. Env: ALMA_MATCH_LABELS.

Examples

Terminal

# Single-node cluster (auth + proxy + node).sudo almad start
# SSH Node joining an existing cluster.sudo ALMA_CLIENT_SECRET=/etc/almaforge/client-secret \    almad start \    --ssh-service \    --no-auth-service \    --no-proxy-service \    --proxy=proxy.example.com:443 \    --client-id=db-prod-1 \    --labels=env=prod,role=db
# App agent joining an existing cluster. The apps it serves come# from AppTarget resources, not from flags.sudo ALMA_CLIENT_SECRET=/etc/almaforge/client-secret \    almad start \    --app-service \    --no-auth-service \    --no-proxy-service \    --proxy=proxy.example.com:443 \    --client-id=billing-app

almad install systemd

Render a systemd unit file for almad. Defaults match the package layout.

Flag	Description
--env-file	Path to the environment file.
--fd-limit	Maximum open file descriptors.
--binary	Full path to the almad binary.
-o, --output	Output destination (stdout, file:///path).
--data-dir	Data directory embedded in the unit.

almad install script

Render a shell script that installs and joins an agent on a fresh node. The script is written to almaforge.sh in the current directory. Use -o stdout to write it to standard output instead, or -o file:///path to choose another location.

Joining a cluster

Helpers for adding a new node, agent, or service to an existing cluster.

almad join openssh

Enroll an existing OpenSSH server into the cluster without running the almad daemon. The command writes credentials, updates sshd_config, and (by default) restarts sshd.

Flag	Description
--proxy	Address of the Proxy Service.
--client-id	Token resource name on the cluster (literal or file path). Pair with ALMA_CLIENT_SECRET for the static method.
--join-method	static, aws, ec2, kubernetes, azure, gcp, github, gitlab, circleci, or spacelift.
--openssh-config	Path to the sshd config (default /etc/ssh/sshd_config).
--data-dir	Directory for local state.
--restart-sshd	Restart sshd after writing config (default true).
--sshd-check-command	Command used to validate the new sshd config.
--sshd-restart-command	Command used to restart OpenSSH. Defaults to systemctl restart on the unit the host installs, sshd.service or ssh.service.
--labels	Comma-separated key=value labels for the OpenSSH node.
--address	IP address of this OpenSSH node.
--additional-principals	Extra principals to include on the certificate.

Misc

almad status

When invoked from inside a session opened by an almad SSH Node, prints the session metadata: cluster, user, roles, and certificate expiration. Useful for debugging RBAC and join behavior.

almad version

Print the binary version. Add --raw for the bare version string (useful in scripts).

Query Examples

Resource-listing commands accept --query. The flag takes a predicate expression that is evaluated against each resource. Resources for which the expression evaluates to true are returned.

Examples:

Terminal

alma node ls --query 'labels["env"] == "prod"'alma db ls --query 'contains(labels["team"], "platform")'alma app ls --query 'hasPrefix(name, "billing-")'