CLI reference

Every sov command, generated from the CLI itself (version 0.2.9). Install with pip install sovaria-cli, then run sov login. Add --json to any command for machine-readable output (or set SOV_JSON=1).

Most commands act on your default organization and project (set by sov login or sov scope). Override per command with --org, --project and --env, or use a named --profile for several accounts.

#sov login

Authenticate with Sovaria. By default opens a browser (PKCE flow). Pass --email to use password login (prompt or SOVARIA_PASSWORD).

sov login [OPTIONS]

#sov logout

Revoke the session for one profile, then clear that profile's local credentials.

sov logout [OPTIONS]

#sov whoami

Print the authenticated user, active scope, and accessible orgs/projects.

sov whoami [OPTIONS]

#sov orgs

List organisations visible to the authenticated user.

sov orgs [OPTIONS]

#sov projects

List projects under an organisation.

sov projects [OPTIONS] [org_id]

#sov context

Context and identity commands

sov context whoami

Print the authenticated user, active scope, and accessible orgs/projects.

sov context whoami [OPTIONS]

sov context list

List organisations and projects you can use with the CLI.

sov context list [OPTIONS]

sov context orgs

List organisations visible to the authenticated user.

sov context orgs [OPTIONS]

sov context projects

List projects under an organisation.

sov context projects [OPTIONS] [org_id]

sov context pick

Interactively pick default org/project scope by index.

sov context pick [OPTIONS]

sov context context

Show access roles the current user has on a specific resource.

sov context context [OPTIONS] {resource_id}

#sov dashboard

Project overview dashboard

sov dashboard [OPTIONS] COMMAND [ARGS]...

#sov connect

Show everything you need to connect an app (like console Connect panel).

sov connect [OPTIONS]

#sov deploy

Deploy a cloud function to the Forge engine. Example: sov deploy ./my-function --name greet --project proj-abc123

sov deploy [OPTIONS] [directory]

#sov auth

Authentication commands

sov auth login

Authenticate with Sovaria. By default opens a browser (PKCE flow). Pass --email to use password login (prompt or SOVARIA_PASSWORD).

sov auth login [OPTIONS]

sov auth logout

Revoke the session for one profile, then clear that profile's local credentials.

sov auth logout [OPTIONS]

sov auth mfa-verify

Complete MFA after login when the gateway returned mfa_required=true.

sov auth mfa-verify [OPTIONS]

sov auth sessions

List active login sessions for the current user.

sov auth sessions [OPTIONS]

sov auth sessions-revoke

Revoke one active session.

sov auth sessions-revoke [OPTIONS] {session_id}

sov auth sessions-revoke-others

Revoke all sessions except the current one.

sov auth sessions-revoke-others [OPTIONS]

sov auth mfa-status

Show MFA enrollment status for the current user.

sov auth mfa-status [OPTIONS]

sov auth mfa-enroll

Start TOTP MFA enrollment (shows secret, URI, and backup codes once).

sov auth mfa-enroll [OPTIONS]

sov auth mfa-disable

Disable MFA (requires current TOTP code).

sov auth mfa-disable [OPTIONS]

sov auth project-login

Authenticate against the strict project login lane.

sov auth project-login [OPTIONS]

sov auth magic-link send

Send a magic-link sign-in email.

sov auth magic-link send [OPTIONS]

sov auth magic-link verify

Exchange a magic-link token for a session. Read the token from stdin or SOVARIA_MAGIC_TOKEN (never a CLI flag).

sov auth magic-link verify [OPTIONS]

sov auth verify-email send

Send a verification email to the authenticated user.

sov auth verify-email send [OPTIONS]

sov auth verify-email confirm

Confirm an email address using a verification token. Read the token from stdin or SOVARIA_VERIFY_EMAIL_TOKEN (never a CLI flag).

sov auth verify-email confirm [OPTIONS]

sov auth sessions-config get

Fetch the authenticated user's session policy.

