The ridm command line

ridm is the command-line administration tool, built from crates/ridm-cli. Every command except bootstrap is a client of the admin API: it resolves a server URL, a tenant and a bearer token, sends one or two requests, and prints either a readable summary or the server’s JSON. It needs nothing but network access to the server and a token.

Each release ships a static ridm for linux amd64 and arm64 (Releases and verification). To build it from the repository:

cargo build --release -p ridm-cli        # target/release/ridm
cargo run -p ridm-cli -- --help          # while developing

bootstrap links the server library and talks to the database directly. Build with --no-default-features for a slim, HTTP-only ridm without it; bootstrapping is then left to ridm-api bootstrap in the server container.

cargo build --release -p ridm-cli --no-default-features

A first session

ridm login --url https://id.example.com             # paste a personal access token
ridm whoami

ridm --tenant acme tenant export -o acme.json        # configuration as code
ridm --tenant acme tenant diff   -f acme.json        # what an import would change
ridm --tenant acme tenant import -f acme.json        # plan, confirm, apply

ridm --tenant acme key rotate
ridm --tenant acme user create alice --email alice@example.com --temporary-password
ridm --tenant acme user reset alice --revoke-sessions
ridm --tenant acme client create --name "Acme SPA" --type spa \
     --redirect-uri https://app.acme.example/callback
ridm master-key status

Global flags

These work with every command, before or after the subcommand.

ridm --version prints the version; ridm help <command> or --help on any command prints its flags.

The CLI also reads a .env file in the working directory at start-up, so RIDM_URL and RIDM_TOKEN (and, for bootstrap, the server’s own variables) may live there.

Profiles and the config file

ridm login writes the server URL, the tenant and the credential to a profile. All profiles live in one JSON file:

1. $RIDM_CONFIG, when set;
2. else $XDG_CONFIG_HOME/ridm/config.json;
3. else ~/.config/ridm/config.json.

The file is written with mode 0600, because a profile may hold a personal access token, a refresh token or a client secret. Nothing is written until ridm login runs: --url and --token (or RIDM_URL and RIDM_TOKEN) are enough on their own for a one-off command or a pipeline, and never touch the file.

{
  "current": "prod",
  "profiles": {
    "prod": {
      "url": "https://id.example.com",
      "tenant": "master",
      "credential": { "kind": "token", "token": "rpat_…" }
    }
  }
}

The first profile stored becomes the selected one. A profile’s tenant is the tenant its credential belongs to and the default target of commands; --tenant acts on another tenant with the same credential, which works only for a global administrator (see Administrator access).

An OAuth credential ("kind": "oauth") is renewed in place about a minute before the access token expires: with the refresh token while one lasts, else, for a confidential client, with the stored secret. The renewed credential is written back so the next command reuses it.

Authenticating

An admin token must carry urn:ridm:admin in aud and belong to a user (or a machine client’s service-account user) holding at least one ridm:* permission, so the CLI always asks for that resource. ridm login has three routes:

ridm login checks the credential against GET /admin/me before storing it, and refuses to store one that does not get through.

• Personal access token. Mint one in the account console under Security → personal access tokens, choosing the admin permissions it carries (see Personal access tokens). In CI, put it in RIDM_TOKEN and skip login.
• Client credentials. The client needs the client_credentials grant, urn:ridm:admin in its allowed_audiences, and a service account holding admin roles. With --client-id and neither --client-secret-stdin nor --device, the secret is prompted for.
• Device grant. The tenant must offer the device endpoint, and the client must allow urn:ietf:params:oauth:grant-type:device_code and list urn:ridm:admin in its audiences. The CLI prints a URL and a code and polls until the code is approved, gives up after the code expires or fifteen minutes, whichever is sooner. The built-in console clients deliberately do not allow this grant; register a device client for it.

# CI: a token from the secret store, no profile file at all
export RIDM_URL=https://id.example.com RIDM_TOKEN="$RIDM_ADMIN_TOKEN"
ridm --tenant acme tenant diff -f acme.json --exit-code

# a stored profile authenticated as a machine client
printf '%s' "$CLIENT_SECRET" | ridm login --url https://id.example.com \
  --name ops --client-id ops-automation --client-secret-stdin

Commands

login, logout, whoami, profile

bootstrap

Creates the first global administrator. See Bootstrap below.

tenant

[SLUG] defaults to the tenant from --tenant or the profile.

