qsva-cli

Command-line tool for QSVA — connect your AI agent project, open the visualization dashboard, and monitor policy enforcement decisions directly from your terminal.

Install

# Run without installing (recommended)
npx qsva-cli init

# Or install globally
npm install -g qsva-cli

Quickstart

# 1. Initialize QSVA in your agent project directory
npx qsva-cli init

# 2. Open the dashboard
npx qsva-cli viz

# 3. Monitor policy checks in real time
npx qsva-cli status

Commands

qsva init

Connects to the QSVA server, auto-generates an API key for your workspace, and saves your config to .qsva-config.json.

qsva init
# or with a custom self-hosted server:
qsva init --url https://your-qsva-server.example.com
# overwrite an existing config:
qsva init --force

Creates .qsva-config.json:

{
  "gatewayUrl": "https://qsva-intersection.onrender.com/api/gateway",
  "dashboardUrl": "https://qsva-intersection.onrender.com",
  "apiKey": "qsva_sk_live_...",
  "createdAt": "2026-04-09T12:00:00.000Z"
}

Keep .qsva-config.json out of version control — add it to your .gitignore.

Then add the key to your .env:

QSVA_API_KEY=qsva_sk_live_...

qsva viz

Opens the QSVA dashboard in your browser. Reads the URL from .qsva-config.json automatically.

qsva viz
# or with a custom URL:
qsva viz --url https://your-qsva-server.example.com

qsva status

Prints a live summary of gateway health and recent policy enforcement decisions.

qsva status
# disable color output:
qsva status --no-color

Example output:

● QSVA Gateway  https://qsva-intersection.onrender.com  82ms

  Recent Policy Checks (last 10)
  ─────────────────────────────────────────────────────────────────────
  ResearchAgent   read    financial data        ✓ ACK     2ms   5s ago
  WriterAgent     write   production databases  ✗ BLOCKED 4ms  12s ago
  ─────────────────────────────────────────────────────────────────────
  2 checks  ·  1 ack  ·  1 blocked

qsva --help

Print all available commands and flags.

Using the gateway in your agent code

After running qsva init, route every agent action through the gateway before executing it:

const response = await fetch("https://qsva-intersection.onrender.com/api/gateway", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.QSVA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agent: "ResearchAgent",
    action: "read",
    resource: "financial data",
  }),
});

const { verdict, reason } = await response.json();
if (verdict !== "ack") {
  throw new Error(`Action blocked by QSVA: ${reason}`);
}
// proceed with action

Self-hosting

If you run your own QSVA server, pass --url to any command:

qsva init --url https://your-server.example.com
qsva viz  --url https://your-server.example.com

Once initialized, .qsva-config.json stores the URL so you won't need to pass it again.