sov auth sessions-config get [OPTIONS]

sov auth sessions-config set

Update the authenticated user's session policy.

sov auth sessions-config set [OPTIONS] {config_json}

sov auth providers-config get

Fetch auth provider runtime configuration.

sov auth providers-config get [OPTIONS]

sov auth providers-config set

Update auth provider toggles and external database link configuration.

sov auth providers-config set [OPTIONS] {config_json}

sov auth event-hooks list

List auth event hooks for the active project.

sov auth event-hooks list [OPTIONS]

sov auth event-hooks create

Create an auth event hook subscription.

sov auth event-hooks create [OPTIONS]

sov auth event-hooks delete

Delete an auth event hook.

sov auth event-hooks delete [OPTIONS] {hook_id}

sov auth github-state get

Fetch GitHub OAuth connection state.

sov auth github-state get [OPTIONS]

sov auth github-state disconnect

Disconnect GitHub OAuth broker state.

sov auth github-state disconnect [OPTIONS]

sov auth passkeys list

List passkeys registered for the current user.

sov auth passkeys list [OPTIONS]

sov auth passkeys revoke

Revoke a registered passkey.

sov auth passkeys revoke [OPTIONS] {passkey_id}

sov auth passkeys register-hint

Explain how to register a passkey (browser WebAuthn required).

sov auth passkeys register-hint [OPTIONS]

sov auth oidc list

List OIDC providers configured for the linked project.

sov auth oidc list [OPTIONS]

sov auth oidc create

Register an OIDC provider for the linked project.

sov auth oidc create [OPTIONS] {config}

sov auth oidc example

Print a starter OIDC provider config (Google-style example).

sov auth oidc example [OPTIONS]

sov auth oidc delete

Remove an OIDC provider.

sov auth oidc delete [OPTIONS] {provider_id}

sov auth oidc login-url

Get the OIDC authorization URL to start SSO in a browser.

sov auth oidc login-url [OPTIONS] {provider_id}

#sov auth-product

Your app's users (product auth).

sov auth-product users

List product users for the resolved org/project scope.

sov auth-product users [OPTIONS]

sov auth-product ban

Toggle a product user's active state in scope.

sov auth-product ban [OPTIONS] {user_id}

sov auth-product delete

Delete a product user credential in scope.

sov auth-product delete [OPTIONS] {user_id}

sov auth-product roles

Show a product user's app roles in scope.

sov auth-product roles [OPTIONS] {user_id}

sov auth-product roles-set

Replace a product user's app roles in scope.

sov auth-product roles-set [OPTIONS] {user_id} {roles}...

sov auth-product create

Create a product user in the current project scope.

sov auth-product create [OPTIONS]

#sov scope

Manage default org/project/env scope

sov scope show

Show currently configured default scope.

sov scope show [OPTIONS]

sov scope set

Persist default scope for future CLI calls.

sov scope set [OPTIONS] {org_id} {project_id}

sov scope clear

Clear default scope for the active profile.

sov scope clear [OPTIONS]

sov scope list

List organisations and projects available to your account.

sov scope list [OPTIONS]

sov scope pick

Pick default org/project interactively by index.

sov scope pick [OPTIONS]

#sov project

Project scaffold commands

sov project init-config

Create a template sovaria.config.json file.

sov project init-config [OPTIONS] [name]

sov project create

Create a project from sovaria.config.json.

sov project create [OPTIONS]

sov project status

Show local sovaria.config.json linkage and resolved scope.

sov project status [OPTIONS]

sov project link

Write org/project scope into sovaria.config.json and the active profile.

sov project link [OPTIONS]

sov project use

Set default scope for CLI commands (profile only, no config file write).

sov project use [OPTIONS] {org_id} {project_id}

sov project export

Export the full project data plane (Postgres dump + migration metadata). Bundle includes postgres.sql.gz (all schemas), manifest.json, storage-metadata.json, and RESTORE.md. Vault object bytes are not included — use sov storage download.

