.Dd March 11, 2026
.Dt MCIASGRPCCTL 1
.Os
.Sh NAME
.Nm mciasgrpcctl
.Nd MCIAS gRPC admin CLI
.Sh SYNOPSIS
.Nm
.Op Fl server Ar addr
.Op Fl token Ar jwt
.Op Fl cacert Ar path
.Ar command
.Op Ar subcommand
.Op Ar flags
.Sh DESCRIPTION
.Nm
is the gRPC companion to
.Xr mciasctl 1 .
It connects to the gRPC/TLS listener of a running
.Xr mciassrv 1
instance and provides subcommands mirroring the REST admin CLI.
.Pp
The gRPC listener must be enabled in the mciassrv configuration
.Pq Sy grpc_addr
for
.Nm
to connect.
.Pp
Authentication is performed using a bearer JWT passed as gRPC metadata.
The token must have the
.Qq admin
role for most operations.
.Sh OPTIONS
.Bl -tag -width Ds
.It Fl server Ar addr
gRPC server address in
.Ar host:port
format.
Default:
.Qq localhost:9443 .
.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.
.El
.Sh COMMANDS
.Ss Informational (no authentication required)
.Bl -tag -width Ds
.It Nm Ic health
Calls the Health RPC.
Prints
.Qq ok
and exits 0 if the server is healthy.
.It Nm Ic pubkey
Returns the server's Ed25519 public key as a JWK.
.El
.Ss account
.Bl -tag -width Ds
.It Nm Ic account Ic list
Lists all accounts.
.It Nm Ic account Ic create Fl username Ar name Fl password Ar pass Op Fl type Ar human|system
Creates a new account.
.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 Fl status Ar active|inactive
Updates account status.
.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 roles for the account.
.It Nm Ic role Ic set Fl id Ar uuid Fl roles Ar role1,role2,...
Replaces the role set for the account.
.El
.Ss token
.Bl -tag -width Ds
.It Nm Ic token Ic validate Fl token Ar jwt
Validates the given token and prints its claims.
.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 get Fl id Ar uuid
Returns the Postgres credentials for the account.
.It Nm Ic pgcreds Ic set Fl id Ar uuid Fl host Ar host Op Fl port Ar port Fl db Ar db Fl user Ar user Fl password Ar pass
Sets Postgres credentials for the account.
.El
.Sh ENVIRONMENT
.Bl -tag -width Ds
.It Ev MCIAS_TOKEN
Bearer token used for authentication when
.Fl token
is not specified.
.El
.Sh EXAMPLES
Check server health over gRPC:
.Bd -literal -offset indent
mciasgrpcctl -server auth.example.com:9443 -cacert /etc/mcias/ca.crt health
.Ed
.Pp
Using grpcurl as an alternative client:
.Bd -literal -offset indent
grpcurl -cacert /etc/mcias/ca.crt \\
  -H "authorization: Bearer $TOKEN" \\
  auth.example.com:9443 \\
  mcias.v1.AdminService/Health
.Ed
.Sh EXIT STATUS
.Ex -std
.Sh SEE ALSO
.Xr mciassrv 1 ,
.Xr mciasctl 1 ,
.Xr mciasdb 1