gradatum-admin 0.0.2

CLI ops — init/migrate/backup/restore + vault lifecycle + api-key management (Auth Path 2, alpha.5)
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

# gradatum-admin

> Operator CLI for Gradatum: bootstrap, migration, backup/restore, vault lifecycle, and API-key management (Auth Path 2 — alpha.5).

**Status** : Alpha — placeholder `v0.0.2`. Phase 2.0c-bis Auth Path 2 LIVE 2026-05-07 (git tag `v0.1.0-alpha.5`). Source code private until `v1.0` public release per D5 criterion. See [gradatum.org](https://gradatum.org).

**Part of [`gradatum`](https://crates.io/crates/gradatum)** — Memory backbone for AI agents.

## Subcommands

### init

Bootstrap a Gradatum root directory.

```
gradatum-admin init --preset hierarchical --root /var/lib/gradatum
gradatum-admin init --root /var/lib/gradatum --force   # re-init (idempotent)
```

Generates:
- `db/jwt_ed25519.key` / `db/jwt_ed25519.pub` (Ed25519 keypair, chmod 600/644)
- `db/admin_bearer.txt` (auto-generated admin token, chmod 600 — displayed once)
- `config.toml` (default server configuration with absolute paths)
- `db/queue.sqlite` (SQLite queue)
- `db/api_keys.db` (SQLite API key store)
- `db/revocation.db` (SQLite revocation store)
- `acl/hierarchical.toml` / `acl/flat.toml` (embedded ACL presets)

### api-key (Auth Path 2 — alpha.5)

```
gradatum-admin api-key create --owner <consumer_id> [--scopes read,write] [--tenant main] [--desc "CI agent"]
gradatum-admin api-key list   [--owner <consumer_id>]
gradatum-admin api-key revoke --prefix ak_<prefix>
gradatum-admin api-key rotate --prefix ak_<prefix>
```

Output of `create`: the full key `ak_<prefix><secret>` printed ONCE (D8 — no re-display).
Rotation is atomic (old key revoked + new key created in a single SQLite transaction).

### token (Path 3 minimal — alpha.5)

```
gradatum-admin token issue --sub <consumer_id> --scopes read --tenant main [--ttl-secs 3600]
```

Direct JWT issuance (operator use only — bypasses API key flow).

### vault

```
gradatum-admin vault create <name>
gradatum-admin vault list
gradatum-admin vault swap <from> <to>
gradatum-admin vault delete <name> [--confirm]
```

### migrate

```
gradatum-admin migrate --from v0.x --to v0.1 --root /var/lib/gradatum
```

### backup / restore

```
gradatum-admin backup --root /var/lib/gradatum --output /backup/gradatum-$(date +%Y%m%d).tar.gz
gradatum-admin restore --input /backup/gradatum-20260504.tar.gz --root /var/lib/gradatum
```

## ACL Presets

| Preset | Description |
|---|---|
| `hierarchical` | Recommended — section-based RBAC with personal-classified guard |
| `flat` | All authenticated consumers: read + write (no section granularity) |
| `strict` | Explicit whitelist per consumer per section |

## Installation (LXC 500 — alpha.5)

```bash
bash scripts/install-lxc500.sh
```

Creates user `gradatum` (UID 985), installs binaries + systemd units + packaging.

## Documentation

- Project : <https://gradatum.org>
- Source : private until v1.0
- Roadmap : Phase 2.0c-bis (alpha.5 LIVE) → Phase 2.1 `v0.1.0-rc.1` → `v0.1.0` public
- License : Apache-2.0