sov project export [OPTIONS]

#sov org

Organisation management

sov org create

Create a new organisation (or PROJECT/ENV) node in the identity graph. Example: sov org create "Acme Corp" sov org create "Payments" --type PROJECT --metadata '{"env": "prod"}'

sov org create [OPTIONS] {name}

sov org member-add

Add a user as a member of an organisation (creates a MEMBER_OF edge). Example: sov org member-add <org_id> <user_id> sov org member-add <org_id> <user_id> --role ADMIN

sov org member-add [OPTIONS] {org_id} {user_id}

#sov db

Database: run SQL, manage tables and apply migrations.

sov db tables

List live relational tables in the linked project database.

sov db tables [OPTIONS]

sov db sql

Execute SQL against Atlas-Rel. Use --interactive for a mini psql-style loop.

sov db sql [OPTIONS] [query]

sov db create-table

Create a new relational table.

sov db create-table [OPTIONS] {name} {columns_json}

sov db pull

Introspect remote SQL schema and write a migration SQL snapshot (Supabase db pull).

sov db pull [OPTIONS]

sov db diff

Compare remote schema against the last local snapshot from sov db pull.

sov db diff [OPTIONS]

sov db reset

Drop all user tables and optionally re-apply local migrations (destructive).

sov db reset [OPTIONS]

sov db seed

Run seed SQL against the linked database (Supabase db seed).

sov db seed [OPTIONS]

sov db tx begin

Begin a relational transaction and return txid.

sov db tx begin [OPTIONS]

sov db tx commit

Commit an open transaction.

sov db tx commit [OPTIONS]

sov db tx rollback

Rollback an open transaction.

sov db tx rollback [OPTIONS]

sov db column add

Add a column to an existing table.

sov db column add [OPTIONS] {table} {name}

sov db column drop

Drop a column from a table.

sov db column drop [OPTIONS] {table} {name}

sov db fk add

Add a foreign key between tables.

sov db fk add [OPTIONS] {table} {column}

sov db fk drop

Drop a foreign key.

sov db fk drop [OPTIONS] {table} {column}

sov db migrations new

Create a new timestamped SQL migration file (Supabase-style).

sov db migrations new [OPTIONS] {name}

sov db migrations list

List remote migration log entries or local migration files.

sov db migrations list [OPTIONS]

sov db migrations push

Apply pending .sql migrations through the project's migration history. Each file is applied atomically and recorded on the server, so every teammate and CI run sees the same history. Put rollback SQL under a -- migrate:down line (or in <name>.down.sql) to make a migration reversible with sov db migrations rollback.

sov db migrations push [OPTIONS]

sov db migrations rollback

Undo the most recent migration using its down SQL.

sov db migrations rollback [OPTIONS]

sov db migrations pull

Fetch remote migration log (schema change history) as JSON.

sov db migrations pull [OPTIONS]

#sov data

Atlas-Doc and Atlas-Rel data plane

sov data doc-put

Write a plain JSON document.

sov data doc-put [OPTIONS] {collection} {document_id} {data}

sov data doc-get

Read a plain JSON document.

sov data doc-get [OPTIONS] {collection} {document_id}

sov data doc-delete

Delete a document.

sov data doc-delete [OPTIONS] {collection} {document_id}

sov data doc-scan

Scan Atlas-Doc by prefix/range.

sov data doc-scan [OPTIONS]

sov data sql

Run SQL query through Atlas-Rel.

sov data sql [OPTIONS] {sql}

sov data table-create

Create a relational table.

sov data table-create [OPTIONS] {table_name} {columns}

sov data table-drop

Drop a relational table.

sov data table-drop [OPTIONS] {table_name}

sov data table-migrations

List migration log entries.

sov data table-migrations [OPTIONS]

#sov storage

Buckets and files.

sov storage buckets

List all storage buckets.

