@vectros-ai/cli

The Vectros provisioning CLI — the vectros binary. Two command groups:

• vectros bootstrap — provision a least-privilege MCP credential (+ optional blueprint).
• vectros blueprint — author + inspect blueprints (init / validate / plan / list), creds-free.
• vectros blueprint-test — apply a blueprint to a live env, assert it provisioned a working credential, then tear it down.

npx -y @vectros-ai/cli bootstrap          # provision a credential
npx -y @vectros-ai/cli blueprint --help   # the authoring commands

Every command has --help. The authoring loop is documented in AUTHORING.md.

vectros bootstrap

Provisions a least-privilege Vectros credential for the @vectros-ai/mcp-server in one command — without your root key and without manual admin-app steps. It:

• mints a scoped key (ssk_*) for this machine (independently rotatable),
• creates the matching AccessProfile — data-plane only,
• optionally scaffolds a use-case blueprint (e.g. task-management: a schema + seed data), and
• safe-merges the vectros server entry into your MCP client config (claude_desktop_config.json — Claude Desktop, Cursor, Cline), backing up the original first. Pass --client code to target Claude Code instead: it merges the project .mcp.json and prints the equivalent claude mcp add command.

# Interactive — pick a blueprint (or a blank read-only credential), sign in once.
npx -y @vectros-ai/cli bootstrap

# Scripted / agent — token in the env, no prompts.
VECTROS_BOOTSTRAP_TOKEN=… npx -y @vectros-ai/cli bootstrap \
  --blueprint task-management --yes

# Login once, then bootstrap unattended — no token needed; --yes reuses your
# stored `vectros login` session.
npx -y @vectros-ai/cli login
npx -y @vectros-ai/cli bootstrap --blueprint task-management --yes

# Provision a PRODUCTION context: the blueprint's schemas + key, but NONE of its
# illustrative sample records.
npx -y @vectros-ai/cli bootstrap --blueprint task-management --no-seed --yes

# See every flag.
npx -y @vectros-ai/cli bootstrap --help

Re-running is idempotent; --rotate revokes + re-mints just this machine's key.

A bundled blueprint ships with sample seed records so the credential works the moment it's minted. For a production context that's synthetic clutter: --no-seed provisions everything else — the schemas, the AccessProfile and the scoped key — but creates no sample records, leaving the context clean for real data. (Interactively, a blueprint with seeds asks before adding them.) This differs from --blank, which is credential-only and drops the schemas too.

vectros blueprint — authoring (creds-free)

Author and inspect blueprints without an account. You'll run these repeatedly, so install once and drop the npx prefix (npm i -g @vectros-ai/cli, or prefix each command with npx -y @vectros-ai/cli). The inner loop:

vectros blueprint init my-thing                      # scaffold a commented YAML starter
#   …edit ./my-thing.blueprint.yaml…
vectros blueprint validate ./my-thing.blueprint.yaml # structural + scope-gate + lint
vectros blueprint plan     ./my-thing.blueprint.yaml # preview what bootstrap would provision
vectros bootstrap --blueprint ./my-thing.blueprint.yaml   # apply it

• init — write a starter (--from <bundled> copies an exemplar; --out, --force).
• validate — structural parse → scope gate → linter. Accepts a file or a bundled name.
• plan — validate, then a terraform-style preview; mints nothing.
• list — the bundled library.

Full guide: AUTHORING.md. Format reference: @vectros-ai/blueprints.

vectros blueprint-test — verify it actually provisions (creds-required)

validate/plan check a blueprint statically; blueprint-test proves it end-to-end against a live environment. It applies the blueprint, asserts the result (the app-context + each schema are readable back, and the freshly minted ssk_* authenticates as a scoped key with the requested actions), then tears down what it created — schemas, the AccessProfile, seed records, and the key. Teardown is created-only: anything that already existed before the run is left untouched, so it's safe to point at a shared staging tenant.

# Apply → assert → teardown against staging (sign in first, or pass --token).
vectros blueprint-test ./my-thing.blueprint.yaml --env staging

# Leave the provisioned graph in place to inspect it.
vectros blueprint-test task-management --keep

Exit 0 = applied and every assertion passed; 1 = an assertion failed or apply errored; 2 = no credential, or the blueprint requested control-plane scope. The app-context is intentionally not deleted (it's idempotent and reused).

The scope gate (the trust boundary)

Blueprints are untrusted input (agent- or community-authored) and the CLI runs under an elevated ephemeral bridge token. So the trust boundary is this binary, not the blueprint: a hardcoded scope gate bounds every mint to a data-plane allowlist (records / schemas / search / documents / folders / inference). Any control-plane scope (keys / profiles / users / billing / admin) or * wildcard hard-rejects — the CLI mints nothing and exits non-zero. There is intentionally no override flag.

Rate limits

blueprint-test provisions against the live API, so a large blueprint can brush the per-account per-minute rate limit. The CLI surfaces the 429 (with its Retry-After hint) directly — rerun after the window resets, or split a large blueprint. See the rate limits guide.

See also

• @vectros-ai/mcp-server — the runtime this CLI provisions for.
• @vectros-ai/blueprints — the curated use-case library the CLI applies.

Security & trust

Vectros enforces per-customer, fail-closed isolation and least-privilege scoped keys, with a tamper-evident audit and version history. Customer-facing surfaces are hardened through extensive adversarial security review. For the full trust posture, drawn plainly with its boundaries, see the compliance and trust guide.

License

Apache-2.0. See the LICENSE file.