CLI

Explanation — what & why

vectros is the provisioning command-line tool (@vectros-ai/cli). It is the terminal-and-CI counterpart to the developer portal: it stands up the things an app needs to exist — app contexts, identities, scoped keys, access bindings, roles — and it runs the blueprint lifecycle that turns a declarative app model into provisioned infrastructure.

Two ideas shape the CLI:

It is the trust boundary, not the blueprint. A blueprint is untrusted input — it may be forked, hand-written, or agent-authored. The CLI's scope gate refuses to mint anything outside a fixed data-plane allowlist. There is no override flag: control-plane access is provisioned deliberately in the portal, never through a tool an agent can drive.
Bootstrap without the root key. The bootstrap command provisions a least-privilege scoped key for an MCP agent using a short-lived bridge token from the developer portal — your root key never touches the flow.

The CLI bundles its own SDK and blueprint library into the binary, so it has no runtime dependency you have to install or authenticate separately.

How-to

Install

npm install -g @vectros-ai/cli
# or invoke without installing:
npx -y @vectros-ai/cli <command>

The binary is vectros. Run vectros --version to print the CLI version plus the bundled SDK and blueprint-library versions.

vectros login            # opens a browser for a PKCE sign-in, stores a session
vectros whoami           # shows the authenticated tenant, environment, and principal
vectros logout           # clears the stored session

login accepts --env staging|production (default staging) and --no-browser to print the sign-in URL instead of opening one (useful on headless/CI/WSL hosts).

Bootstrap an MCP credential in one command

vectros bootstrap

