VectorAmp CLI

Official command-line interface for VectorAmp datasets, ingestion, semantic search, and Intelligence (RAG).

The binary is vectoramp, with the short alias va. Every command supports --json for machine-readable output, and exits non-zero on error.

Requirements

Node.js 18+
A VectorAmp API key (vsk_ followed by 64 hex characters)
Default API host: https://api.vectoramp.com

Install

npm install -g @vectoramp/cli

One-command installer:

curl -fsSL https://raw.githubusercontent.com/VectorAmp/vectoramp-cli/main/scripts/install.sh | bash

From source:

git clone https://github.com/VectorAmp/vectoramp-cli.git
cd vectoramp-cli
npm ci
npm run build
npm link

Configure

Authenticate with environment variables or local CLI config. The API key is the only required input.

export VECTORAMP_API_KEY=vsk_...                       # 64-hex API key
export VECTORAMP_BASE_URL=https://api.vectoramp.com    # optional

vectoramp config set --api-key vsk_...
vectoramp config set --base-url https://api.vectoramp.com
vectoramp config use ds_123        # set the active (default) dataset
vectoramp config show

Config is stored at ~/.config/vectoramp/config.json. The environment variables VECTORAMP_API_KEY, VECTORAMP_BASE_URL, and VECTORAMP_API_PREFIX override local config.

Unprefixed paths

The CLI talks to the public REST API on unprefixed paths (/datasets, /ingestion/jobs, …). The default API prefix is empty; the deprecated /v1 prefix is not used. You only need --api-prefix/VECTORAMP_API_PREFIX for an enterprise gateway that mounts the API elsewhere.

Quick start

A minimal, name-only flow — the API key comes from the environment:

# Create a dataset — name only is enough.
# Defaults: VectorAmp-Embedding-4B, dim 2560, cosine metric, SABLE index.
vectoramp datasets create docs

# Make it the active dataset, then add some text (embeds + inserts server-side).
vectoramp config use ds_123
vectoramp datasets add-texts "VectorAmp uses SABLE for billion-scale vector search."

# Search and ask.
vectoramp datasets search "how does SABLE work?" --top-k 5
vectoramp ask "Summarize this dataset" --dataset ds_123 --stream

Datasets

vectoramp datasets list --limit 50 --offset 0

# Minimal create (defaults: VectorAmp-Embedding-4B / dim 2560 / cosine / SABLE)
vectoramp datasets create docs

# OpenAI BYOM datasets — dimension is inferred (small = 1536, large = 3072)
vectoramp datasets create docs --openai small --metadata '{"team":"support"}'

# Hybrid dense + sparse dataset
vectoramp datasets create docs --hybrid

# Custom embedding model (dimension required — it cannot be inferred)
vectoramp datasets create docs --embedding-provider cohere --embedding-model embed-v3 --dim 1024

vectoramp datasets get ds_123
vectoramp datasets stats ds_123
vectoramp datasets delete ds_123 --yes

Dataset creation always requests SABLE; the CLI intentionally does not expose an index-type selector. The create body uses the dim field (not dimension). For built-in embeddings the dimension is inferred, so you only need --dim for unknown/custom models.

Search

datasets search takes a text query by default. --top-k defaults to 10.

# Text search
vectoramp --dataset ds_123 datasets search "refund policy" --top-k 5

# Reranked search (expands to the VectorAmp-Rerank-v1 rerank object)
vectoramp --dataset ds_123 datasets search "refund policy" --rerank

# Metadata filters (repeatable; values are coerced: true/false/numbers)
vectoramp --dataset ds_123 datasets search "tickets" --filter team=support --filter priority=2

# Hybrid (dense + sparse) search — --sparse implies --hybrid
vectoramp --dataset ds_123 datasets search "refund policy" --sparse refund --alpha 0.4

# Raw vector search — pass a JSON array of floats
vectoramp --dataset ds_123 datasets search anything --vector '[0.1,0.2,0.3]'

Vectors

Insert raw, pre-computed vectors. Integer ids stay JSON numbers on the wire (they are never coerced to strings).

# Single record
vectoramp --dataset ds_123 vectors insert --id 42 --values '[0.1,0.2,0.3]' --metadata '{"src":"docs"}'

# Batch — a JSON array of {id, values, metadata} records (string or integer ids)
vectoramp --dataset ds_123 vectors insert --vectors '[{"id":1,"values":[0.1,0.2]},{"id":"doc-2","values":[0.3,0.4]}]'

Add text

add-texts embeds with the dataset's model, copies the source text into metadata.text, then inserts — no separate embedding step.

vectoramp --dataset ds_123 datasets add-texts "VectorAmp uses SABLE for vector search."
vectoramp --dataset ds_123 datasets add-texts --file ./intro.md
vectoramp --dataset ds_123 datasets add-texts "one" "two" --metadata '{"team":"support"}'

