CLI Reference

Complete reference for the sovra command-line tool.

Global Flags

Admin operations require mTLS authentication. Pass --cert and --key for every admin command:

sovra --cert admin.crt --key admin.key workspace list

login

Authenticate with the Sovra API. Uses SSO by default.

When no --issuer-url or --client-id is provided, the CLI auto-discovers SSO configuration from the server via GET /api/v1/sso-config. You can also set SOVRA_SSO_ISSUER_URL and SOVRA_SSO_CLIENT_ID environment variables.

sovra login                                      # auto-discover from server
sovra login --issuer-url https://idp.example.org --client-id sovra

For legacy AppRole authentication:

sovra login --auth-method approle

logout

Log out from the Sovra API.

sovra logout

activity

View and export activity logs.

activity list

List activity across the organization.

sovra activity list --since 2026-01-01T00:00:00Z --limit 50

activity export

Export activity logs to a file.

sovra activity export \
  --since 2026-01-01T00:00:00Z \
  --until 2026-02-01T00:00:00Z \
  --output activity-export.json \
  --format json

workspace

Manage shared cryptographic workspaces.

workspace create

sovra workspace create \
  --name genomics-data \
  --group-id group-123 \
  --classification CONFIDENTIAL \
  --purpose "Shared genomics research"

workspace list

sovra workspace list --limit 20

workspace get

sovra workspace get ws-123

workspace update

sovra workspace update ws-123 --purpose "Updated purpose"

workspace rotate-dek

Rotate the Data Encryption Key for a workspace.

sovra workspace rotate-dek ws-123

workspace extend

Extend workspace expiration.

sovra workspace extend ws-123 --expires-at 2027-01-01T00:00:00Z

workspace invite

sovra workspace invite ws-123 --org-id org-b

workspace accept-invitation

sovra workspace accept-invitation ws-123 --org-id org-b --group-id group-123

workspace decline-invitation

sovra workspace decline-invitation ws-123 --org-id org-b

workspace request-access

Request access to an existing workspace.

sovra workspace request-access ws-123 --justification "Need access for data analysis"

workspace admission grant

Grant explicit admission to a workspace. Required for SECRET and CRK-protected workspaces.

sovra workspace admission grant ws-123 \
  --identity-id user-456 \
  --identity-type user \
  --org-id org-a

workspace admission list

List all admissions for a workspace.

sovra workspace admission list ws-123

workspace admission get

Get admission status for a specific identity.

sovra workspace admission get ws-123 user-456

workspace admission revoke

Revoke an identity’s admission to a workspace.

sovra workspace admission revoke ws-123 user-456

workspace archive

sovra workspace archive ws-123

workspace delete

sovra workspace delete ws-123

workspace export

Export a workspace as a portable bundle.

sovra workspace export ws-123 --output backup.json

workspace import

Import a workspace from a bundle.

sovra workspace import --input backup.json

federation

Manage federation relationships with partner organizations.

federation list

sovra federation list

federation status

sovra federation status partner-org-id

federation init

Initialize federation for the organization.

sovra federation init

federation establish

sovra federation establish \
  --partner-org org-b \
  --partner-url https://partner.example.org

federation revoke

sovra federation revoke partner-org-id

federation health

sovra federation health

federation import-cert

sovra federation import-cert \
  --partner-org org-b \
  --cert-file partner-cert.pem \
  --public-key-file partner-pubkey.pem

federation renew-cert

Renew the federation certificate for a partner organization.

sovra federation renew-cert partner-org-id

policy

Manage OPA Rego policies for access control.

policy list

sovra policy list --workspace ws-123

policy get

sovra policy get policy-123

policy create

sovra policy create \
  --name data-access \
  --workspace ws-123 \
  --rego-file policy.rego

policy update

sovra policy update policy-123 --rego-file updated-policy.rego

policy delete

sovra policy delete policy-123

policy evaluate

sovra policy evaluate --workspace ws-123 --input-file eval-input.json

policy validate

sovra policy validate policy.rego

audit

Query and export audit logs.