sov storage buckets [OPTIONS]

sov storage create-bucket

Create a new storage bucket.

sov storage create-bucket [OPTIONS] {name}

sov storage ls

List objects in a bucket.

sov storage ls [OPTIONS] {bucket}

sov storage upload

Upload a file to a bucket.

sov storage upload [OPTIONS] {bucket} {file_path}

sov storage download

Download an object to a local file.

sov storage download [OPTIONS] {bucket} {object_path}

sov storage sign-download

Mint a time-limited signed download URL.

sov storage sign-download [OPTIONS] {bucket} {object_path}

sov storage sign-upload

Mint a time-limited signed upload URL.

sov storage sign-upload [OPTIONS] {bucket} {object_path}

sov storage rm

Delete an object from a bucket.

sov storage rm [OPTIONS] {bucket} {object_path}

sov storage bucket-get

Fetch bucket metadata.

sov storage bucket-get [OPTIONS] {name}

sov storage bucket-update

Update bucket settings.

sov storage bucket-update [OPTIONS] {name}

sov storage bucket-delete

Delete a storage bucket and all objects.

sov storage bucket-delete [OPTIONS] {name}

sov storage move

Move or rename an object within storage.

sov storage move [OPTIONS]

#sov fn

Deploy, invoke, version and inspect functions.

sov fn deploy

Deploy a cloud function to the Forge engine. Example: sov deploy ./my-function --name greet --project proj-abc123

sov fn deploy [OPTIONS] [directory]

sov fn status

Check status of a Forge deployment.

sov fn status [OPTIONS] {deploy_id}

sov fn invoke

Invoke a deployed function via Forge sandbox runtime.

sov fn invoke [OPTIONS] {function_name}

sov fn versions

List deployment versions for one function.

sov fn versions [OPTIONS] {function_name}

sov fn history

List invocation history for one function.

sov fn history [OPTIONS] {function_name}

sov fn functions

List Forge functions with active versions and queue summary.

sov fn functions [OPTIONS]

sov fn jobs

List durable async jobs for a function.

sov fn jobs [OPTIONS] {function_name}

sov fn sim-diff

{right_invocation_id} Show unified diff between two simulation invocations.

sov fn sim-diff [OPTIONS] {function_name} {left_invocation_id}

sov fn promote

Promote a deployment/version to become active.

sov fn promote [OPTIONS] {function_name}

sov fn rollback

Rollback active function deployment to a previous version.

sov fn rollback [OPTIONS] {function_name}

sov fn logs

Fetch recent invocation logs for a function.

sov fn logs [OPTIONS] {function_name}

sov fn serve

Run a function locally with a hot HTTP server (Supabase functions serve).

sov fn serve [OPTIONS] [directory]

sov fn get

Get function metadata.

sov fn get [OPTIONS] {function_name}

sov fn delete

Delete a deployed function.

sov fn delete [OPTIONS] {function_name}

sov fn source

Fetch function source code.

sov fn source [OPTIONS] {function_name}

sov fn update

Patch function metadata and/or source.

sov fn update [OPTIONS] {function_name}

sov fn policy-get

Fetch function invoke policy.

sov fn policy-get [OPTIONS] {function_name}

sov fn policy-set

Replace function invoke policy.

sov fn policy-set [OPTIONS] {function_name} {policy_json}

sov fn bindings-get

Fetch function secret bindings.

sov fn bindings-get [OPTIONS] {function_name}

sov fn bindings-set

Replace function secret bindings.

sov fn bindings-set [OPTIONS] {function_name} {bindings_json}

sov fn github-repos

List GitHub repositories available for import. Optional PAT: set SOVARIA_GITHUB_TOKEN or authenticate with gh auth login.

sov fn github-repos [OPTIONS]

sov fn github-import

Import a function from a GitHub repository path. Optional PAT: set SOVARIA_GITHUB_TOKEN or authenticate with gh auth login.

