mezctl CLI Reference

mezctl is the admin CLI for Mezite. It connects to the auth service (default localhost:3025, override with --auth-server) and provides full control over users, roles, tokens, nodes, audit logs, access requests, and auth connectors. Pass a session token via --token or the MEZITE_AUTH_TOKEN environment variable.

users

Manage local users.

User management bash

# Create a user with roles
mezctl users create --username=alice --roles=developer,viewer

# List all users
mezctl users list

# Delete a user
mezctl users delete --username=alice

# Lock a user (prevent login) — uses the locks subsystem
mezctl locks create --user=alice --reason="Security review"

# Unlock a user
mezctl locks delete --target-type=user --target-name=alice

roles

Manage RBAC roles that control SSH access.

Role management bash

# Create a role from a JSON file
mezctl roles create --from-file=role-developer.json

# List all roles
mezctl roles ls

# Get a specific role definition
mezctl roles get developer

# Delete a role
mezctl roles delete developer

tokens

Manage join tokens that agents use to register with the cluster.

Token management bash

# Create a node join token (valid for 1 hour)
mezctl tokens create --roles=node --ttl=1h

# List active tokens
mezctl tokens ls

nodes

List registered SSH nodes.

List nodes bash

# List all nodes with their labels and status
mezctl nodes ls

audit

Query the audit log.

Audit log queries bash

# List recent audit events
mezctl audit ls

# Filter by event type
mezctl audit ls --type=session.start

# Show events from the last 24 hours
mezctl audit ls --since=24h

# Filter by user
mezctl audit ls --user=alice

access-requests

Review and manage access requests.

Access request management bash

# List pending access requests
mezctl access-requests ls

# Approve a request
mezctl access-requests approve <request-id>

# Deny a request
mezctl access-requests deny <request-id>

connectors

Manage authentication connectors (OIDC, SAML, GitHub, LDAP).

Auth connector management bash

# Create an OIDC connector
mezctl connectors create --name=okta --type=oidc \
  --issuer-url=https://auth.example.com \
  --client-id=mezite-app \
  --client-secret=secret \
  --redirect-url=https://access.example.com/callback

# List connectors
mezctl connectors list

ca

Manage Certificate Authority operations.

CA management bash

# View CA status
mezctl ca status

# Export the CA public key
mezctl ca export --type=user

# Initiate CA rotation
mezctl ca rotate --type=user