audit query

sovra audit query \
  --since 2026-01-01T00:00:00Z \
  --event-type workspace.access \
  --limit 50

audit get

sovra audit get event-123

audit export

sovra audit export \
  --format json \
  --output audit-export.json \
  --since 2026-01-01T00:00:00Z

audit stats

sovra audit stats --since 2026-01-01T00:00:00Z

audit verify

Verify audit log integrity.

sovra audit verify \
  --since 2026-01-01T00:00:00Z \
  --until 2026-02-01T00:00:00Z

crk

Customer Root Key management.

crk init

Generate a new CRK with two-factor protected shares (fully offline). Each share is encrypted with a random seed code. The admin distributes seed codes to custodians, who then bind their own password via crk bind-seed.

sovra crk init --org-id my-org --shares 5 --threshold 3 --output crk-init.json

Prints seed codes to stdout. Distribute each seed code to the corresponding custodian via a secure out-of-band channel.

crk bind-seed

Decrypt a share using the seed code, re-encrypt with (seed code + password). Run by each custodian offline.

sovra crk bind-seed \
  --init-file crk-init.json \
  --index 1 \
  --seed-code <HEX_SEED_CODE> \
  --output custodian-1.json

The CLI prompts for a password (twice, with confirmation). The password never leaves the custodian’s machine.

crk import-seeds

Assemble custodian seed files into a final secured CRK file (fully offline).

sovra crk import-seeds \
  --init-file crk-init.json \
  --seed-file custodian-1.json \
  --seed-file custodian-2.json \
  --output crk-secured.json

crk generate

Note: Outputs plaintext shares. For production, use crk init which provides two-factor share protection.

Generate a new CRK with Shamir secret sharing.

sovra crk generate --shares 5 --threshold 3 --output crk-shares.json

crk sign

Sign data using CRK shares.

sovra crk sign \
  --shares-file crk-shares.json \
  --public-key BASE64_KEY \
  --data-file message.txt

Supports three share formats:

• Secured CRK file (type: "sovra-crk-secured"): Prompts for share index, seed code (hex), and password for each share until threshold is met.
• Password-encrypted shares: Prompts for each custodian’s password to decrypt locally.
• Plaintext shares: Used directly.

crk verify

Verify a signature against a CRK public key.

sovra crk verify \
  --public-key BASE64_KEY \
  --signature BASE64_SIG \
  --data-file message.txt

crk rotate

Start a CRK rotation ceremony.

sovra crk rotate --threshold 3

crk ceremony start

sovra crk ceremony start --shares 5 --threshold 3

crk ceremony add-share

sovra crk ceremony add-share ceremony-123 \
  --share-file share.json \
  --share-index 1

Supports three share formats:

• Custodian seed file (type: "sovra-crk-custodian-seed"): Prompts for seed code (hex) and password, decrypts locally.
• Password-encrypted share: Prompts for password, decrypts locally.
• Plaintext share: Used directly.

crk ceremony complete

sovra crk ceremony complete ceremony-123

crk ceremony cancel

sovra crk ceremony cancel ceremony-123

crk generate-ceremony start

Start a password-protected CRK generation ceremony. Each shareholder will independently seed their share with a password before the CRK is generated.

sovra crk generate-ceremony start --org-id org-123 --shares 5 --threshold 3

crk generate-ceremony seed

Seed a share index with a password. Run by each shareholder independently. The CLI prompts for a password (hidden input, with confirmation), derives an encryption key locally via Argon2id, and sends the derived key to the server. The password never leaves the shareholder’s machine.

sovra crk generate-ceremony seed <ceremony-id> --index 1 --custodian-name "Alice"

crk generate-ceremony status

Check the status of a generation ceremony.

sovra crk generate-ceremony status <ceremony-id>

crk generate-ceremony complete

Complete the ceremony. The server generates the Ed25519 keypair, splits via Shamir, encrypts each share with the corresponding shareholder’s derived key, zeroes all plaintext material, and returns the CRK metadata with encrypted share blobs.

