Skip to content
VSKI

Command Line

The vski command-line tool manages VSKI deployments: databases, collections, records, migrations, pipelines, cron, webhooks, secrets, plugins, plus the declarative IaC workflow (plan / apply / pull).

It ships with the Python SDK:

Terminal window
pip install vski-sdk[cli] --extra-index-url https://vski.sh/api/packages/x/pypi/simple/

The command line tool is the successor to the minimal Deno CLI that shipped with @vski/sdk (login / db / migrate); that one is deprecated.

Configuration

Section titled “Configuration”

Every command resolves its target deployment and credentials the same way (highest precedence first):

  1. CLI flags: --url, --api-key, --token, --db
  2. Environment variables: VSKI_URL, VSKI_API_KEY, VSKI_TOKEN, VSKI_DB
  3. A .env file in the working directory (or --env-file path); values there never override real environment variables
  4. The login config file ~/.vski/config.json (written by vski login; override its location with VSKI_CONFIG)
Terminal window
export VSKI_URL=https://vski.example.com
export VSKI_API_KEY=vski_...     # mint with `vski keys create` (below)


vski status                       # health + effective config

Two credential kinds:

  • API keys (recommended for CI and day-to-day devops). Minted once by an admin: vski keys create ci --roles admin (roles are comma-separated; an admin-role key can do everything, a workflows-role key only pipelines/secrets). The raw key is shown exactly once.
  • Admin JWT via vski login (prompts for email/password, stores the token in ~/.vski/config.json); vski logout clears it.

Global flags: --json (machine-readable output for every command), --yes/-y (skip confirmations), --db/-d (default database), --env-file.

Local lifecycle

Section titled “Local lifecycle”

The quickest path from zero to a running local server is the command line tool itself (see Getting Started):

vski install                     # docker pull vski.sh/x/vski:latest-standalone
vski serve [port] [data-dir]     # docker run; defaults: 3000, ~/.vski/data
vski doctor                      # check env: server, auth, docker, local image
vski init [dir]                  # bootstrap a project from the app template
vski setup [dir]                 # scaffold a minimal declarative project (./vski)
  • vski install [--light] [--tag v0.15.1] pulls the server image. The default is the standalone image (with the embedded web UI); --light gets the API-only one, --tag a specific release.
  • vski serve 3000 runs it in the foreground (Ctrl-C stops the container); --detach/-d runs it in the background with a restart policy and prints the URL. A JWT_SECRET is generated once into ~/.vski/serve.env and reused, so tokens survive restarts. --name, --image and repeatable --env KEY=VAL cover the rest of the common docker run options.
  • vski doctor prints a checklist (server reachability, credentials, docker, local image, SDK version) and exits non-zero when something essential is broken; --json emits it structured.
  • vski init clones the app template (a declarative deployment, a demo plugin, a docker-compose stack, an e2e suite; see Project Boilerplate) into dir without its .git. --ref picks a tag, --from a different URL or a local path.
  • vski setup writes a starter vski/ directory only (a working notes collection plus commented pipeline / cron / secrets examples) that loads through the strict IaC validator, ready for vski plan and vski apply.

Commands

Section titled “Commands”
vski login | logout | whoami | status


vski db list | create <name> | rm <name>
vski collections list | show <name> | rm <name>          # --db scopes
vski records list | get | create | update | rm | search  # dev convenience
vski sql exec "<sql>" | sql query <name>
vski migrations list | status | generate | apply <ver> | rollback <ver>
                        | upload <file> | export | rm <ver>
vski pipelines list | show | validate <file> | run <name> | rm
vski pipelines tokens list | create | rm                  # public trigger tokens
vski pipelines trigger <ptk_...>
vski runs list | show | events | cancel                   # workflow + pipeline runs
vski cron list | rm
vski webhooks list | rm | trigger | logs
vski graphs list | show | stats | rm
vski secrets list | set <name> <value|-> | rm
vski plugins list | scan
vski plugins instances list | show | start | stop | restart | invoke | logs | rm
vski keys create <name> --roles admin
vski replicas list


vski init | install | serve | doctor | setup              # local lifecycle (above)
vski plan [dir] | vski apply [dir] | vski pull [dir]      # IaC; see the IaC page

Notes:

  • Collection creation is deliberately not an imperative command: schema changes go through migrations or the IaC apply flow so every change is reviewable and rollback-able.
  • vski plan exits 2 when the deployment drifts from the desired state (0 = clean, 1 = error), a drop-in CI gate, like terraform plan -detailed-exitcode.
  • The app template wires the IaC commands into its Makefile (make iac-plan / iac-apply / iac-pull).