.Dd March 11, 2026 .Dt MCIASDB 1 .Os .Sh NAME .Nm mciasdb .Nd MCIAS database maintenance tool .Sh SYNOPSIS .Nm .Op Fl config Ar path .Ar command .Op Ar subcommand .Op Ar flags .Sh DESCRIPTION .Nm is the MCIAS database maintenance tool. It operates .Em directly on the SQLite database file, bypassing the mciassrv REST API. .Pp Use .Nm for: .Bl -bullet -compact .It Break-glass recovery when the server is unavailable. .It Offline account and role management before first server start. .It Schema verification and migration. .It Token pruning and audit log inspection. .El .Pp .Nm requires the same master key configuration as .Xr mciassrv 1 to decrypt secrets at rest. .Sh TRUST MODEL AND SAFETY WARNINGS .Nm has .Em direct write access to the database and can modify any record without going through the server's validation logic. Use it only when necessary. .Bl -bullet .It Run .Nm on the same host as the database file. Never copy the database to an untrusted host. .It The master key passphrase (or keyfile) must be available. Set the environment variable named by .Sy passphrase_env in the config, or ensure the keyfile is accessible. .It All write operations append an audit log entry tagged .Qq actor:mciasdb . .It Avoid running .Nm while mciassrv is under heavy write load; SQLite WAL mode provides some isolation, but schema migrations acquire an exclusive lock. .El .Sh OPTIONS .Bl -tag -width Ds .It Fl config Ar path Path to the TOML configuration file. Defaults to .Pa mcias.toml in the current directory. .El .Sh COMMANDS .Ss schema .Bl -tag -width Ds .It Nm Ic schema Ic verify Reports the current schema version. Exits 0 if the schema is up to date; exits 1 if migrations are pending. .It Nm Ic schema Ic migrate Applies any pending migrations and reports each one applied. Exits 0 on success. .El .Ss account .Bl -tag -width Ds .It Nm Ic account Ic list Prints UUID, username, type, and status for all accounts. .It Nm Ic account Ic get Fl -id Ar uuid Prints the account record for the given UUID. .It Nm Ic account Ic create Fl -username Ar name Fl -type Ar human|system Inserts a new account row and prints the new UUID. .It Nm Ic account Ic set-password Fl -id Ar uuid Prompts for a new password twice (confirmation). Re-hashes with Argon2id and updates the row. No .Fl -password flag is provided; the password is always read interactively. .It Nm Ic account Ic set-status Fl -id Ar uuid Fl -status Ar STATUS Updates the account status. Valid statuses: .Qq active , .Qq inactive , .Qq deleted . .It Nm Ic account Ic reset-totp Fl -id Ar uuid Clears the TOTP secret and disables TOTP for the account. The user will be able to log in with password only until they re-enrol. .El .Ss role .Bl -tag -width Ds .It Nm Ic role Ic list Fl -id Ar uuid Prints the roles assigned to the account. .It Nm Ic role Ic grant Fl -id Ar uuid Fl -role Ar role Adds a role to the account. .It Nm Ic role Ic revoke Fl -id Ar uuid Fl -role Ar role Removes a role from the account. .El .Ss token .Bl -tag -width Ds .It Nm Ic token Ic list Fl -id Ar uuid Prints JTI, issued_at, expires_at, and revoked_at for all tokens associated with the account. .It Nm Ic token Ic revoke Fl -jti Ar jti Sets revoked_at to the current time on the specified token row. .It Nm Ic token Ic revoke-all Fl -id Ar uuid Revokes all non-revoked tokens for the account. A no-op (exits 0) if no active tokens exist. .El .Ss prune .Bl -tag -width Ds .It Nm Ic prune Ic tokens Deletes rows from the token_revocation table where expires_at is in the past. Prints the number of rows removed. .El .Ss audit .Bl -tag -width Ds .It Nm Ic audit Ic tail Op Fl -n Ar N Prints the last N audit events, newest last. Default: 50. .It Nm Ic audit Ic query Op Fl -account Ar uuid Op Fl -type Ar event_type Op Fl -since Ar timestamp Op Fl -json Queries the audit log. Filters are combinable (AND semantics). .Fl -since accepts an RFC 3339 timestamp. .Fl -json emits newline-delimited JSON instead of tabular output. .El .Ss pgcreds .Bl -tag -width Ds .It Nm Ic pgcreds Ic get Fl -id Ar uuid Decrypts and prints the Postgres credentials for the account. A warning header is printed before the output because the password is displayed in plaintext. .It Nm Ic pgcreds Ic set Fl -id Ar uuid Fl -host Ar host Fl -port Ar port Fl -db Ar db Fl -user Ar user Prompts for the Postgres password interactively (no .Fl -password flag). Encrypts with AES-256-GCM using the master key and stores the record. .El .Sh EXAMPLES Verify schema after upgrade: .Bd -literal -offset indent MCIAS_MASTER_PASSPHRASE=... mciasdb --config /etc/mcias/mcias.conf schema verify .Ed .Pp Create an admin account before first server start: .Bd -literal -offset indent MCIAS_MASTER_PASSPHRASE=... mciasdb --config /etc/mcias/mcias.conf \\ account create --username admin --type human MCIAS_MASTER_PASSPHRASE=... mciasdb --config /etc/mcias/mcias.conf \\ account set-password --id MCIAS_MASTER_PASSPHRASE=... mciasdb --config /etc/mcias/mcias.conf \\ role grant --id --role admin .Ed .Pp Tail the last 20 audit events: .Bd -literal -offset indent MCIAS_MASTER_PASSPHRASE=... mciasdb --config /etc/mcias/mcias.conf \\ audit tail --n 20 .Ed .Sh ENVIRONMENT The environment variable named by .Sy passphrase_env in the configuration file must be set to the master key passphrase, unless .Sy keyfile is used instead. .Pp Example (with default config): .Bd -literal -offset indent export MCIAS_MASTER_PASSPHRASE=your-passphrase mciasdb --config /etc/mcias/mcias.conf account list .Ed .Sh EXIT STATUS .Ex -std .Sh FILES .Bl -tag -width Ds .It Pa /etc/mcias/mcias.conf Default configuration file location. .It Pa /var/lib/mcias/mcias.db SQLite database. .El .Sh SEE ALSO .Xr mciassrv 1 , .Xr mciasctl 1 , .Xr mciasgrpcctl 1