Reference

CLI usage

The same vektor binary that runs the server is also a full command-line client. Authenticate once, then read, write, search, and automate documents, categories, spaces, and workflows from your terminal.

Browse documentation

Getting started

Reference

Operations

Metrics endpoint

Changelog

Latest updates

Every command follows the shape vektor [--space <id>] <command> [args]. Run vektor --help at any time for the full list, or vektor --version to print the installed version.

Running the server

However you installed it, start the server with vektor serve. It listens on port 8080 by default. A few useful flags:

Terminal

vektor serve [--port <port>] [--host <host>] [--no-auth] [--in-memory] [--email-auth]

--port <port>: port to listen on (default 8080).
--host <host>: bind address (e.g. 0.0.0.0 to accept external traffic).
--no-auth: disable authentication. Handy for local trials; never use in production.
--email-auth: enable email/password sign-in.
--in-memory: use an ephemeral in-memory database that is discarded on exit.

Configuration

Configuration is supplied through environment variables (an env file works well with Docker Compose). A typical production file, with SSO, Google sign-in, mail, and a reverse proxy in front:

env

# ── Origins and process ───────────────────────────────────────────────────────
VEKTOR_SITE_URL=https://vektor.example.com
NODE_ENV=production
HOST=0.0.0.0

# ── Database ──────────────────────────────────────────────────────────────────
VEKTOR_DATABASE_URL=file:./data/auth.db

# ── Authentication and secrets ────────────────────────────────────────────────
AUTH_SECRET=change-me
AUTH_LOGIN=false
VEKTOR_SECRETS_ENCRYPTION_KEY=base64-encoded-32-byte-key

# ── OAuth2 / SSO ──────────────────────────────────────────────────────────────
OAUTH_PROVIDER_ID=sso
OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret
OAUTH_SCOPES=email,profile,openid,offline_access
OAUTH_AUTHORIZATION_URL=https://sso.example.com/oauth/authorize
OAUTH_TOKEN_URL=https://sso.example.com/oauth/token
OAUTH_USERINFO_URL=https://sso.example.com/oauth/userinfo
OAUTH_GROUP_SYNC_INTERVAL=60
VEKTOR_ADMIN_GROUPS=vektor-admins
VEKTOR_SPACE_CREATION_GROUPS=space-admins,platform-team

# ── Google sign-in ────────────────────────────────────────────────────────────
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-google-client-secret

# ── Email notifications (SMTP) ────────────────────────────────────────────────
VEKTOR_EMAIL_FROM="Vektor <updates@notifications.example.com>"
VEKTOR_SMTP_HOST=smtp.example.com
VEKTOR_SMTP_PORT=465
VEKTOR_SMTP_SECURE=true
VEKTOR_SMTP_USER=your-smtp-user
VEKTOR_SMTP_PASSWORD=your-smtp-password

# ── Proxying, limits, and rate limiting ───────────────────────────────────────
VEKTOR_TRUST_PROXY=1
VEKTOR_MAX_REQUEST_BYTES=10485760
VEKTOR_RATE_LIMIT=1
VEKTOR_RATE_LIMIT_MAX=600
VEKTOR_RATE_LIMIT_WINDOW=60

# ── Observability ─────────────────────────────────────────────────────────────
OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318
OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer%20xxx
OTEL_SERVICE_NAME=vektor

Server environment variables

Every variable the server reads, including the ones the example leaves out. Only AUTH_SECRET and VEKTOR_SITE_URL are needed to boot; everything else has a default or turns a feature off when unset.

Origins and process

Variable	Description
`VEKTOR_SITE_URL`	Public origin as seen in the browser. Absolute links and the default OAuth redirect URIs are built from it.
`VEKTOR_API_URL`	Development only. Points the frontend at an API on a different origin; in a normal deployment both are served from VEKTOR_SITE_URL.
`VEKTOR_COLLABORATION_HOST`	Development only. Host (and port) the browser opens the realtime sync connection to; it falls back to the API origin.
`VEKTOR_DEFAULT_SPACE`	Space that the root path / redirects to.
`HOST`	Interface the HTTP server binds to. Default: 0.0.0.0. The port comes from serve --port.
`VEKTOR_API_ONLY`	1/true skips the Astro frontend and serves only the API.
`NODE_ENV`	Set to production to enable production-only warnings, such as the derived-secrets-key one below. Default: development

Database

