SDK Installation

VSKI ships two first-party SDKs: Python (vski-sdk, also the backbone of the vski CLI) and TypeScript/JavaScript (@vski/sdk). Both talk to the same REST API and realtime socket; pick your language below. The rest of the wiki uses Python examples.

Both packages are hosted on the VSKI package registry at vski.sh (neither is on PyPI/npmjs), so the one-time setup points your package manager at it.

Installation

pip

pip install vski-sdk --extra-index-url https://vski.sh/api/packages/x/pypi/simple/

npm

echo '@vski:registry=https://vski.sh/api/packages/x/npm/' >> .npmrc
npm install @vski/sdk

To avoid repeating the pip flag, add the index to pip.conf (~/.config/pip/pip.conf on Linux):

[global]
extra-index-url = https://vski.sh/api/packages/x/pypi/simple/

yarn and pnpm equivalents:

.yarnrc.yml

echo 'npmScopes:
  vski:
    npmRegistryServer: https://vski.sh/api/packages/x/npm/' >> .yarnrc.yml

# pnpm
pnpm config set '@vski:registry' https://vski.sh/api/packages/x/npm/

The Python command line ships as an extra: pip install "vski-sdk[cli]" (see Command Line).

Initialize Client

Python

from vski import VskiClient

async with VskiClient("http://127.0.0.1:3000") as client:
    # Authenticate as admin (also sets the client token)
    res = await client.admins.auth_with_password(
        "admin@yourdomain.com", "your-password"
    )

    records = await client.collection("posts").get_list(1, 20)

TypeScript

import { VskiClient } from "@vski/sdk";

const client = new VskiClient("http://127.0.0.1:3000");

// Authenticate as admin
const authRes = await client.admins.authWithPassword(
  "admin@yourdomain.com",
  "your-password",
);
client.setToken(authRes.token);

const records = await client.collection("posts").getList(1, 20);

With an API key instead of a login (CI, services):

Python

async with VskiClient("http://127.0.0.1:3000") as client:
    client.set_api_key("vski_...")

TypeScript

const client = new VskiClient("http://127.0.0.1:3000");
client.setApiKey("vski_...");

For scripts and synchronous Python there is a blocking wrapper with the same surface:

from vski.sync import SyncVskiClient

with SyncVskiClient("http://127.0.0.1:3000") as client:
    res = client.admins.auth_with_password("admin@yourdomain.com", "your-password")
    print(client.settings.databases.list())

Multi-Database Support

Python

tenant = client.db("tenant1")        # recommended: a database-scoped client
posts = await tenant.collection("posts").get_list(1, 20)

TypeScript

const tenant = client.db("tenant1");   // recommended
// client.setDb("tenant1");            // deprecated: switches the whole client

Available Packages

Language	Package	Notes
Python	vski-sdk	core client, workflows, plugin runtime, CLI extra
JS/TS	@vski/sdk	core client, workflow helpers (/functional, /worker)

CI/CD Configuration

GitHub Actions (Python)

- uses: actions/setup-python@v5
  with: {python-version: "3.12"}
- run: pip install vski-sdk --extra-index-url https://vski.sh/api/packages/x/pypi/simple/

npm CI

- run: echo '@vski:registry=https://vski.sh/api/packages/x/npm/' >> .npmrc
- run: npm ci

Troubleshooting

• Package not found (Python): the extra index is missing. Keep --extra-index-url https://vski.sh/api/packages/x/pypi/simple/ or the pip.conf entry.
• 404 installing @vski/sdk: the @vski scope is not pointed at the VSKI registry (.npmrc).
• Type errors after upgrade: the JS SDK types follow the server version closely; align @vski/sdk with your server release.