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 allowlist (the data-plane resources plus a few narrow, named exceptions — see The scope gate). There is no override flag: control-plane access is provisioned deliberately in the portal, not through a tool an agent drives.
  • 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.

Sign in and confirm who you are

vectros login            # opens a browser for a PKCE sign-in, stores a session
vectros whoami           # shows the authenticated tenant, environment, and principal
vectros whoami --tenant test   # the same for your test tenant (default: live)
vectros logout           # clears the stored session

login accepts --env staging|production (default production) and --no-browser to print the sign-in URL instead of opening one (useful on headless/CI/WSL hosts). When a stored session has expired or been revoked, commands say so and name the sign-in command to run again (vectros login, or vectros login --env staging for staging).

whoami confirms tenant, environment, and principal. It reports your live tenant unless you pass --tenant test (CLI 0.26.0 and later), which shows your own user id in the test tenant (it differs from your live user id; this needs platform 0.47.0 or later, and on an earlier platform the line shows — rather than failing); its tenant type line (CLI 0.26.0 and later; tenantType in --json) says which one you are looking at. It does not currently show which app context (the per-tenant data-partition every scoped credential is confined to) a scoped credential is bound to; that binding isn't surfaced by the underlying identity probe (GET /v1/ping) today. If the credential is one this CLI minted or joined itself (bootstrap, join), vectros keyring show reports the context you set it up for, from the CLI's own local record — but for a credential you didn't mint through this CLI (pasted from the developer portal, or handed to you by someone else), there is no discovery command; you have to already know which context it targets.

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 with your vectros login session (or, with none, a portal-issued bridge token you paste), previews the plan, mints a narrow ssk_*, stores it in this machine's OS credential store (or an encrypted file where none is available — never plaintext-in-repo), and merges an entry naming only that non-secret alias into your MCP client config. The vectros MCP server resolves the actual secret at startup via vectros keyring show --format raw — the config file itself discloses nothing if leaked.

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), --no-merge (still mints/stores — this only prints the config snippet instead of merging it), --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 limited to the scope gate's allowlist: the command refuses any scope outside it and mints nothing, whoever authored the blueprint.

Apply a blueprint without minting a key

vectros bootstrap also mints a per-machine key and merges MCP client config. To re-apply a changed blueprint into an existing context (from CI, say) use blueprint apply, which runs the same pipeline with the key step off:

vectros blueprint apply ./my-app.blueprint.yaml --tenant test
vectros blueprint apply ./my-app.blueprint.yaml --tenant live --yes --confirm-existing-principal   # a CI re-apply

It creates or reconciles everything the blueprint declares, but mints no key, opens no keyring and touches no client config. --tenant test|live is required (no default), and before it changes anything it prints the account, tenant, context and API it is pointed at, then the plan, then asks. With no terminal it needs --yes. It uses the same credential and gates as bootstrap and refuses on them before any change. An existing service principal needs --confirm-existing-principal (standing consent in a pipeline, and required on every apply once the principal exists, on any machine; every run prints which principal it reused). The same flag covers a trigger's service principal that already exists without this blueprint's mark: once confirmed it is marked as this blueprint's (an overwrite that needs the users:u scope; apply says if it could not) and not asked about again. Sample seed records are opt-in: unlike bootstrap, apply writes none unless you pass --seed, in either tenant (a blueprint's seeds are illustrative, not real data, and a re-apply from a pipeline must not write them by omission); the plan and the summary say plainly whether they will be or were written (when the blueprint declares any), and --no-seed is refused on apply (it already does not seed). Deletion is opt-in: without --prune nothing is deleted; with it, a trigger the file no longer declares is removed when its stored provisionedBy marker equals the blueprint's name and its principal's external id is the one that blueprint would derive. Those are stored markers, not verified identities, and the name comes from the blueprint file (after any ${{ inputs.* }} substitution, so --set and --values can change it), so a blueprint that reuses another one's name and omits some of its triggers will remove them. If a removal it matched fails, or a row carrying this blueprint's marker has no id or principal to remove it by, apply exits 1. Apply exit codes: 0 applied (also --help, and declining) · 1 failed while applying, or --prune could not remove a trigger it matched · 2 refused, before anything was changed (usage, no --yes without a terminal, no credential, an unknown or malformed blueprint, an invalid base URL, the scope or capability gate, a tenant-wide namespace without the opt-in), or an identity the blueprint references that could not be resolved (after the context and principal were provisioned) · 3 an existing principal (the blueprint's, or a trigger's that this blueprint did not mark) was not confirmed · 4 applied in full but --require-verified-issuers was given and an issuer is pending verification.