Variable	Description
`VEKTOR_DATABASE_URL`	The scheme picks the mode: file: for local storage, libsql:/https: for hosted libSQL, with remote credentials in the authToken query parameter. Default: file:./data/auth.db
`VEKTOR_IN_MEMORY_DB`	1 discards the database on exit. Pair with VEKTOR_NO_AUTH=1 for a throwaway server.

Authentication and secrets

Variable	Description
`AUTH_SECRET`	better-auth signing secret. Required whenever auth is enabled.
`VEKTOR_NO_AUTH`	1 disables authentication entirely. Local trials only — never in production.
`AUTH_LOGIN`	false hides the email/password form, leaving only the configured SSO providers.
`VEKTOR_EMAIL_AUTH`	1 enables email/password sign-in, same as serve --email-auth. Always on in dev.
`VEKTOR_REQUIRE_EMAIL_VERIFICATION`	1 requires a verified address before an email/password account may sign in.
`VEKTOR_SECRETS_ENCRYPTION_KEY`	Encrypts stored space secrets. Must decode to exactly 32 bytes, base64 or raw utf-8 — generate one with openssl rand -base64 32. Falls back to a key derived from AUTH_SECRET, which logs a warning in production.

OAuth2 / SSO

Variable	Description
`OAUTH_PROVIDER_ID`	Identifier for the generic OAuth2 provider (e.g. sso). Also gates whether the SSO button renders.
`OAUTH_CLIENT_ID`
`OAUTH_CLIENT_SECRET`
`OAUTH_SCOPES`	Comma-separated. Include offline_access so group re-reads survive the sign-in token expiring.
`OAUTH_AUTHORIZATION_URL`
`OAUTH_TOKEN_URL`
`OAUTH_USERINFO_URL`	Also used for the periodic group re-read.
`OAUTH_REDIRECT_URI`	Defaults to a callback path under VEKTOR_SITE_URL.
`OAUTH_GROUP_SYNC_INTERVAL`	Seconds a group claim may age before the next re-read. 0 turns re-reads off, leaving group changes to land at the next sign-in. Default: 60
`VEKTOR_SPACE_CREATION_GROUPS`	Comma-separated group ids allowed to create their own spaces. Unset, every signed-in user may; set but matching no usable group, nobody may.
`VEKTOR_ADMIN_GROUPS`	Comma-separated group ids that administer the instance — owner on every space, which is what allows listing and deleting spaces they do not belong to. Unset means nobody.

Google sign-in

Variable	Description
`GOOGLE_CLIENT_ID`	With the secret also set, a “Continue with Google” button appears on the login screen.
`GOOGLE_CLIENT_SECRET`	Never reaches the browser — only a boolean flag does.
`GOOGLE_REDIRECT_URI`	Default: <VEKTOR_SITE_URL>/api/auth/callback/google

Email notifications (SMTP)

Variable	Description
`VEKTOR_EMAIL_FROM`	Delivery stays disabled until both this and VEKTOR_SMTP_HOST are set.
`VEKTOR_SMTP_HOST`
`VEKTOR_SMTP_PORT`
`VEKTOR_SMTP_SECURE`	true/1 for implicit TLS (port 465), 0 for STARTTLS.
`VEKTOR_SMTP_USER`
`VEKTOR_SMTP_PASSWORD`

Proxying, limits, and rate limiting

Variable	Description
`VEKTOR_TRUST_PROXY`	1/true only when a trusted reverse proxy fronts the app; X-Forwarded-* headers are honored only then.
`VEKTOR_MAX_REQUEST_BYTES`	Applies to buffered API request bodies.
`VEKTOR_RATE_LIMIT`	0/false turns API rate limiting off entirely. On by default, and expensive routes — search rebuild, chat completions, job and workflow runs, link previews, media proxy, uploads — carry tighter built-in limits that the two settings below cannot raise.
`VEKTOR_RATE_LIMIT_MAX`	Requests per window on routes without a tighter built-in rule. Default: 600
`VEKTOR_RATE_LIMIT_WINDOW`	Seconds. Default: 60
`VEKTOR_RATE_LIMIT_BLOCK`	Killswitch: comma-separated keys exactly as the 429 log line prints them (ip:<addr>, token:<hash>). Those callers are refused without being counted.

Jobs and extensions

Variable	Description
`VEKTOR_JOB_RUNTIME`	Runtime that executes extension jobs and workflow scripts. Only boa ships today, and there is no unsandboxed path. Default: boa
`VEKTOR_JOB_FETCH_ALLOW_PRIVATE`	1 lets job fetch and AI provider base URLs reach loopback and private ranges — needed for a self-hosted Ollama, but that is also where the internal API, the database and cloud metadata endpoints live, and a space owner can then aim the server at any internal host. Off by default.
`VEKTOR_EXTENSION_ALLOWED_SOURCES`	Comma-separated: upload, marketplace, system. All sources when unset.

