VectorGraph CLI

The VectorGraph CLI provides the first-class vectorgraph command for workspace automation, /cli/v1 workflows, and local NorthGraph code intelligence.

Install

Release 0.7.1 is the patch successor to @orintech/[email protected]. It preserves the existing version, multi-workspace routing, and authorization contracts and lets hosted MCP setup verify either the stable web health route or the split API readiness route. First require the public lookup to return exactly 0.7.1. Installation is then one command:

npm view @orintech/[email protected] version
npm install --global @orintech/[email protected]

This also installs NorthGraph and its local MCP server. Use vectorgraph north ... for NorthGraph commands and vectorgraph north mcp for the local MCP transport. Do not install @orintech/north-core separately. Hosted VectorGraph MCP is a remote workspace service and is configured with its URL and dedicated credential; it is not installed by npm. The same CLI provides vectorgraph mcp doctor --json to probe that hosted connection, but the command does not start a workspace MCP server. There is no separate @orintech/mcp, @vectorgraph/mcp, or vector-mcp executable.

The npm package targets Windows x64/ARM64, macOS Intel/Apple silicon, and Linux x64/ARM64. It requires Node.js 24.19.0. Those targets become customer-support claims only after the exact published package passes release smoke on each one. Git must be available on PATH for local NorthGraph repository analysis. No VectorGraph .msi, .pkg, Homebrew formula, winget package, .deb, or .rpm is currently published. NorthGraph bundles its baseline Tree-sitter parsers; Python, a JDK, and Clang are not required for Python, Java, C, or C++ analysis.

Before installing, confirm the exact version exists. After installing, verify the command and local analyzer:

vectorgraph --version
vectorgraph version --json
vectorgraph north doctor --json

To upgrade an existing installation, use the same canonical scoped package name (including the leading @):

npm view @orintech/[email protected] version
npm install --global @orintech/[email protected]

On Windows PowerShell, run npm.cmd in place of npm. The npm package remains @orintech/cli; vectorgraph is the installed binary. Neither vectorgraph/cli nor @vectorgraph/cli is a published package.

For one-off use without a global install:

npx @orintech/[email protected] north doctor --json

On Windows, run the same commands from PowerShell. Use Get-Command vectorgraph.cmd to verify PATH; npm.cmd and vectorgraph.cmd avoid a PowerShell script-policy dependency. On macOS and Linux, use command -v vectorgraph. Do not bypass managed-device policy or use sudo npm install; use an organization-approved, user-owned Node installation. If npm reports UNABLE_TO_GET_ISSUER_CERT_LOCALLY, keep strict-ssl=true and inspect npm config get cafile. Repair the trusted CA bundle or remove only a stale user-level cafile; never disable TLS verification.

Configure

Browser login and automatic hosted MCP setup require the matching VectorGraph web/API release. Publishing the npm package alone does not activate those server routes; if login reports that the service is unavailable, stop and wait for the announced service release rather than using an unofficial endpoint.

Release boundary: public @orintech/[email protected] includes the global --version alias, saved profiles, the persistent workspace use default, non-mutating --workspace selection, saved-profile session routing, and readiness-aware hosted MCP setup. The paired CLI and NorthGraph packages are registry-verified at 0.7.1; client-specific support claims still require their own UAT.

Use browser login. No API URL, workspace slug, or copied token is required:

vectorgraph auth login
vectorgraph auth status

The browser compares a ten-minute single-use code, signs in with the normal VectorGraph account, and lets the user select one or more workspaces. The server creates a separate scoped token for each selected workspace and returns each raw token once to the waiting CLI. The CLI stores those profiles in a private local file without printing their raw tokens and uses one explicit active workspace. When agent setup is approved and Codex or Claude is detected, interactive login immediately starts the same reviewed MCP setup flow. Use --no-mcp to skip it.

vectorgraph workspace list
vectorgraph workspace use "<workspace-slug>"
vectorgraph auth status

# Target another saved profile without changing the default.
vectorgraph auth status --workspace "<workspace-id-or-slug>"
vectorgraph issues query --workspace "<workspace-id-or-slug>" --json

workspace use verifies the selected profile before saving it. Every CLI API path still contains the immutable workspace ID, every token remains workspace-bound, and the server rechecks current membership and private-team access on every request. --workspace selects the complete saved profile for one command without changing the default; it never combines one profile's token with another profile's workspace. If a name or slug matches more than one saved profile, the CLI stops before making a request and requires the immutable workspace ID.

For a shell or agent session, set only VECTORGRAPH_WORKSPACE_ID to the immutable ID of a saved profile. Each process resolves that profile independently, so concurrent commands can target different workspaces without calling workspace use or racing over a global selection:

VECTORGRAPH_WORKSPACE_ID="<workspace-a-id>" vectorgraph issues query --json
VECTORGRAPH_WORKSPACE_ID="<workspace-b-id>" vectorgraph issues query --json

