# 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 ```bash npm install -g @vectros-ai/cli # or invoke without installing: npx -y @vectros-ai/cli ``` The binary is `vectros`. Run `vectros --version` to print the CLI version plus the bundled SDK and blueprint-library versions. ### Sign in and confirm who you are ```bash 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 ```bash 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`: ```bash export VECTROS_BOOTSTRAP_TOKEN= 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 ` (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: ```bash 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 `. ### Test a blueprint end-to-end against a live environment ```bash 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: ```bash vectros context create my-app --name "My App" vectros context list vectros context get my-app ``` **Identities** — tenant-wide principals (user / org / client): ```bash 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 vectros identity delete --type user --id ``` **Scoped keys** (`ssk_*`): ```bash vectros key issue --principal usr_ --context my-app --name laptop vectros key list --context my-app vectros key get vectros key rotate --principal usr_ --context my-app --name laptop vectros key revoke ``` `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: ```bash 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: ```bash vectros access grant --principal usr_ --context my-app --role editor vectros access grant --principal key_ --context my-app --actions records:r,search:r vectros access list --context my-app vectros access get --principal usr_ --context my-app vectros access revoke --principal usr_ --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 ` | creds-bearing verbs | Override the API base URL. | | `--token ` | creds-bearing verbs | Bearer token; else read from the environment. | | `--json` | read verbs | Emit machine-readable JSON. | | `--blueprint ` | `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 ` | `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](blueprints.md) — the blueprint format the lifecycle commands operate on. - [mcp.md](mcp.md) — what the bootstrapped credential plugs into. - [sdk.md](sdk.md) — the programmatic equivalent of the verbs above. - The blueprint walkthroughs — narrated, end-to-end builds that use `init → bootstrap → blueprint-test`.