import shows the plan, with any items the server would refuse (for example a role granting admin permissions you do not hold yourself), and asks before applying; --yes skips the question and is required when stdin is not a terminal. --prune also deletes configuration the document does not mention. An import that reports per-item errors exits 1 after printing them; secrets of clients and webhooks it created are printed once. diff prints the plan and fails with exit 1 when the dry run reports items that would be refused (not with --output json, which prints the plan as it arrived); otherwise diff --exit-code exits 3 when the plan is not empty. The document format is described in Tenant configuration document, and the workflow in Configuration as code.

key and master-key

The master-key commands need a global administrator. See Rotating keys.

audit

verify prints Intact: N rows (seq A–B), ending on <hash> and exits 0, or names the first row that doesn’t hash or link and exits 1. Keep the hash: passing it as --head later proves the chain was not cut off or rewritten since. See Checking an export yourself.

user

USER is a user id, a username or an email address. A name that is not a UUID is looked up through the user search and must match exactly one account, so a typo never resets somebody else’s password. Without --password-stdin, reset generates a temporary password and prints it once; either way the user must change it at the next sign-in unless --no-must-change is given. create without a password flag makes an account with no password (the user can recover one through the reset flow, or sign in another way the tenant offers).

client

Anything not given takes the server’s type-driven defaults; --grant and --scope left out mean “the defaults for this type”, not “none”. A confidential client’s secret is printed once. private_key_jwt needs a JWKS, which the CLI cannot set: create the client in the console or through the API instead.

client iat manages the initial access tokens that dynamic client registration demands when the tenant’s dcr.mode is initial_access_token. See Registering clients.

Output

Without --output json, results are aligned tables and short sentences on stdout; prompts, progress and “shown once” notes go to stderr, so ridm … > file captures only the result. With --output json, the API’s response is printed as it arrived.

Errors from the admin API are printed from their RFC 9457 problem document, with per-field messages on their own lines:

ridm: POST https://id.example.com/admin/tenants/acme/clients → 400 Bad Request: unknown scope(s): billing

Exit codes

Bootstrap

A new deployment has a master tenant and no administrator. ridm bootstrap creates the first global administrator, a user in master holding the built-in ridm:owner role. It cannot use the admin API, because no token can exist yet, so it reads the server’s own environment (DATABASE_URL, REDIS_URL, MASTER_KEY and the rest; see Server configuration) and runs the same code as the server’s own ridm-api bootstrap and its start-up bootstrap from BOOTSTRAP_ADMIN_EMAIL and BOOTSTRAP_ADMIN_PASSWORD.

Unlike ridm-api bootstrap, which migrates only when MIGRATE_ON_START=true, ridm bootstrap applies pending migrations first unless --no-migrate is given. That needs a DATABASE_URL whose role owns the schema; against the DML-only app role, run ridm-api migrate as the migrator beforehand and pass --no-migrate. It does not create the BOOTSTRAP_SAMPLE_CLIENT sample client; the server does that.

source .env     # the server's DATABASE_URL, REDIS_URL, MASTER_KEY, PUBLIC_URL, ...
printf '%s' 'a-long-passphrase' | ridm bootstrap --email admin@example.com --password-stdin

• It is idempotent: once any live user in master holds ridm:owner, it changes nothing and says so.
• The password must satisfy the master tenant’s password policy (twelve characters by default); a refused password leaves nothing half-created.
• The administrator must change the password at the first sign-in unless --no-must-change is given.

Then sign in to the admin console through master, mint a personal access token in the account console, and run ridm login --url <server URL>.

A token without a browser

--issue-token NAME also mints a personal access token for the administrator named by --username (default admin, or BOOTSTRAP_ADMIN_USERNAME), carrying every admin permission that user holds and expiring after --token-days (30 by default, and at most the master tenant’s personal_token_max_days). The token is printed alone on stdout, everything else goes to stderr, so a script can capture it:

RIDM_TOKEN=$(ridm bootstrap --no-migrate --issue-token ci-setup --token-days 1)

It works on an already-bootstrapped database too — then it creates nothing and needs no password, only the user to mint for. It is meant for development stacks and automated setup: anyone who holds DATABASE_URL and MASTER_KEY already controls every tenant, so it grants nothing new, but the token is as powerful as the administrator. It is recorded in the audit log as a token created by the system, and appears in the administrator’s account console where it can be revoked.