Admin CLI (`ahdapactl`)

ahdapactl is the command-line administration tool for ahdapa. It stores named session credentials in ~/.config/ahdapactl/sessions.toml (mode 0600) and sends authenticated requests to the admin API on one or more nodes.

Installation

From the RPM package

When ahdapa is installed from the RPM, ahdapactl is included automatically:

Binary: /usr/bin/ahdapactl
Man page: /usr/share/man/man1/ahdapactl.1.gz

No additional steps are needed.

From source

ahdapactl is built as part of the ahdapa workspace:

cargo build --release -p ahdapactl
# Binary: target/release/ahdapactl

Copy it to a directory in your $PATH (e.g. /usr/local/bin/ahdapactl).

Authentication

ahdapactl supports two authentication methods:

Kerberos SPNEGO — uses the ambient Kerberos ticket cache (kinit must have been run beforehand). Selected automatically when a valid TGT is present; forced with --kerberos.
Password — prompts for a password and calls POST /api/auth/login. Selected automatically when Kerberos is unavailable; forced with --password.

When neither flag is given, ahdapactl login tries Kerberos first and falls back to password if it fails.

Global flags

Flag	Description
`--node <ALIAS>`	Use the session stored under this alias instead of the default.
`--url <URL>`	Override the node URL for this one invocation (does not save).
`--insecure`	Accept any TLS certificate (development only).
`--ca-cert <PATH>`	Path to a CA certificate PEM file for TLS verification.

Session management

Authenticate to the node at <url> and store the session.

ahdapactl login https://idp.example.com
ahdapactl login https://node1.example.com --name node1
ahdapactl login https://node2.example.com --name node2 --kerberos
ahdapactl login https://node3.example.com --name node3 --password --user admin

Flag	Description
`--name <ALIAS>`	Alias for this session (default: short hostname label).
`--kerberos`	Force Kerberos authentication.
`--password`	Force password authentication.
`-u`, `--user <USER>`	Username for password auth (default: `$USER`).

The first session saved becomes the default.

`ahdapactl logout [alias]`

Remove a stored session. Defaults to the current default session.

`ahdapactl use <alias>`

Set the default session alias.

`ahdapactl status`

List all stored sessions with their URL, auth method, and expiry time. The active default is marked with *.

Cluster management

`ahdapactl cluster bootstrap <url>...`

Bootstrap a new cluster by automating the 5-step key-alignment procedure:

Log in to every listed node.
Generate a random 32-byte cluster wrapping key (or use --key to supply one).
Push the key to every node via PUT /api/admin/keys/cluster.
Re-authenticate to every node (sessions are now sealed under the shared key).
Save all new sessions.

ahdapactl cluster bootstrap \
  https://node1.example.com:8080 \
  https://node2.example.com:8080 \
  https://node3.example.com:8080

The generated wrapping key is printed to stdout. Store it securely — it cannot be recovered from the server.

Flag	Description
`-u`, `--user <USER>`	Username for password auth.
`--name <PREFIX>`	Alias prefix for generated session names (e.g. `--name prod` → `prod-node1`).
`--key <BASE64URL>`	Existing base64url-encoded 32-byte key to use instead of generating one.
`--kerberos`	Force Kerberos auth for all nodes.
`--password`	Force password auth for all nodes.

After bootstrap, verify gossip convergence with ahdapactl cluster status and the curl check from Provisioning a fresh cluster.

`ahdapactl cluster status`

Show the current cluster wrapping key UUID and the list of registered nodes with their KEM, signing-key, and wrapping-key recipient status.

`ahdapactl cluster key show`

Print the cluster wrapping key metadata (UUID and rotation timestamp).

`ahdapactl cluster key rotate [BASE64URL]`

Rotate the cluster wrapping key. Generates a new random key if no argument is given. Prints the new key to stdout — store it securely.

`ahdapactl cluster nodes list`

List all registered cluster nodes and their gossip key enrollment status.

`ahdapactl cluster nodes seed`

Manually seed a node’s ML-KEM-768 public key (and optionally gossip signing key) via the admin API. Used in static-peer deployments when automatic Kerberos-based self-registration is not available.

ahdapactl cluster nodes seed \
  --node-id node2.example.com \
  --kem-key <BASE64URL-DER> \
  [--signing-key <BASE64URL-DER>]

The key values can be obtained from GET /api/gossip/kem-info on the target node.

JWT signing key management

`ahdapactl keys list`

List all JWT signing keys registered on the node.

`ahdapactl keys rotate`

Rotate the JWT signing key. The new key is generated server-side using the algorithm configured by [server] jwt_signing_algorithm. The old public key remains in the CRDT so that tokens minted before the rotation are still verifiable until they expire.

ahdapactl clients create \
  --name "My Application" \
  --redirect-uris https://app.example.com/callback \
  --scopes openid,profile,email \
  [--auth-method private_key_jwt] \
  [--jwks-uri https://app.example.com/.well-known/jwks.json]

Flag	Description
`--name <NAME>`	Human-readable client name (required).
`--redirect-uris <URL,...>`	Comma-separated allowed redirect URIs.
`--scopes <SCOPE,...>`	Comma-separated allowed scopes.
`--auth-method <METHOD>`	Token endpoint auth method (default: `private_key_jwt`).
`--secret <SECRET>`	Pre-shared secret for `client_secret_*` methods.
`--grant-types <TYPE,...>`	Comma-separated allowed grant types.
`--jwks-uri <URL>`	JWKS endpoint for `private_key_jwt`.

ahdapactl scopes update profile \
  --description "Basic profile claims" \
  --claims name,given_name,family_name,email

ahdapactl audit list
ahdapactl audit list --offset 50

Examples

Bootstrap a three-node cluster with Kerberos:

ahdapactl cluster bootstrap --kerberos \
  https://ipa1.example.com/idp \
  https://ipa2.example.com/idp \
  https://ipa3.example.com/idp

Register a confidential client:

ahdapactl login https://idp.example.com
ahdapactl clients create \
  --name "Internal API" \
  --scopes openid,profile \
  --auth-method client_secret_basic \
  --secret "$(openssl rand -base64 32)"

Rotate the JWT signing key on all nodes (multi-node cluster):

for alias in node1 node2 node3; do
  ahdapactl --node "$alias" keys rotate
done

Ahdapa documentation

Admin CLI (`ahdapactl`)

Installation

From the RPM package

From source

Authentication

Global flags

Session management

`ahdapactl logout [alias]`

`ahdapactl use <alias>`

`ahdapactl status`

Cluster management

`ahdapactl cluster bootstrap <url>...`

`ahdapactl cluster status`

`ahdapactl cluster key show`

`ahdapactl cluster key rotate [BASE64URL]`

`ahdapactl cluster nodes list`

`ahdapactl cluster nodes seed`

JWT signing key management

`ahdapactl keys list`

`ahdapactl keys rotate`

`ahdapactl keys delete <kid>`

OAuth2 client management

`ahdapactl clients list`

`ahdapactl clients show <id>`

`ahdapactl clients create`

`ahdapactl clients delete <id>`

User and group inspection

`ahdapactl users list`

`ahdapactl users show <username>`

`ahdapactl users groups`

`ahdapactl users group <name>`

Scope management

`ahdapactl scopes list`

`ahdapactl scopes update <name>`

`ahdapactl scopes delete <name>`

Audit log

`ahdapactl audit list`

Examples

Keyboard shortcuts

Ahdapa documentation