MCIASCTL(1)

NAME
mciasctl - MCIAS admin CLI (REST)

SYNOPSIS
mciasctl [-server url] [-token jwt] [-cacert path] command [subcommand] [flags]

DESCRIPTION
mciasctl is the administrator command-line interface for MCIAS. It connects to a running mciassrv(1) instance via the REST API over HTTPS and provides subcommands for managing accounts, roles, tokens, and Postgres credentials.

Authentication is performed using a bearer JWT. The token must have the "admin" role for most operations. Pass the token with the -token flag or by setting the MCIAS_TOKEN environment variable.

OPTIONS

-server url
    Base URL of the mciassrv instance. Default: "https://mcias.metacircular.net:8443". Can also be set with the MCIAS_SERVER environment variable.

-token jwt
    Bearer token for authentication. Can also be set with the MCIAS_TOKEN environment variable.

-cacert path
    Path to a CA certificate in PEM format for TLS verification. Useful when mciassrv uses a self-signed certificate. If omitted, the system certificate pool is used.

COMMANDS

  account

mciasctl account list
    Lists all accounts. Credential fields are never included in the output.

mciasctl account create -username name -password pass [-type human|system]
    Creates a new account. -type defaults to "human".

mciasctl account get -id uuid
    Returns the account with the given UUID.

mciasctl account update -id uuid [-status active|inactive]
    Updates account fields. Currently only status can be updated.

mciasctl account delete -id uuid
    Soft-deletes the account and revokes all its tokens.

  role

mciasctl role list -id uuid
    Lists the roles assigned to the account.

mciasctl role set -id uuid -roles role1,role2,...
    Replaces the role set for the account with the comma-separated list.

  token

mciasctl token issue -id uuid
    Issues a new service token for a system account.

mciasctl token revoke -jti jti
    Revokes the token with the given JTI.

  pgcreds

mciasctl pgcreds set -id uuid -host host -port port -db db -user user -password pass
    Sets Postgres credentials for the account. The credentials are encrypted with AES-256-GCM using the server master key.

mciasctl pgcreds get -id uuid
    Retrieves and prints the Postgres credentials. The password is included in plaintext; treat the output as sensitive.

ENVIRONMENT

MCIAS_TOKEN
    Bearer token used for authentication when -token is not specified.

MCIAS_SERVER
    Base URL of the mciassrv instance when -server is not specified.

EXAMPLES
List all accounts:

    mciasctl -server https://auth.example.com -token $ADMIN_TOKEN account list

Create a human account:

    mciasctl account create -username alice -password s3cr3t

Grant the admin role:

    mciasctl role set -id $UUID -roles admin

EXIT STATUS

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