CLI Reference

The airdress-operator binary is the single entry point for running the Airdress operator, managing DNS records, enrolling endpoints, installing apps, and inspecting system state. Every subcommand supports --help for inline usage.

airdress-operator --help
airdress-operator <command> --help

Global flags

These flags apply to every subcommand.

Flag	Short	Env	Default	Description
`--config <PATH>`	`-c`	`AIRDRESS_CONFIG`	`/etc/airdress/operator.toml`	Path to the TOML config file
`--log-level <LEVEL>`	`-l`	`AIRDRESS_LOG`	`info`	Log verbosity: `trace`, `debug`, `info`, `warn`, `error`
`--format <FORMAT>`			`human`	Output format: `human` or `json`

The --format json flag is useful for scripting. When set, every command that produces output emits newline-delimited JSON instead of human-readable text.

serve

Start the operator relay server. This is the primary long-running process that establishes a WireGuard tunnel to the nearest Airdress relay PoP and listens for incoming connections.

airdress-operator serve [FLAGS]

Flag	Short	Env	Default	Description
`--bind <ADDR>`	`-b`	`AIRDRESS_BIND`	`127.0.0.1:8080`	HTTP listener address
`--wg-port <PORT>`	`-w`	`AIRDRESS_WG_PORT`	`51820`	WireGuard UDP port

# Start with defaults
airdress-operator serve

# Bind to all interfaces on a custom port
airdress-operator serve --bind 0.0.0.0:9090 --wg-port 51821

INFO  operator ready  bind=127.0.0.1:8080  wg_port=51820

config

Validate and display the resolved configuration. The output shows the final merged result of compiled defaults, config file values, and environment variable overrides.

airdress-operator config [FLAGS]

Flag	Short	Env	Default	Description
`--check`				Validate without printing. Exits 0 on success, non-zero on error.

# Print resolved config
airdress-operator config

# Validate only (useful in CI)
airdress-operator config --check && echo "OK"

health

Check whether the operator is running and its relay tunnel is established.

airdress-operator health [FLAGS]

Flag	Short	Env	Default	Description
`--url <URL>`	`-u`	`AIRDRESS_URL`	`http://127.0.0.1:8080`	Operator base URL to probe

airdress-operator health

OK  operator healthy  uptime=3h12m  tunnel=established

status

Display operator status and runtime metrics. This includes tunnel state, connected endpoints, DNS record count, and resource usage.

airdress-operator status

Operator    airdress-operator 0.x.y
Uptime      3h 12m 45s
Tunnel      established (relay-ams, 12ms RTT)
Endpoints   2 enrolled
DNS records 4

dns

Manage DNS records served by the operator’s built-in authoritative DNS server.

dns add

Add a DNS record.

airdress-operator dns add <NAME> <TYPE> <RDATA> [--ttl <SECS>]

Argument / Flag	Default	Description
`NAME`		Record name (e.g. `myapp.humans.airdress.co`)
`TYPE`		Record type: `A`, `AAAA`, `CNAME`, `TXT`, `MX`, `SRV`
`RDATA`		Record data (e.g. `192.168.1.10`)
`--ttl <SECS>`	`60`	Time to live in seconds

airdress-operator dns add myapp.humans.airdress.co A 192.168.1.10 --ttl 300

dns rm

Remove DNS records. If TYPE is omitted, all records for the name are removed.

airdress-operator dns rm <NAME> [<TYPE>]

# Remove all records for the name
airdress-operator dns rm myapp.humans.airdress.co

# Remove only A records
airdress-operator dns rm myapp.humans.airdress.co A

dns list

List all DNS records managed by the operator.

airdress-operator dns list

NAME                            TYPE  RDATA           TTL
myapp.humans.airdress.co        A     192.168.1.10    300
api.humans.airdress.co          A     192.168.1.11    60

dns reload

Reload DNS records from the configuration. Internally sends SIGHUP to the DNS subsystem.

airdress-operator dns reload

postgres

Manage the embedded PostgreSQL instance. When the operator runs without an external database.url, it manages a PostgreSQL child process automatically. These subcommands inspect that instance.

postgres path

Print the PostgreSQL data directory.

airdress-operator postgres path

./var/postgres

postgres version

Print the PostgreSQL version requirement.

airdress-operator postgres version

=18.3.0

postgres url

Print the connection URL for the embedded or configured database.

airdress-operator postgres url

postgres psql

Open an interactive psql session against the operator database. This execs into psql with the correct connection parameters.

airdress-operator postgres psql

plugin-db

Manage the encrypted plugin database.

plugin-db init-key

Generate a random 32-byte master encryption key, base64-encoded. Store this value securely; it is required to decrypt plugin data.

airdress-operator plugin-db init-key

dGhpcyBpcyBhIDMyLWJ5dGUga2V5IGZvciBkZW1v...

endpoint

Manage device endpoints enrolled with the operator.

endpoint enroll

Enroll a new device endpoint.

airdress-operator endpoint enroll [FLAGS]

Flag	Env	Description
`--airdress <NAME>`		Airdress name to enroll under
`--bootstrap-token <TOKEN>`	`AIRDRESS_BOOTSTRAP_TOKEN`	One-time bootstrap token
`--device-label <LABEL>`		Human-readable device label
`--transport-profile <PROFILE>`		Transport profile to use

airdress-operator endpoint enroll \
  --airdress myname \
  --bootstrap-token abc123 \
  --device-label "dev-laptop"

endpoint list

List enrolled endpoints.

airdress-operator endpoint list --token <TOKEN>

Flag	Short	Env	Default	Description
`--token <TOKEN>`		`AIRDRESS_TOKEN`		Bearer token for authentication

endpoint revoke

Revoke an enrolled endpoint by ID.

