Installing the command-line executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install gradatum-admin

It will make the gradatum-admin command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall gradatum-admin uninstalls.

Back to the crate overview.

Readme

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.

Part of 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 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