# airdress-operator CLI reference

**Looking for the airdress CLI?:** This page is about `airdress-operator`, the server an airdress runs on. To
work with your airdress from a terminal, you want the
[`airdress` CLI](/cli/) instead.

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.

```sh
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 server. This is the long-running process that serves the airdress: its API, functions, plugins and chat.

```sh
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 listen port for agent tunnels |

```sh
# Start with defaults
airdress-operator serve

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

## config

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

```sh
airdress-operator config [FLAGS]
```

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

```sh
# Print resolved config
airdress-operator config

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

## health

Check operator health and readiness.

```sh
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 |

```sh
airdress-operator health
airdress-operator health --url https://<your airdress address>
```

## status

Display operator status and metrics.

```sh
airdress-operator status
```

## dns

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

### dns add

Add a DNS record.

```sh
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 |

```sh
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.

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

```sh
# 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.

```sh
airdress-operator dns list
```

```text
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.

```sh
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.

```sh
airdress-operator postgres path
```

```text
./var/postgres
```

### postgres version

Print the PostgreSQL version requirement.

```sh
airdress-operator postgres version
```

```text
=18.3.0
```

### postgres url

Print the connection URL for the embedded or configured database.

```sh
airdress-operator postgres url
```

### postgres psql

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

```sh
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.

```sh
airdress-operator plugin-db init-key
```

```text
dGhpcyBpcyBhIDMyLWJ5dGUga2V5IGZvciBkZW1v...
```

**Caution:** The master key cannot be recovered if lost. Back it up immediately after generation.

## endpoint

Manage device endpoints enrolled with the operator.

### endpoint enroll

Enroll a new device endpoint.

```sh
airdress-operator endpoint enroll [FLAGS]
```

| Flag | Short | Env | Default | 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 |

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

### endpoint list

List enrolled endpoints.

```sh
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.

```sh
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.

```sh
airdress-operator chat pair [FLAGS]
```

| Flag | Short | Env | Default | 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.

```sh
airdress-operator ingress list
```

### ingress test

Send a test event to an inbound endpoint.

```sh
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 |

```sh
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.

```sh
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.

```sh
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.

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

### app list

List all installed apps for an airdress.

```sh
airdress-operator app list <AIRDRESS>
```

### app status

Show the status of a specific app.

```sh
airdress-operator app status <AIRDRESS> <SUBDOMAIN>
```

### app db-access

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

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

## federation

**Note:** Federation commands are feature-gated and may not be available in all builds.

Inspect and manage chat federation state.

### federation status

Show federation status.

```sh
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.

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

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

### federation rotate

Rotate federation keys for an airdress.

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

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

**Caution:** Key rotation invalidates existing federation sessions. All federated peers will need to re-establish connections.

## 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 |

**Tip:** Double underscores (`__`) in env var names map to nested config sections. For example, `AIRDRESS_AUTH__ISSUER` maps to the `[auth]` section's `issuer` field.

### 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) |

```sh
# 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
```

## See also

[Configuration](/reference/configuration/)
  [Quickstart](/getting-started/quickstart/)
  [Error Reference](/reference/errors/)