If another request changes a schema, app context, role, namespace or trigger rule at the same moment apply updates it, the platform answers 409 (VERSION_CONFLICT) instead of overwriting the other change, and apply stops with the platform's message (exit 1). Run it again once the other change has finished; a re-run converges.

When the blueprint declares agents, apply and bootstrap write each one to the blueprint's context after the roles, scripts and triggers and before any key is minted, and blueprint plan lists one step per agent. A new name is created at version 1, an unchanged definition writes nothing, and a changed one becomes the next version. The summary says what it did to each agent (created at version 1, unchanged at version 2, version 2 -> 3). The credential needs agents:c, and agents:u and agents:r as well when the agent already exists, even if its definition is unchanged; on a 403 the error names the agent, the scope and the context, and because agents are written before the key, a refused run mints none. An agent that already exists with no blueprint mark (made by hand) is refused unless you pass --allow-agent-adoption, and another blueprint's agent of the same name is always refused (exit 1, nothing written to it). A retired agent the blueprint still declares fails the apply. Removing an entry deletes nothing. See Agents.

Author and inspect blueprints (no credentials needed)

The authoring commands of the blueprint group are creds-free and offline (apply, above, is the one that needs credentials) — they are 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 or apply 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>.

The linter warns, without changing the exit code, about a schema field named externalId, partnerUserId, scopes or userId: the platform reserves those names for the top level of a record or document, so a payload that carries one is refused and the field can never hold a value. The warning names the schema and the field and says whether a seed in the same blueprint will fail when it is provisioned. A lookup field with one of those names is an error (exit 2), because the platform refuses the schema when it is created. A plain field on a schema that binds only to users or entities is not checked; the lookup-field error applies to every schema. For a blueprint with agents, validate reports the section as valid and says which scopes an apply needs.

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 never deleted — it is idempotent and reused, so re-running the same blueprint adds no new context. Each distinct context a tested blueprint creates does stay in place and counts toward the account's limit of 100 app contexts (live and test counted separately); creating a new context past it returns 402 (SUBSCRIPTION_LIMIT_EXCEEDED).

A blueprint that declares agents runs too. A retired or purged agent keeps its name for good, so the test applies a copy of the blueprint whose agent names carry a suffix unique to the run (triage runs as triage-t1a2b3c4d, and the report lists each name), then retires and purges exactly the agents it created, even when an assertion failed. An agent that exists under the declared name is never touched. Agent names are limited to 54 characters here, and the credential needs agents:d as well as the scopes an apply needs. If an agent cannot be retired or purged the run exits 1 and prints the API call that retires or erases it; a teardown failure on any other resource is reported without changing the exit code.

^C (SIGINT) or SIGTERM during a blueprint-test run writes no further agents and skips the assertions if they have not begun, but the rest of the apply (schemas, roles, the profile, the key mint, seed records) still runs, because once the apply has begun only the agent step has a stop point (a signal before it begins ends the run first). Then the same teardown as after a failure removes what the apply's result lists, and the command exits 130 or 143, never as a pass. A second signal leaves at once, after printing the id of each agent the run created, any create still in flight, and the calls that retire them. With --keep nothing is torn down. SIGKILL cannot be handled, and a process manager may send it after SIGTERM, so it leaves everything written so far in place. A tracked agent create is sent without the client's own retries: one 429 or 5xx fails that create.

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 — principals: --type user (tenant-wide), or an entity namespace (org / client are reserved names, registered the same way as any other — see identity-access/reference.md; register one with vectros namespace register, below):

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>
vectros identity invite --context my-app --role editor --email bob@example.test \
  --accept-url https://my-app.example.test/accept

identity invite onboards a person into a context by email (POST /v1/users/invite) — your vectros login session already carries enough scope, no root key required. --role names an existing Role in that context; the invitee inherits its scopes. --accept-url is required unless --no-send-email is given, in which case the response carries the raw inviteToken/acceptLink for you to deliver yourself. Whenever you supply --accept-url — including together with --no-send-email — it is validated: it must be an https:// URL with a domain-name host (an IP-literal host or a custom-scheme deep link is rejected).

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.