Documents

Dataset document commands list and download retained source documents. Listing is cursor-paginated: pass the previous response's next_cursor as --cursor; do not use offset pagination. Storage keys are never printed. Omit --output to stream raw bytes to stdout.

# Preferred top-level form
vectoramp documents list ds_123 --limit 50 --status ready
vectoramp documents list ds_123 --cursor "$NEXT_CURSOR"
vectoramp documents download ds_123 doc_456 --output ./original.pdf

# Back-compat aliases under `datasets ...` also work
vectoramp datasets documents ds_123 --limit 50 --status ready
vectoramp datasets download-document ds_123 doc_456 --output ./overview.md

Documents with download_available: false can still have searchable chunks, but their original bytes are unavailable and download returns document_unavailable.

Organization secrets and vector deletion

Store external provider credentials as organization secrets, then reference the secret from datasets. The default OpenAI BYOM reference is emb:openai:api_key.

vectoramp secrets put emb:openai:api_key --env OPENAI_API_KEY

# Or save the secret while creating an OpenAI-backed dataset.
vectoramp datasets create openai-docs --openai small --openai-api-key-env OPENAI_API_KEY

# Delete individual vector ids from search.
vectoramp datasets delete-vectors ds_123 doc-001 42 --write-concern quorum --yes

Ingestion

Create reusable sources for every supported type, including Confluence. A positional URI is merged into the right config key for each type; --config JSON is layered on top.

vectoramp sources web https://docs.example.com --name docs-web --config '{"include_assets":true,"max_assets_per_page":5}'
vectoramp sources s3 s3://my-bucket/docs --config '{"region":"us-west-2"}'
vectoramp sources gcs gs://my-bucket/docs --config '{"prefix":"docs/","auth_mode":"oauth"}'
vectoramp sources gdrive google-folder-id
vectoramp sources gdrive google-folder-id --service-account-json ./sa.json    # headless auth
vectoramp sources gdrive google-folder-id --connection-id conn_123            # reusable connection (see below)
vectoramp sources jira --config '{"cloud_id":"...","projects":["ENG"],"include_comments":true}'
vectoramp sources confluence https://acme.atlassian.net --config '{"spaces":["ENG"],"username":"u","api_token":"t"}'
vectoramp sources file_upload --name "Local upload"

vectoramp sources list --limit 50
vectoramp sources get src_123

Create a source and start a job into the active dataset in one step. sources ingest creates the source, then starts a job via POST /ingestion/jobs:

vectoramp --dataset ds_123 sources ingest web https://docs.example.com --config '{"include_assets":true}'
vectoramp --dataset ds_123 sources ingest confluence https://acme.atlassian.net --config '{"spaces":["ENG"]}'

Local file ingestion

datasets ingest-files hides the entire presigned-upload flow: it auto-creates a file_upload source, initializes the upload, PUTs each file's bytes, completes the upload, then starts the ingestion job. It reads common text formats (.md, .mdx, .txt, .json, .jsonl, .csv, .tsv, .html, .xml, .yaml, .yml).

vectoramp --dataset ds_123 datasets ingest-files ./docs
vectoramp --dataset ds_123 datasets ingest-files ./docs --extensions md,txt --source-name "Product docs"
vectoramp --dataset ds_123 datasets ingest-files ./docs --source-id src_123

Manage and clean up sources

Validate a config, inspect what is using a source, delete it, or remove every source nothing is using.

vectoramp sources validate web https://docs.example.com           # check config without saving
vectoramp sources references src_123                              # schedules + active jobs using it
vectoramp sources delete src_123 --yes                            # 409 if in use…
vectoramp sources delete src_123 --force --yes                    # …--force deletes and disables its schedules
vectoramp sources unused                                          # list sources nothing is using
vectoramp sources cleanup --yes                                   # delete ALL unused sources

Connections (authenticated sources)

A connection is a stored OAuth grant you create once and reuse from many sources (gdrive, gcs, confluence, jira). For headless setups, prefer --service-account-json on the source instead.

# Create a grant, open the printed authorization_url in a browser, then poll until connected.
vectoramp connections create --provider google --source-type gdrive
vectoramp connections get conn_123                # repeat until status == connected
vectoramp connections list --provider google
vectoramp connections delete conn_123 --yes

# Then create the source against the connection:
vectoramp --dataset ds_123 sources ingest gdrive google-folder-id --connection-id conn_123

Jobs

vectoramp jobs list --dataset-id ds_123 --limit 50
vectoramp jobs get job_123                 # one-shot status
vectoramp jobs get job_123 --poll          # poll until completed/failed/cancelled
vectoramp jobs get job_123 --poll --interval 2000 --timeout 300000
vectoramp jobs retry job_123               # fresh full rerun of a failed/cancelled job

