Platform
ScaiWave ScaiGrid ScaiCore ScaiBot ScaiDrive ScaiKey Models Tools & Services
Solutions
Organisations Developers Internet Service Providers Managed Service Providers AI-in-a-Box
Resources
Support Documentation Blog Downloads
Company
About Research Careers Investment Opportunities Contact
Log in

CLI

scaivault is the command-line client. Same API as the SDKs, designed for interactive use, scripts, CI/CD pipelines, and operator workflows.

Install#

bash
1
2
pip install scaivault
scaivault --version

Python 3.10+. The CLI ships in the same package as the Python SDK.

Configure#

The CLI reads configuration from ~/.scaivault/config.json and the environment. Set the server URL and authenticate once:

bash
1
2
3
scaivault config set base_url https://scaivault.scailabs.ai
scaivault auth login --token "$SCAIVAULT_TOKEN"
scaivault auth whoami

Environment variables override config:

Variable Meaning
SCAIVAULT_URL Base URL
SCAIVAULT_TOKEN Bearer token
SCAIVAULT_PARTNER_ID Explicit partner context (admins)
SCAIVAULT_TENANT_ID Explicit tenant context (admins)
SCAIVAULT_DEBUG 1 for verbose output

In CI, set SCAIVAULT_URL and SCAIVAULT_TOKEN and skip auth login entirely.

Output formats#

Most commands default to a human-readable table. Add --json for machine output, then pipe through jq:

bash
1
scaivault secrets list --json | jq -r '.secrets[].path'

Exit codes: 0 success, 1 general error, 2 auth, 3 authz, 4 not found, 5 validation.

Secrets#

bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
# Read
scaivault secrets read app/db/credentials
scaivault secrets read app/db/credentials --version 2
scaivault secrets read app/db/credentials --field password
scaivault secrets read app/db/credentials --json

# Write — accepts repeated key=value pairs, --json-file, or --type
scaivault secrets write app/db/credentials username=admin password=s3cret
scaivault secrets write app/config --type json --json-file config.json
scaivault secrets write app/api-key key=abc --expires-in 30d

# List
scaivault secrets list
scaivault secrets list --prefix environments/production/ --limit 100

# Delete
scaivault secrets delete app/old --hard

# Versions
scaivault secrets versions app/db/credentials

# Rotate
scaivault secrets rotate app/db/credentials

# Find expiring
scaivault secrets expiring --days 30 --prefix environments/production/

Secret policies (value generation)#

bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
scaivault secret-policies list
scaivault secret-policies get sp_abc
scaivault secret-policies types          # list available generators and charsets

# Create from inline JSON
scaivault secret-policies create \
  --name "Strong Password" \
  --type password \
  --fields '[{"name":"password","generator":"random","config":{"length":32,"charset":"alphanumeric"}}]'

# Preview without storing
scaivault secret-policies generate sp_abc --show

See the Secret Policies reference for the generator catalog.

Access policies#

bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
scaivault policies list
scaivault policies get pol_abc

# Quick create (single rule)
scaivault policies create \
  --name "Production Read" \
  --path "environments/production/**" \
  --permissions read,list

# Bind
scaivault policies bind pol_abc --identity-type group --identity-id group:developers

# Test
scaivault policies test app/db/credentials read --identity user:alice@acme.example

scaivault policies delete pol_abc

For multi-rule policies, use --rules-file rules.json with the same structure as the REST body.

Rotation#

bash
1
2
3
4
5
6
scaivault rotation list
scaivault rotation create --name "quarterly" --interval 90d --grace-period 48h --warn-before 7d,1d
scaivault rotation assign rot_quarterly environments/production/salesforce/oauth
scaivault rotation trigger rot_quarterly
scaivault rotation history rot_quarterly --status failed
scaivault rotation due --within-hours 168

PKI#

bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# CAs
scaivault pki ca list
scaivault pki ca create --name "Root CA" --common-name "Acme Root CA" --validity-days 3650
scaivault pki ca cert ca_root_abc --format pem > root.pem

# Issue
scaivault pki certs issue \
  --ca ca_intermediate_abc \
  --common-name "billing.svc.cluster.local" \
  --san "billing-api.svc.cluster.local" \
  --validity-days 7

# List, revoke
scaivault pki certs list --ca-id ca_intermediate_abc --expiring-within 30d
scaivault pki certs revoke cert_xyz --reason key_compromise

# CSR workflow
scaivault pki csr list --status pending
scaivault pki csr approve csr_abc
scaivault pki csr sign csr_abc --ca ca_intermediate_abc --validity-days 90