key rotate matches the key to revoke by (context, principal, name) — --name defaults to "default". If that default doesn't match but another active key exists for the same (context, principal) — e.g. a bootstrap-minted key, named ${blueprint.name}-${machineId} — rotate will not mint a new key silently: it names the other active key(s) it found and asks for an explicit --name (or --force-new to proceed anyway). Read the exact name off vectros key list --context <ctx> (the NAME column) when rotating a key you didn't mint yourself with key issue.

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

--principal me is your own signed-in user, resolved per tenant. In the test tenant your principal has a different id from your live user, so me resolves it per tenant: add --tenant test and it still works, e.g. vectros access grant --principal me --context <context-id> --role <role> --tenant test. This needs CLI 0.25.0 or later and platform 0.47.0 or later (which adds GET /developer/me?tenant=); on an earlier platform the command typically stops and points you to vectros identity list-all --tenant test (an owner login), which shows the id to pass as --principal usr_<id>.

From CLI 0.26.0, access list --principal searches one context, default, because the command's token is pinned to it: depending on the caller the platform may not look beyond that context, so a grant you hold in another context can be missing from the list, and an empty list means no grant in default, not no grants anywhere. The command says so on standard error (so --json output on standard output stays a bare array) and drops the line when a row from another context shows the lookup did span contexts. To see a grant in a specific context, use vectros access get --principal me --context <context-id> (add --tenant test for the test tenant), or vectros access list --context <context-id> for everyone in it. The line is also written with --json, and there is no switch to turn it off: a script that merges standard error into standard output (2>&1) will see one extra line and a 2>&1 | jq pipeline will fail on it; redirect standard error (2>/dev/null) to drop it.

Namespaces — scope-namespace registrations (whether scope:<namespace> values must resolve to identity entities):

vectros namespace register team --context my-app --specificity-rank 10 --entity-backed
vectros namespace list  --context my-app
vectros namespace get   team --context my-app

register requires --context and --specificity-rank and creates a context-owned registration; a repeat name is a 400. list and get read the tenant-wide registration unless you pass --context. There is no CLI verb to update or delete a namespace.

Trusted issuers — IdP registrations for token exchange. --context is required on every verb:

vectros issuers register --context my-app --issuer-id auth0-prod \
  --issuer https://idp.example.test/ --jwks-uri https://idp.example.test/.well-known/jwks.json \
  --audience https://api.example.test
vectros issuers verify   auth0-prod --context my-app --idp-token-file ./login.jwt
vectros issuers list     --context my-app

A registration without --restricted-to-domain starts pending_verification and accepts no tokens until issuers verify succeeds. issuers update --clear-restricted-to-domain is refused unless the registration already holds the unrestricted (issuer, audience) pair, which a registration created scoped to a domain does not. To get an unrestricted issuer, issuers delete the scoped registration, issuers register a new one without --restricted-to-domain, and issuers verify it. A context holds one active issuer, and the delete is refused once any user has been created or matched through the issuer; in that case register the new issuer under a different app context.

Domains (CLI 0.24.0 and later) — domain ownership verification by DNS TXT record, the proof of control that issuers register --restricted-to-domain and webhook targets rely on. These verbs need an account-owner sign-in and take no --tenant, because verified domains are shared across your live and test tenants:

vectros domains register --domain example.com   # prints the TXT record to publish
vectros domains verify   <id>                   # one DNS lookup per call; never polls
vectros domains list
vectros domains delete   <id>                   # refused while an active webhook uses it

Registering a domain you already hold returns 409. verify reports VERIFIED or FAILED; re-run it after DNS propagates. list and verify report a domain whose periodic re-checks keep failing as REVOKED.

Provider configs (CLI 0.24.0 and later) — your bring-your-own-model provider configurations, owner-gated:

vectros provider-config create --tenant test --alias my-provider --provider-type ANTHROPIC_NATIVE \
  --billing-mode CUSTOMER_DIRECT --waiver-type byo-model-inference:customer-key --api-key-secret-file ./provider.key \
  --status DISABLED
vectros provider-config list   --tenant test
vectros provider-config get    <id>
vectros provider-config update <id> --status DISABLED
vectros provider-config delete <id>

