Sovaria CLI

Operator CLI for gateway-backed Sovaria project and platform workflows.

Install

npm install -g @sovaria/cli   # or: npx @sovaria/cli --help
pip install sovaria-cli       # same CLI from PyPI

Both need Python 3.11+. The npm package sets up a private environment in ~/.sovaria/npm-cli on first run.

Run

Examples below use sov ... command syntax.

If sov is installed on your PATH:

sov --help

From repo root without installation:

python -m apps.cli.src.main --help

Cross-SDK Happy Path Smoke

Use the repository smoke script to validate one shared happy path across:

• CLI auth + scoped SQL call
• TypeScript SDK SQL + engine health
• Python SDK SQL + engine health

SOVARIA_URL=http://localhost:8000 \
SOVARIA_ORG_ID=<org_uuid> \
SOVARIA_PROJECT_ID=<project_uuid> \
SOVARIA_EMAIL=<owner_email> \
SOVARIA_PASSWORD='<owner_password>' \
scripts/cli_sdk_happy_path.sh

If you already have valid CLI tokens, omit SOVARIA_EMAIL and SOVARIA_PASSWORD.

Authentication

sov login
sov login --email you@example.com
sov login --file-storage          # headless: tokens in ~/.sovaria/credentials.toml
sov logout
sov logout --force                # clear local tokens if server revoke fails

• Browser (PKCE): authorize opens the console origin (get_console_url); the token exchange POSTs to the gateway api_url /oauth/token proxy. That split is intentional.
• Password: never pass --password. Operator login prompts with getpass, or reads SOVARIA_PASSWORD.
• Product user create: sov auth-product create --email ... prompts for the new user's password, or reads SOVARIA_USER_PASSWORD. Do not reuse SOVARIA_PASSWORD (that is the operator login secret).
• Magic link: sov auth magic-link verify reads the token from stdin or SOVARIA_MAGIC_TOKEN.
• GitHub deploy PAT: set SOVARIA_GITHUB_TOKEN or use gh auth token. There is no --token flag.
• OAuth callback: binds 127.0.0.1 by default. Non-loopback SOVARIA_CLI_CALLBACK_HOST requires --insecure-callback.

Token refresh contract

Axis supports two refresh modes. Do not mix them:

Copying the console cookie pattern into a CLI or SDK client will fail silently (no cookie jar). Copying the CLI JSON-body pattern into a browser app bypasses HttpOnly cookie storage.

Pulse WebSocket URLs

sov realtime ws-url issues an opaque ticket= query parameter. Never put a JWT in ?token= — production gateways disable GATEWAY_WS_ALLOW_QUERY_TOKEN. Local .env.local may still enable the legacy query-token path; do not copy that into clients.

sov realtime ws-url my-channel --org <org_id> --project <project_id>
# wss://api.sovaria.in/api/v1/rt/ws/my-channel?ticket=...&org_id=...&project_id=...

Core Command Groups

• sov auth ... auth login/logout
• sov scope ... default org/project/env scope
• sov data ... Atlas-Doc and Atlas-Rel
• sov realtime ... Pulse realtime and e2ee
• sov policy ... Guard policy management
• sov audit ... Echo audit and simulation
• sov chrono ... Chrono timeline/snapshot operations
• sov fn ... Forge function deploy/status/invoke
• sov project ... project config template + scaffold creation
• sov api call ... raw gateway API request
• sov branches list|create|get|update|use|delete environments as branches (create x --from staging, use x)
• sov gen types typescript|python|dart|swift|kotlin -o <file> row models from the live schema
• sov storage cp [-r] <src> <dst> copy between local paths and ss://bucket/path (or between buckets)
• sov collections delete <path> [-r] delete a collection or document (and its subcollections with -r)
• sov auth-product export users.json|users.csv every app user (profile fields only)
• sov functions new <name> --runtime python|node|typescript|go a function folder with a starter handler

Project Bootstrap (Config JSON)

Create a template config file:

sov project init-config my-app --output sovaria.config.json

Then scaffold a project from that config:

sov project create --config sovaria.config.json --dir .

Function Sandbox Flow

Deploy a function bundle (zipped from local folder):

sov fn deploy ./my-function --name hello --project <project_id> --note "add audit logging"

Poll deployment status:

sov fn status <deploy_id> --project <project_id>

Invoke the deployed function in its project sandbox:

sov fn invoke hello --project <project_id> --data '{"message":"hi"}'

Run a simulation invocation (tracked separately from normal invoke):

sov fn invoke hello --project <project_id> --simulate --data '{"message":"dry-run"}'

Queue heavy async invocation and wait for completion:

sov fn invoke hello --project <project_id> --execution-profile heavy --async --wait --data-file payload.json

List function versions:

sov fn versions hello --project <project_id>

List functions with active versions + queue depth:

sov fn functions --project <project_id>

List invocation history:

sov fn history hello --project <project_id> --mode invoke

List durable async jobs:

sov fn jobs hello --project <project_id> --status QUEUED

Promote a specific function version:

sov fn promote hello --project <project_id> --version 3 --reason "promote stable release"

Rollback to previous active version:

sov fn rollback hello --project <project_id> --reason "rollback regression"

Diff two simulation invocations:

sov fn sim-diff hello <left_invocation_id> <right_invocation_id> --project <project_id>

Scope Requirement

Realtime and relational routes require org/project scope. You can pass scope per command (--org --project --env) or set defaults:

sov scope set <org_id> <project_id> --env <env_id>