Schedules

Recurring ingestion schedules re-run a source into a dataset on a cron cadence.

vectoramp schedules list
vectoramp schedules get sch_1
vectoramp schedules create --source-id src_1 --dataset-id ds_1 --cron "0 0 * * *" --timezone UTC
vectoramp schedules update sch_1 --disable           # or --enable
vectoramp schedules update sch_1 --cron "0 */6 * * *"
vectoramp schedules trigger sch_1                    # run now, outside the cron cadence
vectoramp schedules delete sch_1 --yes

Ask (RAG)

# Defaults: top_k 5, include_sources true, dataset "all" when unscoped
vectoramp ask "What changed in the latest release?"
vectoramp ask "Summarize my dataset" --dataset ds_123 --stream
vectoramp ask "List open risks" --dataset ds_123 --top-k 12

A one-off ask is single-turn — each invocation stands alone with no memory of previous questions. For multi-turn follow-ups, use interactive mode (below).

Interactive mode

Run vectoramp with no subcommand to enter a slash-command REPL. The session opens with a [ VectorAmp ] banner showing the working directory and active dataset; the prompt itself shows the active dataset (VectorAmp:ds_123 ›). In non-TTY environments it falls back to a plain line reader.

╭────────────────────────────────────────╮
│              [ VectorAmp ]             │
│                                        │
│ cwd ~/work/product-docs                │
│ ctx active dataset: ds_123             │
╰────────────────────────────────────────╯

Type / for commands. Plain text asks Intelligence.

Interactive commands:

/help                     Show interactive commands
/datasets                 Pick an active dataset from a filterable list
/use <dataset-id>         Switch directly to a dataset by id
/context (/status)        Show the active dataset and working directory
/search <query>           Semantic search in the active dataset
/add-texts <text>         Add inline text to the active dataset
/ingest-files <path>      Upload local text files into the active dataset
/ask <question>           Ask Intelligence (keeps multi-turn context)
/reset (/new)             Clear the conversation history
/sources <type> <uri>     Create an ingestion source
/config                   Show resolved local CLI config
/exit (/quit)             Leave interactive mode

Niceties:

Type / to show a filtered command palette with commands and descriptions.
Use ↑/↓ to move the highlighted command; press Tab or Enter to complete it.
Once a full command plus a trailing space is typed, the palette hides so arguments can be entered cleanly.
/datasets fetches datasets and opens a filterable picker with UUID and name columns.
Plain text without a leading slash is treated as /ask against the active dataset.

Multi-turn conversations

The Intelligence API is stateless, so follow-up questions need prior turns sent as context. Interactive mode keeps the running conversation and sends a window of recent messages with each follow-up, so a question like "and why is that?" resolves against earlier turns. Use --history <n> to control how many prior messages are included (default 10), and /reset (or /new) to clear the conversation. Switching datasets (/use, /datasets) also resets the conversation.

vectoramp --history 6
#   ask a question, then a follow-up that depends on the previous answer
#   /reset clears the conversation, /help lists commands

Programmatic use

The package also exports a typed client and source helpers for embedding the same behavior in scripts. Prefer the object → method flow: create a dataset, then operate through the returned id.

import { VectorAmpClient, confluenceSource } from '@vectoramp/cli';

const client = new VectorAmpClient({
  apiKey: process.env.VECTORAMP_API_KEY!,
  baseUrl: 'https://api.vectoramp.com',
  apiPrefix: '',
});

const dataset = await client.createDataset({ name: 'docs', hybrid: true });
await client.addTexts(dataset.id, ['VectorAmp uses SABLE.']);
await client.search(dataset.id, 'how does SABLE work?', { topK: 5, rerank: true });
await client.ingestSource(dataset.id, confluenceSource({ cloudId: 'cid', spaces: ['ENG'] }));

Source helpers exported from @vectoramp/cli: webSource, s3Source, gcsSource, googleDriveSource, jiraSource, confluenceSource, fileUploadSource, and the generic source({ sourceType, config }) escape hatch.

Command reference

Global options apply to every command: --api-key <key>, --base-url <url>, --api-prefix <prefix>, -d, --dataset <id>, --history <n> (interactive, default 10), --json.

Datasets

Command	Required	Optional (defaults)
`datasets list`	—	`--limit`, `--offset`
`datasets create <name>`	`name`	`--dim` (inferred for built-in models), `--metric` (cosine), `--openai <small\|large>`, `--embedding-provider`, `--embedding-model`, `--hybrid`, `--metadata <json>`. `index_type` is always `sable`.
`datasets get <id>`	`id`	—
`datasets stats <id>`	`id`	—
`datasets delete <id>`	`id`	`-y, --yes` (required to confirm)
`datasets search <query…>`	`query` (or `--vector`) + active dataset	`-k, --top-k` (10), `--rerank`, `--filter k=v` (repeatable), `--vector <json-array>`, `--hybrid`, `--sparse <text>`, `--alpha <n>`, `--dataset`
`datasets add-texts <texts…>`	text(s) or `--file` + active dataset	`--file <path>`, `--metadata <json>`, `--dataset`
`datasets ask <question…>`	`question` + active dataset	`--stream`, `-k, --top-k`, `--dataset`
`datasets ingest-files <path>`	`path` + active dataset	`--extensions <list>`, `--max-bytes-per-file <n>`, `--source-id <id>`, `--source-name <name>`, `--dataset`