create and list take --tenant test|live; get, update and delete address a config by its id. The provider credential is read from --api-key-secret-file <path> (- for stdin); there is no flag that takes it on the command line, and the platform never returns it. update is a partial patch: an omitted field, including the credential file, keeps the stored value. --alias is 1 to 64 lowercase letters, digits, - or _, unique within the tenant; the platform answers 400 for a new or changed alias outside that rule. An alias a config already holds is accepted, so a config whose alias is outside the rule keeps working. Callers must send the alias exactly: the match is case-sensitive. Changing the --provider-type of an existing config needs --endpoint stated in the same command, in either direction (--endpoint '' means the provider's default); the platform answers 400 otherwise, because a stored endpoint would keep overriding the Anthropic default. Moving a config to a different host, which includes --endpoint '' on a config that has an endpoint, also needs --api-key-secret-file again. --billing-mode is optional, and CUSTOMER_DIRECT is its only value and its default: your provider bills you directly. PLATFORM_BILLED is retired. CLI 0.25.0 and later refuse it locally and no longer have the --platform-token-factor and --platform-output-weight flags (an unknown option); the platform answers 400 when you try to set that mode and refuses calls through a config that still holds it. To move such a config to the only mode, run vectros provider-config update <id> --billing-mode CUSTOMER_DIRECT. --status defaults to ACTIVE, and a config can be ACTIVE only while your account holds a granted waiver for its --waiver-type; without one, create is refused with 400: pass --status DISABLED to store the config switched off, as in the example above. A call you route to a provider config (providerAlias on an inference request) is processed where that provider processes it and leaves the Vectros perimeter; this is separate from the platform-hosted model path. When the waiver is not in force the call is refused with a 403 whose errorCode is WAIVER_NOT_SIGNED, WAIVER_TEXT_CHANGED or WAIVER_REVOKED (never signed; the waiver in force for your tenant is older than the version Vectros requires; revoked by an owner); an account owner resolves all three in the developer portal (Model Providers). If your account has accepted the Business Associate Agreement with Vectros in the developer portal, an owner must also attest each config in the developer portal before it is usable; the CLI does not give the attestation, and an update that changes --provider-type or --endpoint withdraws it, after which the config's calls are refused with 403 until an owner attests again.

Reference

Command catalog

CommandPurpose
login / logoutBrowser sign-in (PKCE) and session teardown.
whoamiShow the authenticated tenant, environment, and principal (--tenant test|live).
bootstrapOne-shot least-privilege MCP credential (ssk_* + access profile + optional blueprint).
blueprint initScaffold a new blueprint file to edit.
blueprint validateStructural parse + scope gate + lint (creds-free).
blueprint planValidate, then preview what bootstrap or apply would provision (creds-free).
blueprint flattenPrint a blueprint split across files (include:) as the single document it composes to (creds-free).
blueprint applyProvision a blueprint into a tenant WITHOUT minting a key (for CI). --tenant required; deletion only with --prune; --stack <name> applies one stack of a split blueprint (see blueprints).
blueprint listList the bundled blueprint library.
blueprint-testApply → assert → teardown a blueprint against a live environment.
context create|list|get|destroyManage app contexts. destroy is the irreversible teardown — it asks you to re-type the context id before doing anything. A blueprint's service principal belongs to the whole tenant and is NOT removed; identity list-all still shows it, but after the destroy identity delete cannot reach it and answers Not found.
identity create|list|get|delete|inviteManage principals — --type user (tenant-wide), or an entity namespace (org/client, or one you register) — plus invite, which onboards a person into a context by email without a root key.
key issue|list|get|revoke|rotateManage scoped API keys (ssk_*).
role create|list|get|deleteManage context-scoped roles.
access grant|revoke|list|get|explainManage principal-to-context bindings. explain shows what a binding actually grants — its clauses plus a concrete access matrix.
join <context>Enroll a principal in a context (grant + key) in one step, and keep the key in the keyring.
assumeRe-mint your own token with one or more identity.<namespace> values switched — needs a role's assumable grant.
scripts push|list|get|deleteManage script objects: the versioned JS source a trigger rule runs. --context is required on all four.
agents list|get|create|versionManage stored agents (/v1/agents): a named, versioned model + system prompt + tool whitelist. create stores version 1 from a JSON or YAML definition file (an existing name comes back untouched); version writes the next version as a full replacement (--expected-version guards a concurrent edit, --restore brings a retired agent back); get --at-version <n> reads an earlier one; list --include-retired also shows retired agents. --context is required on all four. No delete: a retired agent keeps its name. create needs agents:c, version agents:u, list/get agents:r.
issuers register|update|list|get|delete|verifyManage registered third-party IdP issuers — the token-exchange trust anchors. register and get print a pending_verification registration's challenge; verify answers it with a JWT from a real login (--idp-token-file, stdin or --idp-token, never --token), activating the issuer (platform 0.45.0+).
namespace register|list|getManage scope-namespace registrations (whether scope:<namespace> values resolve to identity entities).
domains register|list|delete|verifyManage account-level domain ownership verification by DNS TXT record (owner-gated; CLI 0.24.0+). Shared across your live and test tenants, so no --tenant.
provider-config create|list|get|update|deleteManage your bring-your-own-model provider configs (owner-gated; CLI 0.24.0+). The provider credential is read from --api-key-secret-file, never from a flag value.
keyring list|use|show|doctor|prune|removeInspect and manage the local multi-principal keyring. switch is a top-level shortcut for keyring use.

The scope gate (data-plane allowlist)

The bootstrap and blueprint paths will only mint scopes on these data-plane resources, plus the narrow exceptions described below:

records · schemas · search · documents · folders · inference · entities · runs

runs is the end-user run capability: a role that grants runs:c lets a bound end user start a run of a stored agent, and the agent listing then shows that user a summary of each agent the grant covers. A grant may name one agent (runs:c:<agent>, runs:r:<agent>) to reach only that one; the gate refuses a named form the platform would never match (a wildcard, a qualifier that cannot be an agent name, a qualifier on any letter but c or r). runs:r reads runs. Defining or reading an agent (agents) stays control-plane, so a role that runs an agent does not need it. A trigger may not be granted runs, directly or through a role it composes: the gate refuses it and names the trigger.

entities grants ordinary per-namespace identity-entity CRUD (creating/reading/ updating/deleting org/client/or any namespace you registered), gated by the same ownership rules as records. It does not grant any authority over the namespace registry itself.

profiles is a partial exception, and admission differs by op letter: profiles:r is admitted only unqualified — any qualifier rejects the whole entry, since the platform resolves no qualifier for r. profiles:u and profiles:d are admitted with or without a qualifier, including a literal principal id. profiles:c is admitted when qualified with the literal self (profiles:c:self) — the platform resolves self at the handler from the minted credential's own bound identity, never from anything the pack supplies — or, bare and unqualified, when the SAME clause also declares capabilities: [member-lifecycle] (the platform's own context-bounded, allowlisted mechanism for a role that invites/removes members without raw tenant-wide users:*). A bare profiles:c with no such capability, or a literal-principal qualifier on c (profiles:c:usr_<id>) with or without one, still hard-rejects — the capability unlock covers the bare form only. profiles:* is rejected outright — a wildcard carries no qualifier by construction.

