.Dd March 11, 2026
.Dt MCIASCTL 1
.Os
.Sh NAME
.Nm mciasctl
.Nd MCIAS admin CLI (REST)
.Sh SYNOPSIS
.Nm
.Op Fl server Ar url
.Op Fl token Ar jwt
.Op Fl cacert Ar path
.Ar command
.Op Ar subcommand
.Op Ar flags
.Sh DESCRIPTION
.Nm
is the administrator command-line interface for MCIAS.
It connects to a running
.Xr mciassrv 1
instance via the REST API over HTTPS and provides subcommands for managing
accounts, roles, tokens, and Postgres credentials.
.Pp
Authentication is performed using a bearer JWT.
The token must have the
.Qq admin
role for most operations.
Pass the token with the
.Fl token
flag or by setting the
.Ev MCIAS_TOKEN
environment variable.
.Sh OPTIONS
.Bl -tag -width Ds
.It Fl server Ar url
Base URL of the mciassrv instance.
Default:
.Qq https://localhost:8443 .
Can also be set with the
.Ev MCIAS_SERVER
environment variable.
.It Fl token Ar jwt
Bearer token for authentication.
Can also be set with the
.Ev MCIAS_TOKEN
environment variable.
.It Fl cacert Ar 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.
.El
.Sh COMMANDS
.Ss account
.Bl -tag -width Ds
.It Nm Ic account Ic list
Lists all accounts.
Credential fields are never included in the output.
.It Nm Ic account Ic create Fl username Ar name Fl password Ar pass Op Fl type Ar human|system
Creates a new account.
.Fl type
defaults to
.Qq human .
.It Nm Ic account Ic get Fl id Ar uuid
Returns the account with the given UUID.
.It Nm Ic account Ic update Fl id Ar uuid Op Fl status Ar active|inactive
Updates account fields.
Currently only status can be updated.
.It Nm Ic account Ic delete Fl id Ar uuid
Soft-deletes the account and revokes all its tokens.
.El
.Ss role
.Bl -tag -width Ds
.It Nm Ic role Ic list Fl id Ar uuid
Lists the roles assigned to the account.
.It Nm Ic role Ic set Fl id Ar uuid Fl roles Ar role1,role2,...
Replaces the role set for the account with the comma-separated list.
.El
.Ss token
.Bl -tag -width Ds
.It Nm Ic token Ic issue Fl id Ar uuid
Issues a new service token for a system account.
.It Nm Ic token Ic revoke Fl jti Ar jti
Revokes the token with the given JTI.
.El
.Ss pgcreds
.Bl -tag -width Ds
.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 Fl password Ar pass
Sets Postgres credentials for the account.
The credentials are encrypted with AES-256-GCM using the server master key.
.It Nm Ic pgcreds Ic get Fl id Ar uuid
Retrieves and prints the Postgres credentials.
The password is included in plaintext; treat the output as sensitive.
.El
.Sh ENVIRONMENT
.Bl -tag -width Ds
.It Ev MCIAS_TOKEN
Bearer token used for authentication when
.Fl token
is not specified.
.It Ev MCIAS_SERVER
Base URL of the mciassrv instance when
.Fl server
is not specified.
.El
.Sh EXAMPLES
List all accounts:
.Bd -literal -offset indent
mciasctl -server https://auth.example.com -token $ADMIN_TOKEN account list
.Ed
.Pp
Create a human account:
.Bd -literal -offset indent
mciasctl account create -username alice -password s3cr3t
.Ed
.Pp
Grant the admin role:
.Bd -literal -offset indent
mciasctl role set -id $UUID -roles admin
.Ed
.Sh EXIT STATUS
.Ex -std
.Sh SEE ALSO
.Xr mciassrv 1 ,
.Xr mciasdb 1 ,
.Xr mciasgrpcctl 1