Vectors

Command	Required	Optional
`vectors insert`	active dataset + (`--values` or `--vectors`)	`--id <id>` (string or integer), `--values <json>`, `--metadata <json>`, `--vectors <json>` (array of records), `--dataset`

Documents

Command	Required	Optional
`documents list <dataset>` (alias `docs`)	`dataset`	`--limit`, `--cursor`, `--status`
`documents download <dataset> <document-id>`	`dataset`, `document-id`	`-o, --output <path>`
`datasets documents <id>` / `datasets download-document <id> <document-id>`	(back-compat aliases of the above)	same

Sources

Command	Required	Optional
`sources <web\|s3\|gcs\|gdrive\|jira\|confluence\|file_upload> [uri]`	source type	`[uri]` positional, `--name`, `--config <json>`, `--service-account-json <path>`, `--connection-id <id>`
`sources ingest <type> <uri>`	`type`, `uri` + active dataset	`--config <json>`, `--service-account-json <path>`, `--connection-id <id>`, `--pipeline-id`, `--dataset`
`sources list`	—	`--limit`, `--offset`
`sources get <source-id>`	`source-id`	—
`sources validate <type> [uri]`	`type`	`[uri]` positional, `--config <json>`
`sources references <source-id>`	`source-id`	—
`sources delete <source-id>`	`source-id`	`--force`, `-y, --yes`
`sources unused`	—	`--limit`, `--offset`
`sources cleanup`	—	`-y, --yes`

Connections

Command	Required	Optional
`connections list`	—	`--provider <google\|atlassian>`
`connections create`	`--provider <google\|atlassian>`	`--source-type <type>` (prints `authorization_url`)
`connections get <connection-id>`	`connection-id`	— (poll until `status` is `connected`)
`connections delete <connection-id>`	`connection-id`	`-y, --yes`

Jobs

Command	Required	Optional
`jobs list`	—	`--dataset-id`, `--limit`, `--offset`
`jobs get <job-id>`	`job-id`	`--poll`, `--interval <ms>`, `--timeout <ms>`
`jobs retry <job-id>`	`job-id`	—

Schedules

Command	Required	Optional
`schedules list`	—	`--limit`, `--offset`
`schedules get <schedule-id>`	`schedule-id`	—
`schedules create`	`--source-id`, `--dataset-id`, `--cron`	`--timezone`, `--pipeline-id`, `--no-enabled`, `--name`, `--metadata <json>`
`schedules update <schedule-id>`	`schedule-id` + ≥1 field	`--cron`, `--timezone`, `--pipeline-id`, `--enable`/`--disable`, `--name`, `--metadata <json>`
`schedules delete <schedule-id>`	`schedule-id`	`-y, --yes`
`schedules trigger <schedule-id>`	`schedule-id`	—

Intelligence and config

Command	Required	Optional
`ask <question…>`	`question`	`--stream`, `-k, --top-k`, `--dataset` (defaults to `all` when unscoped)
`config show`	—	—
`config set`	—	`--api-key`, `--base-url`, `--api-prefix`, `--dataset`
`config use <dataset>`	`dataset`	—

Development

npm ci
npm run typecheck
npm test
npm run build

License

Licensed under the Apache License, Version 2.0. See LICENSE and NOTICE.

Requirements​

Install​

Configure​

Quick start​

Datasets​

Search​

Vectors​

Add text​

Documents​

Organization secrets and vector deletion​

Ingestion​

Local file ingestion​

Manage and clean up sources​

Connections (authenticated sources)​

Jobs​

Schedules​

Ask (RAG)​

Interactive mode​

Multi-turn conversations​

Programmatic use​

Command reference​

Datasets​

Vectors​

Documents​

Sources​

Connections​

Jobs​

Schedules​

Intelligence and config​

Development​

License​

Requirements

Install

Configure

Quick start

Datasets

Search

Vectors

Add text

Documents

Organization secrets and vector deletion

Ingestion

Local file ingestion

Manage and clean up sources

Connections (authenticated sources)

Jobs

Schedules

Ask (RAG)

Interactive mode

Multi-turn conversations

Programmatic use

Command reference

Datasets

Vectors

Documents

Sources

Connections

Jobs

Schedules

Intelligence and config

Development

License