CLI setup

Data directory

The CLI stores its configuration at $SWARM_HOME (default: ~/.swarm/).

File	Purpose
config.json	Saved defaults for common flags
client.crt, client.key	Your mTLS client certificate and key (created by swarm login)
server.pem	The swarm CA certificate pinned at login — the trust anchor for the server’s TLS identity

Connect to the server

Point the CLI at your running server:

swarm config set server https://localhost:8800

This is the only required CLI configuration. All cloud credentials and SSH keys are managed on the server side.

Authenticate (one-time)

The server’s API is protected by mutual TLS. Enroll this machine with the one-time token the server printed at first start (or minted via swarm server token):

swarm login --token <token>

swarm login generates a client keypair, exchanges it for a CA-signed certificate, and stores it in ~/.swarm. Afterwards every CLI command (and the TUI) authenticates automatically. If the server’s certificate is not yet trusted, pass its CA bundle explicitly instead of the default trust-on-first-use pin:

swarm login --ca /path/to/ca.crt --token <token>

The CA certificate is also served publicly by the server at GET /ca, so scripts can fetch it without logging in.

Managing users (operator)

swarm user list                 # show enrolled users and revocation status
swarm user revoke <serial>      # revoke a user's certificate (instant)
swarm server token              # print a fresh one-time enrollment token

Revocation takes effect immediately: the revoked certificate’s next request gets a 401. Certificates otherwise live for a year; expiry is the backstop.

Save defaults

Avoid repeating flags on every command:

swarm config set <key> <value>

Valid keys:

Key	Used by	Description
server	All server commands	URL of the swarm-server instance
zone	vm create	Datacenter zone (e.g. fi-hel1)
plan	vm create	Server plan/size (e.g. 1xCPU-1GB)
template	vm create	OS template UUID

(The server-side keys ssh-key, agent-binary, provider-username-cmd, provider-password-cmd, provider-token-cmd are accepted for config parity but not used by the CLI.)

Example:

swarm config set server https://localhost:8800
swarm config set zone fi-hel1
swarm config set plan 1xCPU-1GB
swarm config set template 01000000-0000-4000-8000-000030200364

Show the current configuration:

swarm config show

Unset values show (not set).

Next

• VM management
• Security model — tokens, certificates, revocation, CA rotation