sovra crk generate-ceremony complete <ceremony-id> --output crk.json

crk generate-ceremony cancel

Cancel an in-progress generation ceremony.

sovra crk generate-ceremony cancel <ceremony-id>

crk generate-ceremony prepare-seed

Prepare an offline seed file for an air-gap ceremony. The custodian runs this on their own machine — no server connection is needed. The CLI prompts for a password, derives a key via Argon2id, and writes a JSON seed file.

sovra crk generate-ceremony prepare-seed --index 1 --custodian-name "Alice" --output seed-alice.json

The seed file is written with 0600 permissions. Securely delete it after transferring to the admin.

crk generate-ceremony import-seed

Import one or more offline seed files (created by prepare-seed) into an active generation ceremony. Run by the admin on a server-connected machine.

sovra crk generate-ceremony import-seed <ceremony-id> \
  --seed-file seed-alice.json \
  --seed-file seed-bob.json

identity

Manage admin, user, service, and device identities.

identity list

sovra identity list --type admin

identity get

sovra identity get identity-123 --type admin

identity create admin

sovra identity create admin \
  --email admin@example.org \
  --name "Admin User" \
  --role security_admin \
  --sso-provider azure_ad \
  --sso-subject sub-456

Roles: super_admin, security_admin, operations_admin, auditor

identity create service

sovra identity create service \
  --name data-pipeline \
  --auth-method approle

Auth methods: approle, kubernetes, cert

identity create user-sso

sovra identity create user-sso \
  --email user@example.org \
  --name "User Name" \
  --sso-provider azure_ad \
  --sso-subject sub-123

identity delete

sovra identity delete identity-123 --type admin

identity admin disable

sovra identity admin disable admin-123

identity admin enable

sovra identity admin enable admin-123

identity service rotate

Rotate credentials for a service identity.

sovra identity service rotate service-123

identity admin bootstrap

Bootstrap the first admin on a clean instance. Generates a CRK and creates the initial admin identity.

sovra --api-url https://control.example.com \
  identity admin bootstrap \
  --email admin@example.org \
  --name "First Admin" \
  --shares 5 \
  --threshold 3

identity admin enroll

Complete admin enrollment using an enrollment token (received from another admin). Generates an mTLS certificate.

sovra --api-url https://control.example.com \
  identity admin enroll \
  --enrollment-token <TOKEN>

identity admin renew-cert

Renew the current admin’s mTLS certificate.

sovra --cert admin.crt --key admin.key \
  identity admin renew-cert

identity admin sign-message

Sign a message using the admin’s mTLS key (for CRK operations).

sovra --cert admin.crt --key admin.key \
  identity admin sign-message --data "data to sign"

identity enroll-device

sovra identity enroll-device --name "edge-sensor-1" --device-type sensor

identity revoke-device

sovra identity revoke-device device-123

identity mfa enable

sovra identity mfa enable admin-123

identity mfa verify

sovra identity mfa verify admin-123 --code 123456

identity group create

sovra identity group create --name researchers --description "Research team"
sovra identity group create --name engineers --idp-group-id "00g1abc2de" --description "Synced from IdP"

identity group update

Update an existing identity group’s name, description, or IdP binding.

sovra identity group update group-123 --name "new-name"
sovra identity group update group-123 --idp-group-id "00g1abc2de"
sovra identity group update group-123 --idp-group-id ""  # clear IdP binding

identity group list

sovra identity group list

identity group add-member

sovra identity group add-member group-123 \
  --identity-id user-456 \
  --identity-type user

identity group remove-member

sovra identity group remove-member group-123 --identity-id user-456

identity group join-requests

List pending join requests for a group.

sovra identity group join-requests group-123

identity group approve-join

Approve a pending join request.

sovra identity group approve-join request-123

identity group deny-join

Deny a pending join request.

sovra identity group deny-join request-123

identity role create

sovra identity role create --name data-reader --description "Read-only data access"

identity role list

sovra identity role list

identity role assign

sovra identity role assign role-123 \
  --identity-id user-456 \
  --identity-type user