# ACME
scaivault pki acme register --provider letsencrypt --email certs@acme.example
scaivault pki acme issue --account acme_abc --domains api.acme.example --challenge dns-01

Dynamic secrets#

bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
scaivault dynamic engines list
scaivault dynamic roles list postgres-prod

# Generate a lease and use it
scaivault dynamic creds postgres-prod readonly --ttl 2h --json
# -> { "lease_id": "...", "data": { "connection_url": "..." } }

scaivault dynamic leases list --engine postgres-prod
scaivault dynamic leases renew lease_abc --ttl 1h
scaivault dynamic leases revoke lease_abc

Audit#

bash
1
2
3
scaivault audit query --action read --start 2026-04-22 --end 2026-04-23
scaivault audit trail environments/production/salesforce/oauth
scaivault audit summary

Service accounts and API keys#

bash
1
2
3
4
scaivault service-accounts create --name "CI Pipeline" --roles secrets-reader
scaivault service-accounts create-key sva_abc --name "Production Key"
scaivault service-accounts list-keys sva_abc
scaivault service-accounts delete-key sva_abc key_xyz

API key plaintext is shown once at creation. Pipe to a secret store immediately, or pass --store-in <path> to write the new key directly into ScaiVault under a path you control.

Subscriptions#

bash
1
2
3
4
5
6
7
8
scaivault subscriptions create \
  --name "Slack rotation alerts" \
  --paths "environments/production/**" \
  --events secret.rotated,rotation.due \
  --webhook https://hooks.slack.com/xxx

# Long-poll an existing subscription
scaivault subscriptions poll sub_abc --follow

--follow keeps polling and prints each event as it arrives — handy for piping into another tool.

Federation#

bash
1
2
3
scaivault federation list
scaivault federation sync fed_abc
scaivault federation status fed_abc

ScaiKey#

Tenant-onboarding workflow lives here:

bash
1
2
3
4
scaivault scaikey register --scope tenant --tenant-slug acme --email admin@acme.example
scaivault scaikey status
scaivault scaikey sync                  # trigger identity sync
scaivault scaikey sync-status --history

TPM (self-hosted)#

For deployments using a TPM 2.0 as the KMS root:

bash
1
2
3
4
5
6
7
8
scaivault tpm init --sopin <so-pin> --userpin <user-pin>
scaivault tpm status

# CRITICAL — back the key up
scaivault tpm backup --output backup.blob --userpin <user-pin>

# Restore to a new host
scaivault tpm restore --input backup.blob --userpin <user-pin>

The TPM-wrapped key never leaves the device in plaintext. Back up the wrapping blob — without it, key recovery on a new host is impossible.

Common patterns#

CI/CD: fetch credentials at job start#

bash
1
2
3
4
5
6
7
export SCAIVAULT_URL="https://scaivault.scailabs.ai"
export SCAIVAULT_TOKEN="$CI_VAULT_TOKEN"

# Read JSON and export specific fields
creds=$(scaivault secrets read app/db/prod --json)
export DB_USER=$(echo "$creds" | jq -r '.data.username')
export DB_PASS=$(echo "$creds" | jq -r '.data.password')

Watch for expiring secrets#

bash
1
2
3
scaivault secrets expiring --days 14 --json \
  | jq -r '.secrets[] | "\(.path) expires \(.expires_at)"' \
  | sort

Stream rotation events#

bash
1
2
scaivault subscriptions poll sub_abc --follow --json \
  | jq -r 'select(.event_type=="secret.rotated") | "\(.path): \(.data.old_version) -> \(.data.new_version)"'

One-shot lease for a script#

bash
1
2
3
4
5
6
7
8
9
lease=$(scaivault dynamic creds postgres-prod readonly --ttl 30m --json)
url=$(echo "$lease" | jq -r '.data.connection_url')
lease_id=$(echo "$lease" | jq -r '.lease_id')

# Use it
psql "$url" -c "SELECT count(*) FROM users"

# Revoke as soon as we're done
scaivault dynamic leases revoke "$lease_id"

Troubleshooting#

"Not authenticated." scaivault auth login --token <token> or set SCAIVAULT_TOKEN.

"Connection refused." Check scaivault config get base_url and try curl -s "$URL/v1/health".

"Permission denied." scaivault auth whoami to see the token's identity and scopes; scaivault policies test <path> <permission> to see which policy rule blocks (or fails to allow) the action.

Verbose tracing. SCAIVAULT_DEBUG=1 scaivault ... prints every HTTP request and response.

What's next#

  • Python SDK — same operations from inside an application.
  • MCP — same operations for AI agents.
  • Quickstart — first steps with the API.
Updated 2026-05-17 13:26:51 View source (.md) rev 1