> Source: https://nexusatlas.dev/docs/cli — Nexus Atlas developer documentation (Reference). Converted from the HTML page; the page is canonical.

# CLI reference

One binary carries everything: `atlasd` is the daemon, the control CLI, the web server and the tooling. (Packaging installs a `nexus-atlasd` compatibility symlink beside it for older unit files.) Commands default to config `/etc/atlas/config.toml` and interface `nexus0` where those apply.

## Daily drivers

### `atlasd keygen`

Generate a Curve25519 keypair, base64-encoded — the node identity. The private key goes into this node's `[interface]`, the public key into every peer's `[[peer]]` block for it.

Example — the key lines are TOML-ready, paste them straight into configs

```
$ atlasd keygen

✓ Keypair generated (Curve25519)

  Private Key (keep secret)
  private_key = "4AiNx2P9vKq8mW3jR7hT5cL0dF6gY1bZ4nS8uE2oKEY="

  Public Key (share with peers)
  public_key  = "9XpQm4Wv7Jk2Rt8Ny5Bc1Hf3Zd6Ls0Ga9Ue7Iw2bQc="

  » Add these to your /etc/atlas/config.toml
  » Share only the public key with remote peers
```

### `atlasd run -c <config>`

The daemon itself. Under systemd, startup completes only when the TUN exists and every link is serviced (`Type=notify`) — "started" means the data path is up, not that the process exec'd.

Example — the log milestones that mean the tunnel is up

```
$ sudo atlasd run -c /etc/atlas/config.toml
…  handshake init from peer 1 processed, sending response
…  handshake complete with peer 1
…  all peer handshakes established
```

Under systemd, prefer the unit — start blocks until the data path is live

```
$ sudo systemctl start nexus-atlasd   # returns when TUN + links are serviced
```

### `atlasd status`

Freshness-checked digest of every daemon instance on the host: interface, address, strategy, links alive, peers established. The thirty-second answer to "is it running and is it healthy".

Example

```
$ atlasd status

  Nexus Atlas  v0.2.0

  nexus0  10.0.100.1/24  lowest_delivery_time  2/2 links alive  1 peer established
```

### `atlasd stats -i nexus0 -f pretty|json|json-pretty`

