VectorAmp CLI

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

• Binary: vectoramp with short alias va
• Node.js 18+
• Auth via VECTORAMP_API_KEY or local config
• Default API: https://api.vectoramp.com
• Dataset creation is SABLE-only; the CLI always sends index_type: sable
• Every command supports --json for machine-readable output

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

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                 # default dataset
vectoramp config show

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

Quick start

# Create a dataset — name only is enough (VectorAmp-Embedding-4B, dim 2560, cosine, SABLE)
vectoramp datasets create docs

# Make it the active dataset, then add some text
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" --stream

Datasets

vectoramp datasets list --limit 50

# Minimal create: omit embedding flags to use VectorAmp's managed default
# (VectorAmp-Embedding-4B / dim 2560 / cosine / SABLE).
vectoramp datasets create docs

# Optional BYOM examples when you intentionally want a non-default embedding model.
# OpenAI dimensions are inferred (small = 1536, large = 3072).
vectoramp datasets create openai-docs --openai small --metadata '{"team":"support"}'
vectoramp datasets create openai-docs --openai small --openai-api-key-env OPENAI_API_KEY
vectoramp datasets create custom-docs --embedding-provider cohere --embedding-model embed-v3 --dim 1024
vectoramp datasets create docs --hybrid           # enable dense + sparse hybrid search
vectoramp datasets create docs --dim 768 --metric dot

# Declare typed metadata at creation. Supported types: string, u32, i32, i64, f32, f64.
vectoramp datasets create products --metadata-schema '[{"name":"price","type":"f32"},{"name":"category","type":"string"}]'

# Merge fields into the schema, or replace it completely.
vectoramp datasets schema-patch ds_123 '[{"name":"created_at","type":"i64"}]'
vectoramp datasets schema-replace ds_123 '[{"name":"category","type":"string"}]'

vectoramp datasets get ds_123
vectoramp datasets stats ds_123
vectoramp datasets delete-vectors ds_123 doc-001 42 --write-concern quorum --yes
vectoramp datasets delete ds_123 --yes

index_type is always forced to sable and is never accepted from the caller. The create body uses the dim field (not dimension). For most datasets, omit embedding flags and use the managed VectorAmp embedding model.

Search

# Text search (top_k defaults to 10)
vectoramp --dataset ds_123 datasets search "refund policy" --top-k 5

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

# Metadata filters (repeatable)
vectoramp --dataset ds_123 datasets search "tickets" --filter team=support --filter priority=2

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

# Raw vector search
vectoramp --dataset ds_123 datasets search anything --vector '[0.1,0.2,0.3]'

Organization secrets

Store provider credentials as organization secrets. The CLI sends the plaintext once; VectorAmp stores it server-side and future dataset operations reference the secret name.

# Default OpenAI BYOM secret reference used by SDKs and docs
vectoramp secrets put emb:openai:api_key --env OPENAI_API_KEY
vectoramp secrets put emb:openai:api_key --file ./openai-key.txt

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

Vectors

# Insert a single raw vector. Integer ids stay JSON numbers on the wire.
vectoramp --dataset ds_123 vectors insert --id 42 --values '[0.1,0.2,0.3]' --metadata '{"src":"docs"}'

# Insert a batch
vectoramp --dataset ds_123 vectors insert --vectors '[{"id":1,"values":[0.1,0.2]},{"id":"doc-2","values":[0.3,0.4]}]'

# Delete selected vector ids from search
vectoramp datasets delete-vectors ds_123 1 doc-2 --yes

Documents

Document listing uses cursor pagination. Pass the response next_cursor back with --cursor; do not assume offsets or totals. Downloads write retained original bytes and follow API/storage redirects. Omit --output to stream bytes to stdout.

vectoramp documents list ds_123 --limit 50 --status ready
vectoramp documents list ds_123 --cursor eyJpZCI6...
vectoramp documents download ds_123 doc_456 --output ./original.pdf

Ingestion

