opctl is the admin CLI. It manages users, roles, tokens, nodes, and audit events through the control-plane API. It uses the current op login profile, including its proxy address, session token, and TLS settings, so there is no separate server address or credential to configure:

op login overpass.example.com --user admin
opctl users ls

The logged-in user must have the corresponding management rules. Mutations made through the API are authorized and recorded in the audit log.

Local recovery mode

Pass --local to operate directly on the control plane's state: the database for users, tokens and nodes, and the server-managed config directory for roles. This mode must run on the control-plane host and bypasses authorization and the audit log; use it only for bootstrap or recovery. A role written with --local while the server is running is picked up by the server on its next restart (the server holds its own in-memory copy).

Data directory resolution

In --local mode, opctl finds the database and config directory without repeating --data-dir everywhere. It reads --config <file>, or /etc/overpass.yaml (or .yml) when --config is omitted. Precedence:

1. An explicitly defined data_dir in the selected config file
2. --data-dir <dir> when the config omits data_dir
3. The default /var/lib/overpass

The data directory is created if it doesn't exist.

Users

opctl users add <name> --logins alice,deploy --roles admin   # prompts for a password
opctl users add <name> --roles access --no-password          # OIDC-only
opctl users ls
opctl users rm <name>

Flag (users add)	Purpose
--logins	unix logins this user may use (comma-separated)
--roles	roles to assign (default: access)
--password-stdin	read the password from stdin instead of prompting
--no-password	create without a password (OIDC-only)

Roles

opctl roles ls
opctl roles set <name> --logins deploy --node-labels env=prod --rules terminal,manage_nodes
opctl roles rm <name>

roles set creates or updates a role. See RBAC for the model.

Tokens

opctl tokens add        # prints a node join token
opctl tokens ls

Nodes

opctl nodes ls
opctl nodes info <name>  # live hostname, OS, CPU, memory, disk and uptime from the agent
opctl nodes rm <name>

Audit

opctl audit ls          # recent events, newest first