auberge 0.14.25

CLI tool for managing self-hosted infrastructure with Ansible
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

# auberge versions

Report every version pin the repo declares, per [ADR-0017](https://github.com/sripwoud/auberge/blob/master/meta/adr/0017-app-versions-declared-in-playbook-meta.md): the App Version from each app's Playbook Meta (`ansible/playbooks/<app>.meta.yml`), and the Tool Versions from `# renovate:` annotations in role defaults (`ansible/roles/<role>/defaults/main.yml`) — `lego`, `uv`, Caddy's plugins. Alias: `auberge v`.

```bash
auberge versions [OPTIONS]
```

DECLARED is the repo's declaration, read from the binary's embedded asset tree — not what any host currently runs. The default run is fully offline.

## Options

| Option                | Description                                                                               | Default |
| --------------------- | ----------------------------------------------------------------------------------------- | ------- |
| `--check-upstream`    | Query each pin's datasource for the latest stable release; adds LATEST and STATUS columns | `false` |
| `-o, --output FORMAT` | `human` or `json`                                                                         | `human` |

## Output

Default — App and Tool Versions stay distinct sections, keeping the ADR-0017 split visible:

```
App Versions
┌────────────┬────────────┐
│ APP        │ DECLARED   │
├────────────┼────────────┤
│ actual     │ 26.8.0     │
├────────────┼────────────┤
│ …          │ …          │
└────────────┴────────────┘

Tool Versions
┌────────┬───────────────────┬──────────┐
│ ROLE   │ TOOL              │ DECLARED │
├────────┼───────────────────┼──────────┤
│ blocky │ lego              │ 5.3.1    │
├────────┼───────────────────┼──────────┤
│ caddy  │ cloudflare_plugin │ v0.2.4   │
├────────┼───────────────────┼──────────┤
│ …      │ …                 │ …        │
└────────┴───────────────────┴──────────┘
```

ROLE/TOOL come from the pinned variable: `blocky_lego_version` reports as role `blocky`, tool `lego`.

With `--check-upstream`, each pin's declared datasource (`npm` registry, GitHub releases, or the Go module proxy for `datasource=go`) is queried:

```
App Versions
┌────────────┬────────────┬───────────┬─────────┐
│ APP        │ DECLARED   │ LATEST    │ STATUS  │
├────────────┼────────────┼───────────┼─────────┤
│ actual     │ 26.8.0     │ 26.8.1    │ behind  │
├────────────┼────────────┼───────────┼─────────┤
│ headscale  │ 0.25.1     │ 0.29.3    │ behind  │
├────────────┼────────────┼───────────┼─────────┤
│ …          │ …          │ …         │ …       │
└────────────┴────────────┴───────────┴─────────┘

Tool Versions
┌────────┬──────┬──────────┬────────┬─────────┐
│ ROLE   │ TOOL │ DECLARED │ LATEST │ STATUS  │
├────────┼──────┼──────────┼────────┼─────────┤
│ blocky │ lego │ 5.3.1    │ 5.3.1  │ current │
├────────┼──────┼──────────┼────────┼─────────┤
│ …      │ …    │ …        │ …      │ …       │
└────────┴──────┴──────────┴────────┴─────────┘
```

| Status    | Meaning                                                                                                     |
| --------- | ----------------------------------------------------------------------------------------------------------- |
| `current` | Declared >= latest                                                                                          |
| `behind`  | Upstream has a newer stable release                                                                         |
| `unknown` | Either side is not version-shaped (e.g. non-numeric) — mirrors Renovate, which skips values it cannot parse |

Upstream semantics mirror Renovate's. `github-releases`: newest non-draft, non-prerelease release whose tag yields a version — a hyphenated suffix (`2.0.1-alpha.1`) counts as prerelease even when GitHub doesn't flag it, and `extractVersion` regexes filter monorepo tags. `go`: newest stable version the module proxy lists under `@v/list`.

## Exit codes

Follow the Backup Verdict convention so a cron can branch on drift:

| Code | Meaning                                                                 |
| ---- | ----------------------------------------------------------------------- |
| `0`  | Every pin `current` (or no upstream check requested and read succeeded) |
| `1`  | At least one App or Tool Version `behind`                               |
| `2`  | Operational error                                                       |

`unknown` drift does not fail the gate:

```bash
auberge versions --check-upstream || notify "version pins drifted"
```

## JSON output

```bash
auberge versions --check-upstream -o json
```

```json
{
  "checked_upstream": true,
  "apps": [
    {
      "app": "actual",
      "declared": "26.8.0",
      "latest": "26.8.0",
      "status": "current"
    }
  ],
  "tools": [
    {
      "role": "blocky",
      "tool": "lego",
      "declared": "5.3.1",
      "latest": "5.3.1",
      "status": "current"
    }
  ]
}
```

`latest` and `status` are omitted without `--check-upstream`.

?> Set the `GITHUB_TOKEN` env var to authenticate GitHub API calls with `--check-upstream` and avoid anonymous rate limits.