scripts has one admitted form: scripts:x:<name> (execute one named script). The qualifier is required, because a bare scripts:x would reach every script in the context, including ones added later. The script's own writes are still checked against the caller's data permissions. scripts:c and the rest of scripts stay rejected.

keys, app-contexts, users, billing, admin, namespaces, triggers, agents, any other form of scripts, any unknown resource, or a bare * wildcard are rejected with no partial exception, and the command mints nothing and exits non-zero. There is no override flag. Updating or deleting a namespace (PUT/DELETE /v1/namespaces) needs a root key, and registering one (POST /v1/namespaces) needs a root key or an owner-only bootstrap capability, regardless of any scope a token carries — namespaces is not a resource the bootstrap loader mints as a scope. scripts authoring and triggers are refused too — not as root-key-only surfaces, but because they are not data-plane resources; the gate names them explicitly rather than as unrecognized ones: script authoring and trigger declaration are admin-shaped, design-time surfaces, and the platform puts them out of reach of an ordinary confined role. (The gate is an allow-list: it accepts only the resources and forms above, so a resource it has never heard of is rejected by default.)

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 — plus x (execute) on scripts. Author explicit resource:op forms: coarse verbs and the ops-wildcard resource:* are rejected when authored. A trailing qualifier (e.g. records:r:intake_form, or documents:r:invoice to read only invoice-typed documents) only narrows access; it is accepted on records, entities and documents for every op, on profiles for c/u/d, and on scripts for x. A document with no governing schema matches only an unqualified documents grant.