One-shot snapshot dump. The JSON forms are stable integration surfaces — the same document served at [/api/stats](https://nexusatlas.dev/docs/api).

Example — one link, machine-readable

```
$ atlasd stats -i nexus0 -f json | jq '.links[0]'
{
  "id": 0,
  "name": "wired",
  "bind_device": "eth0",
  "alive": true,
  "rtt_ms": 0.42,
  "jitter_ms": 0.05,
  "loss_pct": 0.0,
  "capacity_mbps": 100.0,
  "quality_score": 0.98,
  "tx_bytes": 104857,
  "rx_bytes": 99231
}
```

### `atlasd monitor -i nexus0 -r 500`

Live terminal dashboard, refresh in milliseconds. Keys: `q` quit, `g` sparklines, `p` pause. The fastest way to watch a failover happen.

### `atlasd web -i nexus0 -l 0.0.0.0:9800`

The [REST API](https://nexusatlas.dev/docs/api) and browser dashboard. Static UI assets are served from disk (`/opt/atlas/web`); without them the port is API-only.

Example — serve, then read the same snapshot the CLI sees

```
$ atlasd web -i nexus0 -l 0.0.0.0:9800 &

$ curl -s localhost:9800/api/stats | jq .strategy
"lowest_delivery_time"

$ curl -fsS localhost:9800/api/health >/dev/null && echo healthy
healthy
```

### `atlasd journal [-c category] [-s severity] [--since 30m] [--code link.down] [--follow] [--json]`

Read the persistent [event journal](https://nexusatlas.dev/docs/concepts/telemetry#journal); `--follow` tails it live, `--json` makes it a pipeline source. Default limit 50 entries, newest first.

Example — human view, then the same entry as a pipeline source

```
$ atlasd journal -c link -s warn --since 24h
2026-08-13 14:32:01  WARN   link.down                 link wired on nexus0 went down  reason=probe_timeout missed_probes=5
2026-08-13 14:31:42  WARN   link.quota_warn           link lte0 at 80% of monthly budget  used_pct=80

$ atlasd journal --json -n 1
{"v":1,"seq":891,"ts":1786297001,"category":"link","severity":"warn","code":"link.down","msg":"link wired on nexus0 went down","fields":{"reason":"probe_timeout","missed_probes":5}}
```

## Configuration tooling

### `atlasd config check [-c path] [--json]`

The daemon's exact load pipeline without starting the engine. Exit 0 = loadable (warnings allowed), exit 1 = the daemon would refuse to start. `--json` emits `{ok, findings:[{fatal, path, message}]}` for CI gates.

Example — the three verdicts, and the exit code CI cares about

```
$ atlasd config check -c node-a.toml
✓ node-a.toml is valid

$ atlasd config check -c tuned.toml
✓ tuned.toml is loadable (2 warnings)

$ atlasd config check -c broken.toml
✗ broken.toml has fatal errors — the daemon would refuse to start
$ echo $?
1
```

### `atlasd config schema`

Print the config JSON Schema (draft-07), generated from the daemon's own structs. Point a `#:schema` header at it and a TOML-aware editor autocompletes and validates as you type; the [configuration reference](https://nexusatlas.dev/docs/config) is generated from the same document.

Example

```
$ atlasd config schema | head -6
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Nexus Atlas config",
  "type": "object",
  "required": ["interface", "link"],
  "properties": {

$ atlasd config schema > config.schema.json   # then: #:schema ./config.schema.json
```

### `atlasd config node-token`

Print the time-windowed mesh read token for the `X-Atlas-Node-Token` header — bare token to stdout, scope and validity to stderr, so it pipes cleanly into scripts.

Example — annotations go to stderr; only the token reaches stdout

```
$ atlasd config node-token
  Scope  GET /api/config, GET /api/stats — no writes, no session
  Valid  another 4m 12s (5-minute windows — mint again after that)

9y1uTq83KfWv2mDplRcxJ7hNbA5eZsG0

  » Read a locked-down mesh member over the tunnel:
    $ curl -H "X-Atlas-Node-Token: $(atlasd config node-token)" \
           http://10.0.100.2:9800/api/stats
```

### `atlasd config keygen-author [--out path]`

Generate the Ed25519 author keypair that signs fleet configuration epochs (written mode 0600).

### `atlasd config sign-epoch --policy <file> --epoch <n> [--confirm-secs 90] [--target-roles a,b]`

Sign a policy TOML into a distributable config epoch offline, with optional role/node targeting (selectors intersect) and the commit-confirm window baked in.

### `atlasd config wizard`

Offline provisioning-bundle authoring shell. Binds loopback only by default — it deliberately has no auth of its own.

## Dashboard accounts & tokens

### `atlasd web adduser|passwd|deluser|list-users`

Dashboard account management — argon2id at rest, sessions as signed cookies. Create accounts before exposing `:9800` beyond localhost.

### `atlasd web remove-passkey`

The break-glass path when a hardware security key is lost — removes a passkey from an account so password sign-in works again.

### `atlasd web token add ci --scope read|write [--expires 30d]`

Mint an API token for automation; the secret is printed exactly once. `token list` and `token revoke` manage the set; scopes are documented in the [API reference](https://nexusatlas.dev/docs/api#machine-credentials).

Example — the secret appears exactly once, on stdout

```
$ atlasd web token add ci --scope read --expires 30d
atlas_kQ3nX8vLw2Jm7RfT5cYp0dHb4gZs9uEaIo6WqBNVkPr

$ atlasd web token list
  ci  atlas_kQ3n  read  created_at=1786295400 by=admin expires=1788887400 last_used=never
```

## Diagnostics & support

### `atlasd support-bundle -i nexus0 [-o file.zip] [--no-crashes]`

One redacted zip: config (secrets stripped by allowlist), stats, health, journal tail, scheduler log, netcheck, QoS state, versions, crash spool. It prints every redaction it performed — private keys cannot leave by accident.

### `atlasd crash list|show|export|purge [<id>]`

The local crash spool — capture is on by default, and reports stay on the node until an operator acts. IDs match by unique prefix; `export` writes a signed zip for manual handling.

### `atlasd crash send <id> [--anonymous|--attributed]`

Explicit, per-report upload to the console. Anonymous mode strips identity *and* forces redaction; background auto-send exists but is off by default.

### `atlasd enroll <code>`

Enroll this node into a hosted console account, with proof-of-possession of the node key. The only way a node ever becomes console-connected.

## Patterns worth stealing

```
# CI gate: fail the pipeline when a config would not load
atlasd config check -c deploy/node-a.toml --json | jq -e '.ok'

# Yesterday's link flaps, machine-readable
atlasd journal -c link -s warn --since 24h --json

# Watch a failover as it happens
atlasd monitor -i nexus0 -r 250

# Print the schema your editor should validate against
atlasd config schema > config.schema.json
```