sov fn github-import [OPTIONS]

sov fn github-commit

Commit local function source back to GitHub. Optional PAT: set SOVARIA_GITHUB_TOKEN or authenticate with gh auth login.

sov fn github-commit [OPTIONS]

#sov collections

NoSQL document collections

sov collections list

List document collections in the linked project.

sov collections list [OPTIONS]

#sov logs

API, auth, function and database logs.

sov logs api

Show recent API audit events (console Logs → API page).

sov logs api [OPTIONS]

#sov schema

Database schema introspection

sov schema describe

Describe relational tables and columns (information_schema).

sov schema describe [OPTIONS] [table]

#sov secrets

Function secrets (values are write-only).

sov secrets list

List secret bindings for a function (masked values).

sov secrets list [OPTIONS] {function}

sov secrets set

Set one secret binding on a function.

sov secrets set [OPTIONS] {function}

sov secrets unset

Remove a secret binding from a function.

sov secrets unset [OPTIONS] {function}

sov secrets import

Import secrets from a .env file or JSON bindings array.

sov secrets import [OPTIONS] {function} {file}

#sov gen

Generate types and client artifacts

sov gen types

Generate typed models from the live SQL schema (Supabase-style).

sov gen types [OPTIONS] {lang}

#sov chrono

Timeline and snapshot operations

sov chrono commit

Create a new chronon commit.

sov chrono commit [OPTIONS]

sov chrono timeline-list

List timelines.

sov chrono timeline-list [OPTIONS]

sov chrono timeline-spawn

Spawn a new timeline from a source head.

sov chrono timeline-spawn [OPTIONS] {name}

sov chrono timeline-delete

Delete a timeline.

sov chrono timeline-delete [OPTIONS] {name}

sov chrono timeline-jump

Force-jump a timeline to a specific head.

sov chrono timeline-jump [OPTIONS] {name}

sov chrono timeline-history

Show timeline history.

sov chrono timeline-history [OPTIONS] {name}

sov chrono topology

Show timeline topology graph.

sov chrono topology [OPTIONS]

sov chrono converge

Converge source timeline into target.

sov chrono converge [OPTIONS]

sov chrono variance

Calculate variance between chronons.

sov chrono variance [OPTIONS]

sov chrono snapshot-create

Create a Chrono snapshot.

sov chrono snapshot-create [OPTIONS]

sov chrono snapshot-list

List Chrono snapshots.

sov chrono snapshot-list [OPTIONS]

sov chrono snapshot-restore

Restore a snapshot by id.

sov chrono snapshot-restore [OPTIONS] {snapshot_id}

#sov audit

Echo audit trail and simulations

sov audit append

Append an immutable audit entry.

sov audit append [OPTIONS]

sov audit list

Query audit log entries.

sov audit list [OPTIONS]

sov audit verify

Verify audit hash-chain integrity.

sov audit verify [OPTIONS]

sov audit count

Return audit log entry count.

sov audit count [OPTIONS]

sov audit sim-run

Run an Echo phantom simulation.

sov audit sim-run [OPTIONS] {simulation_name} {operations}

sov audit sim-plan

Preview an Echo simulation plan.

sov audit sim-plan [OPTIONS] {simulation_name} {operations}

#sov policy

Project access policies.

sov policy templates

List built-in SPL policy templates.

sov policy templates [OPTIONS]

sov policy list

List active policies in scope.

sov policy list [OPTIONS]

sov policy get

Fetch a policy by ID.

sov policy get [OPTIONS] {policy_id}

sov policy upsert

Create or update a policy (tries create then update).

sov policy upsert [OPTIONS] {policy_id}

sov policy delete

Delete (deactivate) a policy.

sov policy delete [OPTIONS] {policy_id}

sov policy history

List policy version history.

sov policy history [OPTIONS] {policy_id}

sov policy rollback

Rollback policy to a historical version.

sov policy rollback [OPTIONS] {policy_id}