Common flags

FlagApplies toMeaning
--env staging|productioncreds-bearing verbsTarget environment (default production).
--base-url <url>creds-bearing verbsOverride the API base URL.
--token <token>creds-bearing verbsBearer token; else read from the environment.
--jsonread verbsEmit machine-readable JSON.
--blueprint <name|path>bootstrapA bundled name or a path to your own file.
--blankbootstrapCredential only (read-only data-plane, no schemas).
--no-mergebootstrapStill mints/stores — print the config snippet instead of merging it.
--rotatebootstrapRevoke + re-mint this machine's key.
--require-verified-issuersbootstrap, blueprint applyExit 4 (after the apply completed) when an issuer is still pending_verification; without it a pending issuer still exits 0.
--yes / -ybootstrap, blueprint applySkip confirmations (agent / CI). apply requires it when there is no terminal.
--seedblueprint applyAlso write the blueprint's sample seed records. Off by default, in both tenants (the opposite of bootstrap, which seeds unless --no-seed).
--pruneblueprint applyAlso remove the triggers this blueprint provisioned earlier and its file no longer declares (matched by a stored marker, not a verified identity). Off by default.
--stack <name>blueprint plan|applyPlan or apply only the named stack of a split blueprint (repeatable). The whole blueprint is still validated and gated; what the stack needs from other stacks (schemas, scripts, roles and namespaces it refers to) must already be live and is checked before anything is written. Cannot be combined with --prune.
--confirm-existing-principalbootstrap, blueprint applyAuthorize using a service principal that already exists in your tenant, including a trigger's service principal that this blueprint did not mark (standing consent in a pipeline).
--allow-tenant-wide-namespacesbootstrap, blueprint applyPermit a blueprint's namespaces[] entry marked tenantWide: true to register a tenant-wide namespace. Without it, such a blueprint is refused (exit 2). Registration also needs the account owner's authority.
--allow-script-adoptionbootstrap, blueprint applyPermit the blueprint to push a script onto a name that already exists without a blueprint marker (a hand-pushed script), taking it into the blueprint's management. A name owned by a different blueprint is refused regardless of this flag.
--allow-agent-adoptionbootstrap, blueprint applyPermit the blueprint to write its agent over an agent that already exists with no blueprint mark (made by hand): it is marked as the blueprint's and given the declared definition as its next version if that differs. An agent managed by a different blueprint is refused regardless.
--keepblueprint-testSkip teardown; leave the graph for inspection.
--forcecontext destroySkip the interactive re-type-the-id confirmation (required when stdin is not a terminal).
--tenant test|livebootstrap, blueprint-test, blueprint apply, join, context, role, access, key, scripts, agents, issuers, identity, provider-config create|listWhich of your tenants the command targets (default live; blueprint apply has no default and requires it). domains takes none.
--set name=value / --values <file>blueprint validate|plan|apply, bootstrapSupply install-time input values (file blueprints only).

Bootstrap exit codes

(blueprint apply has its own set, above.)

0 applied (also --help, and answering no at "Apply this plan?") · 1 failed: a bad flag, an unknown or malformed blueprint, a missing or invalid --set input, a declared issuer scope the platform did not apply, or any error while applying · 2 refused by a gate: the scope gate or the capability gate rejected the blueprint, an identity it references could not be resolved, or it declares a tenant-wide namespace without the opt-in (the message says what, if anything, was already provisioned) · 3 a confirmation it did not get (an existing service principal, a trigger's existing service principal that this blueprint did not mark, a key that cannot be recovered) · 4 applied in full, but --require-verified-issuers was given and an issuer is still pending_verification.

Notes & limits

  • SDK pin. The CLI bundles a matching 0.50.0 SDK build into its binary; you do not install or pin the SDK separately to use the CLI.
  • bootstrap needs a sign-in. It uses your stored vectros login session; without one it takes a bridge token from the developer portal (--token, VECTROS_BOOTSTRAP_TOKEN, or pasted at a prompt in a terminal). Run vectros login once and later runs, --yes runs included, need no token.
  • --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 left in place; each distinct context it creates counts toward the account's limit of 100 app contexts (live and test counted separately).
  • Little control-plane provisioning through bootstrap/blueprints. Keys, billing, admin, and agents scopes, and most of profiles, are portal-only by design; the scope gate admits only the narrow exceptions listed above.

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.