MCIASDB(1)

NAME
mciasdb - MCIAS database maintenance tool

SYNOPSIS
mciasdb [-config path] command [subcommand] [flags]

DESCRIPTION
mciasdb is the MCIAS database maintenance tool. It operates directly on the SQLite database file, bypassing the mciassrv REST API.

Use mciasdb for:
•   Break-glass recovery when the server is unavailable.
•   Offline account and role management before first server start.
•   Schema verification and migration.
•   Token pruning and audit log inspection.

mciasdb requires the same master key configuration as mciassrv(1) to decrypt secrets at rest.

TRUST MODEL AND SAFETY WARNINGS
mciasdb has direct write access to the database and can modify any record without going through the server's validation logic. Use it only when necessary.

•   Run mciasdb on the same host as the database file. Never copy the database to an untrusted host.

•   The master key passphrase (or keyfile) must be available. Set the environment variable named by passphrase_env in the config, or ensure the keyfile is accessible.

•   All write operations append an audit log entry tagged "actor:mciasdb".

•   Avoid running mciasdb while mciassrv is under heavy write load; SQLite WAL mode provides some isolation, but schema migrations acquire an exclusive lock.

OPTIONS

-config path
    Path to the TOML configuration file. Defaults to mcias.toml in the current directory.

COMMANDS

  schema

mciasdb schema verify
    Reports the current schema version. Exits 0 if the schema is up to date; exits 1 if migrations are pending.

mciasdb schema migrate
    Applies any pending migrations and reports each one applied. Exits 0 on success.

  account

mciasdb account list
    Prints UUID, username, type, and status for all accounts.

mciasdb account get --id uuid
    Prints the account record for the given UUID.

mciasdb account create --username name --type human|system
    Inserts a new account row and prints the new UUID.

mciasdb account set-password --id uuid
    Prompts for a new password twice (confirmation). Re-hashes with Argon2id and updates the row. No --password flag is provided; the password is always read interactively.

mciasdb account set-status --id uuid --status STATUS
    Updates the account status. Valid statuses: "active", "inactive", "deleted".

mciasdb account reset-totp --id 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.

  role

mciasdb role list --id uuid
    Prints the roles assigned to the account.

mciasdb role grant --id uuid --role role
    Adds a role to the account.

mciasdb role revoke --id uuid --role role
    Removes a role from the account.

  token

mciasdb token list --id uuid
    Prints JTI, issued_at, expires_at, and revoked_at for all tokens associated with the account.

mciasdb token revoke --jti jti
    Sets revoked_at to the current time on the specified token row.

mciasdb token revoke-all --id uuid
    Revokes all non-revoked tokens for the account. A no-op (exits 0) if no active tokens exist.

  prune

mciasdb prune tokens
    Deletes rows from the token_revocation table where expires_at is in the past. Prints the number of rows removed.

  audit

mciasdb audit tail [--n N]
    Prints the last N audit events, newest last. Default: 50.

mciasdb audit query [--account uuid [--type event_type [--since timestamp [--json]]]]
    Queries the audit log. Filters are combinable (AND semantics). --since accepts an RFC 3339 timestamp. --json emits newline-delimited JSON instead of tabular output.

  pgcreds

mciasdb pgcreds get --id 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.

mciasdb pgcreds set --id uuid --host host --port port --db db --user user
    Prompts for the Postgres password interactively (no --password flag). Encrypts with AES-256-GCM using the master key and stores the record.

EXAMPLES
Verify schema after upgrade:

    MCIAS_MASTER_PASSPHRASE=... mciasdb --config /etc/mcias/mcias.conf schema verify

Create an admin account before first server start:

    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 <UUID>
    MCIAS_MASTER_PASSPHRASE=... mciasdb --config /etc/mcias/mcias.conf \
      role grant --id <UUID> --role admin

Tail the last 20 audit events:

    MCIAS_MASTER_PASSPHRASE=... mciasdb --config /etc/mcias/mcias.conf \
      audit tail --n 20

ENVIRONMENT
The environment variable named by passphrase_env in the configuration file must be set to the master key passphrase, unless keyfile is used instead.

Example (with default config):

    export MCIAS_MASTER_PASSPHRASE=your-passphrase
    mciasdb --config /etc/mcias/mcias.conf account list

EXIT STATUS

FILES

/etc/mcias/mcias.conf
    Default configuration file location.

/var/lib/mcias/mcias.db
    SQLite database.

SEE ALSO
mciassrv(1), mciasctl(1), mciasgrpcctl(1)