airdress-operator endpoint revoke <ID> --token <TOKEN>

Argument / Flag	Env	Description
`ID`		Endpoint ID to revoke
`--token <TOKEN>`	`AIRDRESS_TOKEN`	Bearer token for authentication

chat

Manage the chat pairing flow.

chat pair

Pair a device for chat federation.

airdress-operator chat pair [FLAGS]

Flag	Env	Description
`--airdress <NAME>`		Airdress name to pair with
`--bootstrap-token <TOKEN>`	`AIRDRESS_BOOTSTRAP_TOKEN`	Bootstrap token
`--device-label <LABEL>`		Device label

ingress

Manage inbound event endpoints (webhooks, callbacks).

ingress list

List all registered inbound endpoints.

airdress-operator ingress list

ingress test

Send a test event to an inbound endpoint.

airdress-operator ingress test <SLUG> [FLAGS]

Argument / Flag	Default	Description
`SLUG`		Endpoint slug to test
`--url <URL>`		Override destination URL
`--payload <JSON>`		JSON payload to send

airdress-operator ingress test github-webhook --payload '{"action":"ping"}'

app

Install, manage, and inspect mini-apps running under the operator.

app install

Install a mini-app.

airdress-operator app install <AIRDRESS> <APP_TYPE> [--subdomain <SUB>]

Argument / Flag	Description
`AIRDRESS`	Airdress name to install under
`APP_TYPE`	App type from the registry
`--subdomain <SUB>`	Custom subdomain (auto-generated if omitted)

app uninstall

Uninstall a mini-app.

airdress-operator app uninstall <AIRDRESS> <SUBDOMAIN> --purge [--backup]

Argument / Flag	Description
`AIRDRESS`	Airdress name
`SUBDOMAIN`	App subdomain
`--purge`	Remove all data
`--backup`	Create a backup before purging

app enable / disable

Enable or disable an installed app without uninstalling it.

airdress-operator app enable <AIRDRESS> <SUBDOMAIN>
airdress-operator app disable <AIRDRESS> <SUBDOMAIN>

app list

List all installed apps for an airdress.

airdress-operator app list <AIRDRESS>

app status

Show the status of a specific app.

airdress-operator app status <AIRDRESS> <SUBDOMAIN>

app db-access

Open a database session for an app’s isolated database.

airdress-operator app db-access <AIRDRESS> [--subdomain <SUB>]

federation

Inspect and manage chat federation state.

federation status

Show federation status.

airdress-operator federation status [--url <URL>]

Flag	Env	Default	Description
`--url <URL>`	`AIRDRESS_URL`	`http://127.0.0.1:8080`	Operator base URL

federation dns-records

Print the DNS records required for federation discovery.

airdress-operator federation dns-records [--ttl <SECS>]

Flag	Default	Description
`--ttl <SECS>`		TTL for generated records

federation rotate

Rotate federation keys for an airdress.

airdress-operator federation rotate <AIRDRESS> [--confirm]

Argument / Flag	Description
`AIRDRESS`	Airdress name to rotate keys for
`--confirm`	Skip confirmation prompt

Environment variables

Every flag that accepts an environment variable is listed above with its corresponding command. This table collects all supported variables in one place.

Operator variables

Variable	Maps to	Description
`AIRDRESS_CONFIG`	`--config`	Config file path
`AIRDRESS_LOG`	`--log-level`	Log level
`AIRDRESS_BIND`	`serve --bind`	HTTP bind address
`AIRDRESS_WG_PORT`	`serve --wg-port`	WireGuard UDP port
`AIRDRESS_URL`	`health --url`, `federation --url`	Operator base URL
`AIRDRESS_TOKEN`	`endpoint list/revoke --token`	Bearer token
`AIRDRESS_BOOTSTRAP_TOKEN`	`endpoint enroll --bootstrap-token`	Bootstrap token
`AIRDRESS_DATABASE_URL`	`database.url` config field	External PostgreSQL connection URL
`AIRDRESS_AUTH__ISSUER`	`auth.issuer` config field	OIDC issuer URL
`AIRDRESS_AUTH__JWKS_URI`	`auth.jwks_uri` config field	JWKS endpoint URL
`AIRDRESS_AUTH__AUDIENCE`	`auth.audience` config field	Expected JWT audience
`AIRDRESS_ENROLLMENT__BOOTSTRAP_TOKEN`	`enrollment.bootstrap_token` config field	First enrollment secret
`AIRDRESS_CHAT__FEDERATION__KEYSTORE_PASSPHRASE`	federation keystore	KEK passphrase for federation keys
`AIRDRESS_SECRETS_KEY`	`plugin_db.secrets`	Base64-encoded 32-byte master encryption key

Installer variables

These variables control the behavior of the shell installer at https://get.airdress.co/operator.

Variable	Default	Description
`AIRDRESS_OPERATOR_VERSION`	auto-detected	Pin a specific version
`AIRDRESS_OPERATOR_HOME`	`$HOME/.local`	Install prefix (`bin/` is appended)
`AIRDRESS_OPERATOR_VERIFY`	`optional`	Minisign verification: `required`, `optional`, or `skip`
`AIRDRESS_OPERATOR_PRERELEASE`	`0`	Set to `1` to install the latest pre-release instead of latest stable
`AIRDRESS_OPERATOR_KIND`	`auto`	Package format: `binary`, `tar.gz`, `deb`, `rpm`, or `auto`
`AIRDRESS_OPERATOR_NO_SUDO`	`0`	Set to `1` to force user-space install (no sudo)

# Install a specific version without sudo
AIRDRESS_OPERATOR_VERSION=0.4.2 AIRDRESS_OPERATOR_NO_SUDO=1 \
  curl -fsSL https://get.airdress.co/operator | sh