contextvault-client

Typed SDK and CLI for Context Vault — talk to the daemon from Node, browsers, agents, or the terminal.

npm install contextvault-client          # SDK + cv CLI
npm install -g contextvault-client       # also puts `cv` on PATH

Two ways to use it

From code — import { CVClient } …

import { CVClient } from "contextvault-client";

const cv = new CVClient({
  baseUrl: "https://contextvault.metisos.co/api/cv",
  token: process.env.CV_TOKEN!,
  workspaceId: "ws-mngwr1n8-uhqfgq",
});

// Upsert — creates the artifact, or updates it if the URI already exists
const result = await cv.artifacts.save(
  "ctx://ws-…/engineering/architecture.md",
  "# Architecture\n\n…",
);

// Search the typed graph
const hits = await cv.search.query({ q: "vector DB", limit: 5 });

// Walk the catalog
const ws = await cv.catalog.workspace();
const eng = await cv.catalog.dept("engineering");

// Subscribe to live changes (Node / server-side)
for await (const event of cv.subscriptions.stream({ pattern: "ctx://ws-…/engineering/**" })) {
  console.log(event.event_type, event.artifact_uri);
}

From the terminal — cv

cv login                                 # device-flow auth (opens browser)
cv workspaces                            # list workspaces you can access
cv use ws-mngwr1n8-uhqfgq                # set the active workspace
cv ls engineering/                       # list artifacts at a path
cv cat ctx://ws-…/engineering/foo.md     # print an artifact
cv push ./local-file.md ctx://ws-…/…/foo.md
cv push-folder ./docs/ ctx://ws-…/product/
cv watch ./docs/ --to ctx://ws-…/product/
cv agent register --name "my-bot" --grants 'read:ctx://ws-…/**'

Both interfaces are the same package, sharing the same types and error classes — switching between a script and the terminal doesn't change the contract.

Typed errors

Every method throws a typed CVError subclass:

import { CVConflictError, CVForbiddenError } from "contextvault-client";

try {
  await cv.artifacts.create({ uri, name, content_type, content });
} catch (e) {
  if (e instanceof CVConflictError) {
    // URI already exists — use save() instead, or update()
  } else if (e instanceof CVForbiddenError) {
    // Actor lacks the grant
  } else {
    throw e;
  }
}

| Status | Class | Retryable | | -------- | ----------------------------- | --------- | | 400, 422 | CVValidationError | no | | 401 | CVAuthError | no | | 403 | CVForbiddenError | no | | 404 | CVNotFoundError | no | | 409 | CVConflictError | sometimes | | 412 | CVPreconditionFailedError | yes | | 5xx | CVServerError | yes | | network | CVNetworkError | yes | | n/a | CVSchemaError (wire drift) | no |

Resources

| Resource | What it covers | | --------------------- | ----------------------------------------------------------------------------------- | | client.artifacts | get / create / update / save (upsert) / delete / history / list / neighborhood / blob / move | | client.search | FTS5 keyword search | | client.catalog | workspace / stats / dept / folder | | client.edges | create / remove / query / listAll / neighbors | | client.workers | list / operators / agents | | client.provenance | query / forUri | | client.folders | list / get / upsert / remove (folder metadata) | | client.actors | create / list / get / heartbeat | | client.permissions | create / list / revoke / effective / explain | | client.subscriptions| stream (SSE AsyncIterable) | | client.chat | send (MetisOS turn) | | client.health | check |

Wire types

All wire shapes are exported as inferred Zod types:

import type { Artifact, SearchResponse, ChangeEvent } from "contextvault-client";

Or, for runtime validation:

import * as schemas from "contextvault-client/schemas";
const parsed = schemas.ArtifactSchema.parse(unknownInput);

License

Apache-2.0