identity role unassign

sovra identity role unassign role-123 --identity-id user-456

edge

Manage edge nodes (Vault clusters).

edge list

sovra edge list

edge get

sovra edge get edge-123

edge register

sovra edge register \
  --name edge-eu-west \
  --vault-addr https://vault.eu-west.example.org:8200 \
  --region eu-west

edge unregister

sovra edge unregister edge-123

edge health

sovra edge health edge-123

edge sync-policies

sovra edge sync-policies edge-123

edge sync-keys

sovra edge sync-keys edge-123 --workspace ws-123

edge sync-status

sovra edge sync-status edge-123

cert

Manage certificates issued by the Vault PKI engine.

cert issue

sovra cert issue \
  --common-name api.example.org \
  --role default \
  --ttl 8760h \
  --alt-names api2.example.org,api3.example.org

cert revoke

sovra cert revoke AA:BB:CC:DD

cert get

sovra cert get AA:BB:CC:DD

cert list

sovra cert list

cert ca-chain

sovra cert ca-chain

cert tidy

Clean up expired certificates.

sovra cert tidy --safety-buffer 72h

emergency-access

Manage break-glass emergency access requests.

emergency-access request

sovra emergency-access request \
  --org-id org-a \
  --reason "Critical security incident requiring immediate access"

emergency-access approve

sovra emergency-access approve request-123

emergency-access deny

sovra emergency-access deny request-123

emergency-access complete

sovra emergency-access complete request-123

emergency-access verify

Verify emergency access with CRK signature.

sovra emergency-access verify request-123 --signature BASE64_SIG

emergency-access list

sovra emergency-access list --org-id org-a

emergency-access get

sovra emergency-access get request-123

account-recovery

Account recovery using CRK share reconstruction.

account-recovery initiate

sovra account-recovery initiate \
  --admin-id admin-123 \
  --reason "Lost credentials" \
  --type lost_credentials

Types: lost_credentials, locked_account

account-recovery share

Submit a CRK share for account recovery.

sovra account-recovery share recovery-123

account-recovery complete

sovra account-recovery complete recovery-123

compliance

Generate compliance reports.

compliance summary

sovra compliance summary \
  --since 2026-01-01T00:00:00Z \
  --until 2026-02-01T00:00:00Z

compliance gdpr-dsar

Generate a GDPR Data Subject Access Request report.

sovra compliance gdpr-dsar --subject-id user-123

compliance access-review

sovra compliance access-review \
  --since 2026-01-01T00:00:00Z \
  --until 2026-02-01T00:00:00Z

backup

Manage system backups.

backup create

Create a new backup. The backup payload is encrypted at rest using the organization’s KEK via Vault transit. Requires a CRK co-signature.

sovra backup create --type full --crk-signature <base64-signature>

backup list

List available backups.

sovra backup list

backup get

Get details of a specific backup.

sovra backup get backup-123

backup restore

Restore from a backup. Requires a CRK co-signature. Restore is restricted to the same organization or a clean (empty) instance — cross-org restore is rejected.

sovra backup restore backup-123 --crk-signature <base64-signature>

rotation-policy

Manage automatic key rotation policies for workspaces.

rotation-policy set

sovra rotation-policy set ws-123 --max-age 720h --enabled

rotation-policy get

sovra rotation-policy get ws-123

rotation-policy delete

sovra rotation-policy delete ws-123

rotation-policy list

sovra rotation-policy list

message

Send and receive encrypted direct messages between users on federated control planes without creating a workspace.

message send

sovra message send --to <recipient-id> --to-org <org-id> --subject "..." --body "..."
sovra message send --to <recipient-id> --subject "..." --body-file ./message.txt

When --to-org is omitted, the message is treated as same-org (no federation required). Cross-org messages require an active federation link with the recipient’s organization.

message list

sovra message list [--sent] [--limit N]

message read

sovra message read <message-id>

Decrypts and displays the message body. Received messages are automatically marked as read.

message delete

sovra message delete <message-id>

Deletes a message you own (sent or received).