Configure hosted VectorGraph MCP and optional local NorthGraph MCP for Codex, Claude, or both:

vectorgraph mcp setup \
  --client codex,claude \
  --workspace "<workspace-id-or-slug>" \
  --team ENG \
  --local-north

The command reviews the workspace, clients, grants, scopes, tools, expiry, and storage targets before creating separate client credentials. Add --manage-tokens only when the approving CLI was explicitly granted token management during browser authorization and the MCP client must list, create, or revoke delegated credentials. New hosted entries use a compact, lossless base64url encoding of their complete immutable workspace UUID, such as vectorgraph-ERERERERQRGBEREREREREQ, so several workspaces can coexist in the same Codex or Claude configuration without sharing identity or credentials, even when slugs or UUID prefixes collide. The compact name also keeps Claude-qualified MCP tool and prompt names within the 64-character API limit. Existing managed entries retain their recorded legacy names. Concurrent setup merges CLI metadata and direct Codex configuration under cross-process locks; Claude configuration remains mediated by Claude's user-scoped CLI. Failure rollback removes only the connections, entries, and metadata created by that setup run. For automation, run the same command with --json for a no-write review, then repeat the identical request with --json --yes after approval. Raw MCP credentials are not printed or stored in VectorGraph CLI metadata.

vectorgraph mcp doctor validates an explicitly supplied MCP credential; the CLI intentionally does not retain generated MCP secrets in its metadata. It therefore rejects --workspace instead of silently substituting a saved CLI token. Use the workspace-named client entry or the setup command's direct credential probe for per-workspace MCP validation.

CI can use environment variables instead:

export VECTORGRAPH_API_URL="https://staging.vectorgraph.app"
export VECTORGRAPH_API_TOKEN="<vta_...>" # or VECTORGRAPH_CLI_TOKEN
export VECTORGRAPH_WORKSPACE_ID="<workspace-id>"

On Windows, set the same variables in PowerShell:

$env:VECTORGRAPH_API_URL = "https://staging.vectorgraph.app"
$env:VECTORGRAPH_API_TOKEN = "<vta_...>" # or VECTORGRAPH_CLI_TOKEN
$env:VECTORGRAPH_WORKSPACE_ID = "<workspace-id>"

or in cmd.exe:

set VECTORGRAPH_API_URL=https://staging.vectorgraph.app
set VECTORGRAPH_API_TOKEN=<vta_...>
set VECTORGRAPH_WORKSPACE_ID=<workspace-id>

All three forms apply to the current shell session only. For persistent values use the CI system's secret store, or setx on Windows (new shells only). An environment token is accepted only when the same environment also supplies its immutable VECTORGRAPH_WORKSPACE_ID; incomplete or mismatched overrides fail before any API request. When no environment token is set, VECTORGRAPH_WORKSPACE_ID may select a saved browser-login profile for that shell without changing the default profile. vectorgraph auth logout removes stored config credentials but never changes environment variables, so unset these yourself when rotating tokens.

Troubleshooting network errors

Start with the built-in diagnosis. It requires no login and checks the API URL and its source, environment overrides, proxy settings, DNS, TCP, the presented TLS certificate chain, and the API health endpoint:

vectorgraph net doctor

When a connection is intercepted, the TLS chain check names the authority that signed what the server presented — for example a Norton or Zscaler root — so the cause is visible without contacting support.

The CLI reports every failed connection with the URL it called, the underlying cause, and the error code, and exits with code 9. Example:

Network error calling https://vectorgraph.app/cli/v1/auth/device: unable to
verify the first certificate (UNABLE_TO_VERIFY_LEAF_SIGNATURE). Your network
inspects TLS (antivirus or a corporate proxy). Set NODE_USE_SYSTEM_CA=1 (or
run with NODE_OPTIONS=--use-system-ca), or point NODE_EXTRA_CA_CERTS at your
organization's CA bundle.

Two network environments are handled automatically:

• TLS inspection. Antivirus and corporate proxies (Norton, Zscaler, and similar) re-sign HTTPS traffic with a root certificate installed in the operating system trust store. Node.js does not read that store by default, so every request would fail TLS verification even though the browser works. The CLI merges the operating-system trust store into its trusted roots at startup, so inspected networks work without flags. NODE_USE_SYSTEM_CA=1 and NODE_OPTIONS=--use-system-ca remain equivalent manual switches for other Node tools. If the inspecting root is distributed as a file instead of installed in the OS store, point NODE_EXTRA_CA_CERTS at that bundle. Never disable TLS verification.
• HTTP(S) proxies. The CLI honors HTTP_PROXY, HTTPS_PROXY, and NO_PROXY for every request. No extra Node flags are required.

