Skip to main content

Admin CLI

The identity service ships with zymtrace-cli, an administrative tool for managing users and roles directly, without logging in to the UI.

Use it if you:

  • lost your admin password
  • misconfigured OIDC provider
  • have an account without the right roles

If you have shell access to the identity service (SSH to the host, or kubectl exec into the pod), you can restore access with a few commands.

All operations are recorded in the audit log with origin=cli.

Running the CLI​

In Kubernetes deployments, execute the CLI inside the identity pod:

kubectl exec -it -n your-zymtrace zymtrace-identity-XXX-XX -- bin/zymtrace-cli --help

Find your identity pod name with kubectl get pods -n <namespace> | grep identity.

Restoring access​

A typical lockout recovery:

# 1. Find your account
zymtrace-cli identity user list --query [email protected] --include-roles

# 2. Reset its password (prompts for the new password with input hidden)
zymtrace-cli identity user reset-password --user-id <USER_ID>

# 3. Make sure it has the System Admin role
zymtrace-cli identity roles set --user-id <USER_ID> --admin

Or create a fresh admin account from scratch:

# Prompts for the password with input hidden
zymtrace-cli identity user create --email [email protected]
zymtrace-cli identity roles set --user-id <USER_ID> --admin
OIDC deployments

When OIDC is enabled, local login additionally requires the auth:local:login permission. The built-in System Admin role includes it (**:*), so an account recovered with roles set --admin can always log in locally at https://zymtrace.company.com.

Command reference​

All commands accept -e/--endpoint <URL> (default http://127.0.0.1:7829, which is correct when running inside the identity pod; otherwise, you need to specify the correct address).

Create a user​

$ zymtrace-cli identity user create --email [email protected] --password 'secure-password' --given-name Jane --family-name Doe
User 01a0345e-3959-7162-8336-ad512287d145
  email: [email protected]
  given_name: Jane
  family_name: Doe
  created_at: 2026-08-24T15:23:05.433+00:00
  updated_at: 2026-08-24T15:23:05.048296+00:00

Omit --password to read it from stdin: on a TTY you get an interactive prompt with input hidden; otherwise it is read from the pipe:

echo 'secure-password' | zymtrace-cli identity user create --email [email protected]

New users start with only the default Default Project Viewer role; grant more with zymtrace-cli identity roles set.

List users​

$ zymtrace-cli identity user list --query jane --include-roles
User 01a0345e-3959-7162-8336-ad512287d145
  email: [email protected]
  given_name: Jane
  family_name: Doe
  created_at: 2026-08-24T15:23:05.433+00:00
  updated_at: 2026-08-24T15:23:05.048296+00:00
  roles: Default Project Viewer

Page 0: 1 users (1 total, 1 pages)

Other filters: --org-id <UUID>, --page N, --page-size N (max 100).

Reset a password​

Interactively, with input hidden:

zymtrace-cli identity user reset-password --user-id 01a0345e-3959-7162-8336-ad512287d145

Or non-interactively, via --password or a pipe (note that both can leak the password into shell history or process listings):

zymtrace-cli identity user reset-password --user-id 01a0345e-3959-7162-8336-ad512287d145 --password 'new-password'
echo 'new-password' | zymtrace-cli identity user reset-password --user-id 01a0345e-3959-7162-8336-ad512287d145

List roles​

$ zymtrace-cli identity roles list --name "System Admin"
Role 00000000-0000-0000-0000-000000000001
  name: System Admin
  is_locked: true
  users: 13
  perms: **:*

1 roles

Filters: --org-id <UUID>, --user-id <UUID> (only roles assigned to that user), --name <NAME> (exact match, repeatable). Without filters, all roles are listed.

Set a user's roles​

Replaces the user's entire role assignment with the given set. Role names are validated before anything is changed:

$ zymtrace-cli identity roles set --user-id 01a0345e-3959-7162-8336-ad512287d145 --admin --role "System Viewer"
User 01a0345e-3959-7162-8336-ad512287d145
  email: [email protected]
  ...
  roles: System Admin, System Viewer

--admin is shorthand for including the built-in System Admin role. Unknown role names fail without modifying anything:

$ zymtrace-cli identity roles set --user-id 01a0345e-... --role "Nonexistent Role"
Error: roles not found: Nonexistent Role

Pass no roles to revoke everything:

zymtrace-cli identity roles set --user-id 01a0345e-3959-7162-8336-ad512287d145