Interactively, it asks what to set up — a blank read-only data-plane credential, or a bundled blueprint (which also provisions that blueprint's schemas and seed) — signs you in once with a portal-issued bridge token, previews the plan, mints a narrow ssk_*, and merges it into your MCP client config.

For scripted or agent runs, set the bridge token in the environment and pass the blueprint plus --yes:

export VECTROS_BOOTSTRAP_TOKEN=<token from the developer portal>
vectros bootstrap --blueprint task-management --yes

Useful flags: --blank (credential only, no schemas), --print (print the config snippet instead of merging), --rotate (revoke and re-mint this machine's key), --env staging|production, and --blueprint <name|./path.yaml> (a bundled name or a path to your own blueprint file — both pass the identical scope gate).

The minted key is per-machine and independently rotatable. The access profile is data-plane only: the command hard-refuses any control-plane scope, so even a community-authored blueprint cannot escalate the credential it provisions.

Author and inspect blueprints (no credentials needed)

The blueprint group is creds-free and offline — it is your authoring inner loop:

vectros blueprint list                          # the bundled library
vectros blueprint init my-app                   # scaffold ./my-app.blueprint.yaml to edit
vectros blueprint init my-app --from clinical-intake   # scaffold from a bundled exemplar
vectros blueprint validate ./my-app.blueprint.yaml     # structural + scope-gate + lint
vectros blueprint plan ./my-app.blueprint.yaml         # validate, then preview what bootstrap would provision

validate runs three checks in order: structural parse, the data-plane scope gate, and the authoring linter. plan runs the same validation and then prints a provisioning preview (it mints nothing). A blueprint may declare an inputs: block; supply values with --set name=value (repeatable) or --values <file>.

Test a blueprint end-to-end against a live environment

vectros blueprint-test ./my-app.blueprint.yaml
vectros blueprint-test task-management --keep   # leave the provisioned graph in place

blueprint-test runs the full lifecycle: apply → assert → teardown. It applies the blueprint to the target environment, asserts the minted key actually works (it pings the API as that key and checks the provisioned graph is readable), then tears the graph back down — leaving a shared environment clean. The harness key is isolated in an ephemeral store so a test run never touches your real per-machine key. --keep skips teardown for inspection. The app context itself is intentionally never deleted — it is idempotent and reused, so leaving it is harmless.

Provision the pieces directly

When you do not want a whole blueprint, the verb groups provision individual resources. Every creds-bearing verb shares the auth flags --env, --base-url, --token, and (on read verbs) --json.

App contexts — the namespace all data lives in:

vectros context create my-app --name "My App"
vectros context list
vectros context get my-app

Identities — tenant-wide principals (user / org / client):

vectros identity create --type user --external-id alice --email alice@example.test
vectros identity create --type org  --external-id acme --name "Acme Inc."
vectros identity list   --type user
vectros identity get    --type user --id <vectrosId>
vectros identity delete --type user --id <vectrosId>

Scoped keys (ssk_*):

vectros key issue  --principal usr_<id> --context my-app --name laptop
vectros key list   --context my-app
vectros key get    <keyId>
vectros key rotate --principal usr_<id> --context my-app --name laptop
vectros key revoke <keyId>

key issue and key rotate emit the secret; choose the output shape with --format human|raw|env|json. A revoke is a soft-delete and takes a few minutes to take effect.

Roles — reusable, identity-agnostic scope rules in a context:

vectros role create --context my-app --role-id editor --name Editor \
  --actions records:cru,search:r
vectros role list   --context my-app
vectros role get    --context my-app --role-id editor
vectros role delete --context my-app --role-id editor

Access bindings — bind a principal to a context, via a role or inline actions:

vectros access grant  --principal usr_<id> --context my-app --role editor
vectros access grant  --principal key_<id> --context my-app --actions records:r,search:r
vectros access list   --context my-app
vectros access get    --principal usr_<id> --context my-app
vectros access revoke --principal usr_<id> --context my-app

Reference

Command catalog

Command	Purpose
`login` / `logout`	Browser sign-in (PKCE) and session teardown.
`whoami`	Show the authenticated tenant, environment, and principal.
`bootstrap`	One-shot least-privilege MCP credential (`ssk_*` + access profile + optional blueprint).
`blueprint init`	Scaffold a new blueprint file to edit.
`blueprint validate`	Structural parse + scope gate + lint (creds-free).
`blueprint plan`	Validate, then preview what `bootstrap` would provision (creds-free).
`blueprint list`	List the bundled blueprint library.
`blueprint-test`	Apply → assert → teardown a blueprint against a live environment.
`context create\|list\|get`	Manage app contexts.
`identity create\|list\|get\|delete`	Manage tenant-wide principals (user/org/client).
`key issue\|list\|get\|revoke\|rotate`	Manage scoped API keys (`ssk_*`).
`role create\|list\|get\|delete`	Manage context-scoped roles.
`access grant\|revoke\|list\|get`	Manage principal-to-context bindings.

The scope gate (data-plane allowlist)

The bootstrap and blueprint paths will only mint scopes on these resources:

records · schemas · search · documents · folders · inference

Anything else — keys, profiles, app-contexts, users, billing, admin, clients, orgs, any unknown resource, or a bare * wildcard — is hard-rejected, and the command mints nothing and exits non-zero. There is no override flag.

Scope grammar

A scope token is resource:operations[:qualifier]. Operations are the combinable single characters c (create), r (read), u (update), d (delete) — e.g. records:cru. Author explicit resource:op forms: coarse verbs and the ops-wildcard resource:* do not grant access at runtime. A trailing qualifier (e.g. records:r:intake_form) only narrows access.

Common flags

Flag	Applies to	Meaning
`--env staging\|production`	creds-bearing verbs	Target environment (default `staging`).
`--base-url <url>`	creds-bearing verbs	Override the API base URL.
`--token <token>`	creds-bearing verbs	Bearer token; else read from the environment.
`--json`	read verbs	Emit machine-readable JSON.
`--blueprint <name\|path>`	`bootstrap`	A bundled name or a path to your own file.
`--blank`	`bootstrap`	Credential only (read-only data-plane, no schemas).
`--print`	`bootstrap`	Print the config snippet instead of merging.
`--rotate`	`bootstrap`	Revoke + re-mint this machine's key.
`--yes` / `-y`	`bootstrap`	Skip confirmations (agent / CI).
`--keep`	`blueprint-test`	Skip teardown; leave the graph for inspection.
`--set name=value` / `--values <file>`	`blueprint validate\|plan`	Supply install-time input values (file blueprints only).

Bootstrap exit codes

0 success · 1 failure · 2 scope gate refused the blueprint (mints nothing) · 3 the key was minted but could not be recorded.

Notes & limits

SDK pin. The CLI bundles a 0.26 staging SDK build into its binary; you do not install or pin the SDK separately to use the CLI.
A bridge token is a human prerequisite. bootstrap needs a bridge token from the developer portal (passed via --token or VECTROS_BOOTSTRAP_TOKEN). There is no way to mint one from the CLI alone.
--set/--values apply to file blueprints only. Bundled blueprints are fixed and declare no inputs; supplying values against one is a usage error.
blueprint-test never deletes the app context. It tears down the data it created, but the context is idempotent and intentionally left in place.
No control-plane provisioning through bootstrap/blueprints. Keys, profiles, billing, and admin scopes are portal-only by design.

Where to go next

blueprints.md — the blueprint format the lifecycle commands operate on.
mcp.md — what the bootstrapped credential plugs into.
sdk.md — the programmatic equivalent of the verbs above.
The blueprint walkthroughs — narrated, end-to-end builds that use init → bootstrap → blueprint-test.