Create reusable sources (all source types, including Confluence, GitHub, and GitLab):

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 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"
# GitHub reads through a read-only GitHub App installation, so pass its installation id.
vectoramp sources github VectorAmp/Docs --config '{"installation_id":12345678,"ref_mode":"active"}'
# GitLab takes a saved OAuth connection, or auth_mode "token" with an access token.
vectoramp sources gitlab platform/ingestion --config '{"auth_mode":"token","access_token":"glpat-..."}'

vectoramp sources list
vectoramp sources get src_123

Create a source and start a job 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"]}'
vectoramp --dataset ds_123 sources ingest github VectorAmp/Docs --config '{"installation_id":12345678}'

Local file ingestion hides the 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:

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

Jobs

vectoramp jobs list --dataset-id ds_123
vectoramp jobs get job_123                 # one-shot status
vectoramp jobs get job_123 --poll          # poll until completed/failed/cancelled
vectoramp jobs retry job_123

Schedules

vectoramp schedules list
vectoramp schedules create --source-id src_1 --dataset-id ds_1 --cron "0 0 * * *" --timezone UTC
vectoramp schedules update sch_1 --disable
vectoramp schedules trigger sch_1
vectoramp schedules delete sch_1 --yes

Ask (RAG)

# Defaults: top_k 5, include_sources true, and every dataset you can see 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

# Scope one question to several datasets: repeat --datasets, or comma-separate
vectoramp ask "Which contracts renew in Q4?" --datasets ds_contracts --datasets ds_invoices
vectoramp ask "Which contracts renew in Q4?" --datasets ds_contracts,ds_invoices

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 filter the command palette; ↑/↓ to highlight, Tab/Enter to complete. Plain text without a slash is treated as /ask against the active dataset and keeps a rolling multi-turn conversation. --history <n> controls how many prior messages are included (default 10). Switching datasets resets the conversation.

Multi-turn conversations

The Intelligence API is stateless, so follow-up questions need prior turns sent as context. One-off ask commands are single-turn. In interactive mode the REPL keeps the running conversation and sends a window of recent messages with each follow-up, so questions like "and why is that?" resolve against earlier turns.

Programmatic use

The package also exports a typed client for embedding the same behavior in scripts:

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'] }));

Method reference (client)

| Method | Required args | Optional | |---|---|---| | listDatasets(params?) | — | limit, offset | | getDataset(id) | id | — | | createDataset(body) | body.name | dim (inferred for built-in models), metric (cosine), embedding, hybrid, metadata. index_type is always sable. | | deleteDataset(id) | id | — | | stats(id) | id | — | | search(id, query, options?) | id, query (string | float[] | object) | topK (10), filters, hybrid, sparseQuery, alpha, rerank (true expands to the full object), includeDocuments, includeMetadata | | embed(id, input, options?) | id, input (string | string[]) | model/provider overrides | | insert(id, vectors) / insertVectors(id, vectors) | id, vectors (record | record[]) | id accepts string or integer; integers stay JSON numbers | | addTexts(id, texts, metadata?, ids?) | id, texts (string | string[]) | metadata (shared or per-text), ids (auto-generated when omitted); copies text into metadata.text | | listDocuments(id, params?) | id | limit, cursor, status | | downloadDocument(id, documentId) | id, documentId | returns ArrayBuffer | | createSource(input) | input (descriptor or URL string) | — | | listSources(params?) / getSource(id) | — / id | limit, offset | | ingestSource(id, src, options?) | id, src | pipelineId — creates the source then POST /ingestion/jobs | | ingestFiles(id, files, options?) | id, files (IngestFile[]) | sourceId, sourceName, pipelineId — runs the presigned upload flow | | startJob(body) / listJobs(params?) / getJob(id) / retryJob(id) | per signature | — | | waitForJob(id, options?) | id | intervalMs, timeoutMs, onPoll | | listSchedules / getSchedule / createSchedule / updateSchedule / deleteSchedule / triggerSchedule | per signature | — | | ask(body) / askStream(body) | body.query | datasetIds (omit for every visible dataset), topK (5), includeSources (true), conversationHistory | | createSession / listSessions / getSession / deleteSession / appendMessage / listMessages | per signature | — |

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

Development

npm ci
npm run typecheck
npm test
npm run build

License

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