vectorgraph mcp doctor checks GET /api/health on the API origin before probing MCP methods, so connectivity failures are reported once with the real cause instead of five timed-out probes. Browser login tolerates brief network interruptions while waiting for approval and times out individual requests after 30 seconds. If NODE_TLS_REJECT_UNAUTHORIZED=0 is set, certificate verification is disabled for the whole Node.js process; the CLI warns and directs you to unset it. The CLI's automatic system trust makes that variable unnecessary; it is never the fix.

Network diagnostics reporting

After a network failure, the CLI stores the failure's error code locally and includes it — with the platform name and CLI version, nothing else — in a header on its next successful request to the VectorGraph API. This tells the service which network problems customers actually hit and is covered by the VectorGraph Terms of Service. Set VECTORGRAPH_NO_TELEMETRY=1 (or the standard DO_NOT_TRACK=1) to disable it; no report is stored or sent when either is set.

Core Commands

vectorgraph issues query --json
vectorgraph issues create --team ENG --title "Follow up"
vectorgraph tokens list --json
vectorgraph tokens create --scope workspace:read,artifact:read,artifact:write --ttl 30d --json
vectorgraph tokens revoke --id <token-uuid> --json
vectorgraph tokens remove --id <token-uuid> --json
vectorgraph docs list --json
vectorgraph docs get --id <document-uuid> --json
vectorgraph docs create --title "Incident runbook" --body "Steps..." --team <team-uuid>
vectorgraph docs import ./runbook.md ./operations.md --collection <collection-uuid> --team <team-uuid>
vectorgraph docs update --id <document-uuid> --title "New title"
vectorgraph docs archive --id <document-uuid>
vectorgraph canvas list --json
vectorgraph canvas create --title "Architecture" --scene-json '{"elements":[]}'
vectorgraph canvas update --id <canvas-uuid> --scene-json '{"elements":[]}'
vectorgraph canvas archive --id <canvas-uuid>
vectorgraph search --query "auth enforcement"
vectorgraph api operations --json
vectorgraph api call listApiProjects --query-json '{"limit":25}' --json
vectorgraph signals submit --team ENG --title "Customer signal" --body "..."
vectorgraph deploy mark --issues ENG-123 --sha "$(git rev-parse HEAD)"
vectorgraph context bundle --issue ENG-123 --json
vectorgraph north plan --intent "check auth changes" --json
vectorgraph north ask "where is workspace auth enforced?" --json
vectorgraph north verify --base HEAD --mode targeted --json
vectorgraph north mcp
vectorgraph net doctor --json

NorthGraph bounded execution

Every local NorthGraph operation except the long-lived north mcp transport runs inside one shared execution context. Interactive commands have a five-minute end-to-end deadline, verify has a 25-minute end-to-end deadline, ordinary stages have a five-minute deadline, the verification-command stage has a 20-minute deadline, and each configured verification command has a ten-minute deadline. Long work emits a heartbeat every five seconds. Override those measured budgets with --timeout-ms, --stage-timeout-ms, --command-timeout-ms (verify only), and --heartbeat-ms; every value is a positive integer in milliseconds and remains bounded by the end-to-end deadline.

Human-mode commands send progress to stderr immediately. JSON mode preserves exactly one final JSON value on stdout; add --progress to receive newline-delimited north_progress lifecycle records and north_command_progress command records on stderr. Timeout, cancellation, configuration, authentication, repository, index, command, evidence, and attachment failures include a run ID, operation, named stage, elapsed time, budget, partial-result state, retryability, and safe remediation. The CLI exits 124 for a timeout and 130 for cancellation. Ctrl-C cancels the active run and bounded verification commands terminate their descendant process trees on Windows, macOS, and Linux before the final error is returned.

The local MCP server accepts timeoutMs and stageTimeoutMs on every tool; verify tools also accept commandTimeoutMs. Clients that send an MCP progress token receive notifications/progress, and notifications/cancelled aborts the matching request. See docs/testing/NORTH_EXECUTION_RELIABILITY.md for the exact contract and verification commands.

tokens remove is the explicit removal command and performs the same audited revocation as tokens revoke; it preserves the credential receipt while immediately rejecting later authentication. Token management requires a CLI login approved with credential-management access in the browser. It never requires VECTORGRAPH_SESSION_COOKIE or browser-cookie extraction.

docs and canvas reads go through the permission-filtered /cli/v1 workspace endpoints; --archived lists archived artifacts instead of active ones. Their create, update, and archive writes go through the same approved-operation executor as vectorgraph api call and send an idempotency key automatically (pass --idempotency-key to control retries yourself). vectorgraph search --query <text> runs the permission-filtered workspace search and prints one line per hit: object type, object ID, and title.

vectorgraph api operations --json returns every committed agent-safe OpenAPI operation allowed by the configured token in its selected workspace, including method, path, read/write class, and required scopes. vectorgraph api call accepts --path-json, --query-json, --body-json, or a complete --input-json object. Every mutation requires --idempotency-key. The server selects the method/path from the allowlist and rejects human/admin/provider/public/transport operations and arbitrary routes.

All examples on this page use the installed vectorgraph command directly.