Avatars

Variable	Description
`VEKTOR_GRAVATAR_URL`	Gravatar-compatible API, queried as <host>/avatar/<email-hash> for users whose login provider supplied no picture. Unset means no lookup — enabling it discloses an email hash and viewer IPs to that host.

Observability (OpenTelemetry)

Variable	Description
`OTEL_EXPORTER_OTLP_ENDPOINT`	Collector base URL for OTLP/HTTP log export; /v1/logs is appended. Logs keep going to stdout/stderr either way.
`OTEL_EXPORTER_OTLP_HEADERS`	k1=v1,k2=v2, percent-decoded — e.g. an ingest token.
`OTEL_SERVICE_NAME`	Reported as service.name. Default: vektor

Authentication

vektor login starts a browser-based OAuth flow. It spins up a temporary local callback server, opens your browser to authorize, and prints the environment variables to export when it completes:

Terminal

vektor login

After authorizing, export the values it prints so subsequent commands are authenticated:

Terminal

export VEKTOR_HOST=https://vektor.example.com
export VEKTOR_SPACE_ID=<space-id>
export VEKTOR_ACCESS_TOKEN=<token>

CLI environment variables

The CLI client is configured entirely through the environment. These are the only variables it needs — the server settings above do not apply to it:

Variable	Description
`VEKTOR_HOST`	Server URL the CLI talks to. Default: http://localhost:8080
`VEKTOR_SPACE_ID`	Space to operate on. Defaults to the first space the token has access to.
`VEKTOR_ACCESS_TOKEN`	API token used to authenticate requests (and by vektor mcp).
`VEKTOR_DATABASE_URL`	Auth database URL. Default: file:./data/auth.db

Working with documents

Read, create, update, and search documents in the active space.

Terminal

# list documents (newest first)
vektor ls [--limit <n>]

# print a document's content to stdout
vektor cat <docId>

# full-text / semantic search
vektor query <query>

vektor write creates a new document or overwrites an existing one. Pass a file, or pipe content on stdin with -:

Terminal

# create a new document from a file
vektor write ./notes.md --title "Release notes" --category changelog

# create from stdin
echo "# Hello" | vektor write - --title "Greeting"

# overwrite an existing document by id
vektor write <docId> ./notes.md

vektor set updates a document's properties, title, category, or parent:

Terminal

# set custom key/value properties
vektor set <docId> status=published owner=alice

# remove a property with a leading dash
vektor set <docId> -owner

# move a document under a new parent (or to the root with -)
vektor set <docId> --parent <parentDocId>
vektor set <docId> --parent -

Uploads

Upload a file and get back a URL, optionally attaching it to a document:

Terminal

vektor upload ./diagram.png --filename diagram.png --document <docId>

# emit JSON for scripting
vektor upload ./diagram.png --json

Spaces

Terminal

vektor space ls
vektor space register <libsql-url>
vektor space attach <libsql-url>
vektor space enable <database-id>

Workflows

Run sandboxed JavaScript workflow documents and inspect their logs:

Terminal

# run a workflow, passing inputs as key=value
vektor workflow run <docId> --input branch=main --input dryRun=true

# emit the full result as JSON
vektor workflow run <docId> --json

# fetch the logs for a previous run
vektor workflow logs <runId>

Extensions

Scaffold, package, and publish extensions to your workspace:

Terminal

# scaffold a new extension
vektor extension create my-extension

# package an extension into a distributable bundle
vektor extension package my-extension

# upload a packaged extension to the server
vektor extension upload my-extension

Agent

vektor agent runs an AI agent against your workspace, optionally scoped to a single document:

Terminal

# start an interactive agent session
vektor agent

# run a single prompt against a specific document and exit
vektor agent "Summarize the open questions" --doc <slug|id> --once

MCP server

vektor mcp starts a Model Context Protocol server so tools like Claude and Cursor can read and search your documents. It authenticates with VEKTOR_ACCESS_TOKEN:

Terminal

vektor mcp

CLI usage

Running the server

Configuration

Server environment variables

Origins and process

Database

Authentication and secrets

OAuth2 / SSO

Google sign-in

Email notifications (SMTP)

Proxying, limits, and rate limiting

Jobs and extensions

Avatars

Observability (OpenTelemetry)

Authentication

CLI environment variables

Working with documents

Uploads

Categories

Spaces

Workflows

Extensions

Agent

MCP server