CLI: install, sign in and work
Install sovaria-cli, sign in (browser, email or CI tokens), choose the organization and project, link a folder, everyday workflows, output for scripts, exit codes and troubleshooting.
Install
pipx install sovaria-cli
sov --versionPython 3.11 or newer. The command is sov. This page and the CLI reference describe the current CLI; run pipx upgrade sovaria-cli if a command is missing.
Sign in
| How | Command | Use |
|---|---|---|
| Browser | sov login | Your own machine. Opens the console to approve the sign-in. |
sov login --email you@example.com (password from the prompt or SOVARIA_PASSWORD) | Machines without a browser. | |
| Token or key | SOVARIA_ACCESS_TOKEN or SOVARIA_API_KEY in the environment | CI — no login step, nothing stored. |
The session is stored in your OS keyring (or ~/.sovaria/credentials.toml, readable only by you, with --file-storage). sov whoami shows who you are; sov logout signs out.
Choose the project
sov scope pick # choose organization and project interactively
sov scope show
sov init # in a project folder: pick and write sovaria.config.json
sov link # link this folder to an existing projectCommands use, in order: flags (--org, --project), the folder's sovaria.config.json, then the scope from sov scope set. Commit sovaria.config.json — it holds ids and the URL, no secrets.
Everyday workflows
| Task | Commands |
|---|---|
| Run SQL | sov db sql "select count(*) from orders" |
| Migrations | sov db migrations new add_reviews → edit → sov db migrations push --dry-run → sov db migrations push (Migrations) |
| Pull the live schema | sov db pull, sov db diff |
| Generate types | sov gen types |
| Functions | sov fn serve (run locally) → sov fn deploy → sov fn logs <name> (Deploying and running functions) |
| Access checks | sov policy check …, sov rules test, sov sim run --fail-on critical (CI/CD) |
| Storage | sov storage upload, sov storage ls |
| Keys | sov keys list, sov keys create, sov keys revoke |
In scripts
--json(orSOV_JSON=1) prints raw JSON forjqand other tools.SOV_DEBUG=1shows full error traces.- Exit codes:
0success;1a request failed or a check found problems (failing rules tests, simulation findings at--fail-on);2invalid usage or input.
Troubleshooting
| Message | Fix |
|---|---|
| Not signed in / session expired | sov login again, or set SOVARIA_ACCESS_TOKEN in CI. |
| No project selected | sov scope pick, sov link, or pass --project. |
403 on a command | Your member role doesn't allow it (Organizations, members and roles) or a plan limit applies. |
No such command | Upgrade: pipx upgrade sovaria-cli. |
| Keyring errors on a server | Use sov login --file-storage, or environment variables. |
Something unclear or missing on this page?Tell us