MCIASGRPCCTL(1)

NAME
mciasgrpcctl - MCIAS gRPC admin CLI

SYNOPSIS
mciasgrpcctl [-server addr] [-token jwt] [-cacert path] command [subcommand] [flags]

DESCRIPTION
mciasgrpcctl is the gRPC companion to mciasctl(1). It connects to the gRPC/TLS listener of a running mciassrv(1) instance and provides subcommands mirroring the REST admin CLI.

The gRPC listener must be enabled in the mciassrv configuration (grpc_addr) for mciasgrpcctl to connect.

Authentication is performed using a bearer JWT passed as gRPC metadata. The token must have the "admin" role for most operations.

OPTIONS

-server addr
    gRPC server address in host:port format. Default: "mcias.metacircular.net:9443".

-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.

COMMANDS

  Informational (no authentication required)

mciasgrpcctl health
    Calls the Health RPC. Prints "ok" and exits 0 if the server is healthy.

mciasgrpcctl pubkey
    Returns the server's Ed25519 public key as a JWK.

  auth

mciasgrpcctl auth login -username name [-totp code]
    Authenticates with the server and prints the bearer token to stdout. The password is always prompted interactively. Suitable for use in scripts:

        export MCIAS_TOKEN=$(mciasgrpcctl auth login -username alice)

mciasgrpcctl auth logout
    Revokes the current bearer token.

  account

mciasgrpcctl account list
    Lists all accounts.

mciasgrpcctl account create -username name -password pass [-type human|system]
    Creates a new account.

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

mciasgrpcctl account update -id uuid -status active|inactive
    Updates account status.

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

  role

mciasgrpcctl role list -id uuid
    Lists roles for the account.

mciasgrpcctl role set -id uuid -roles role1,role2,...
    Replaces the role set for the account.

  token

mciasgrpcctl token validate -token jwt
    Validates the given token and prints its claims.

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

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

  pgcreds

mciasgrpcctl pgcreds get -id uuid
    Returns the Postgres credentials for the account.

mciasgrpcctl pgcreds set -id uuid -host host [-port port -db db -user user -password pass]
    Sets Postgres credentials for the account.

  policy

mciasgrpcctl policy list
    Lists all policy rules.

mciasgrpcctl policy create -description str -json file [-priority n [-not-before rfc3339 [-expires-at rfc3339]]]
    Creates a new policy rule. file must be a path to a file containing a JSON rule body.

mciasgrpcctl policy get -id id
    Returns the policy rule with the given ID.

mciasgrpcctl policy update -id id [-priority n [-enabled true|false [-not-before rfc3339 [-expires-at rfc3339 [-clear-not-before [-clear-expires-at]]]]]]
    Applies a partial update to a policy rule.

mciasgrpcctl policy delete -id id
    Permanently removes a policy rule.

ENVIRONMENT

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

EXAMPLES
Check server health over gRPC:

    mciasgrpcctl -server auth.example.com:9443 -cacert /etc/mcias/ca.crt health

Using grpcurl as an alternative client:

    grpcurl -cacert /etc/mcias/ca.crt \
      -H "authorization: Bearer $TOKEN" \
      auth.example.com:9443 \
      mcias.v1.AdminService/Health

EXIT STATUS

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