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
bootstrapcommand 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
| Command | Purpose |
|---|---|
login / logout | Browser sign-in (PKCE) and session teardown. |
whoami | Show the authenticated tenant, environment, and principal (--tenant test|live). |
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 or apply would provision (creds-free). |
blueprint flatten | Print a blueprint split across files (include:) as the single document it composes to (creds-free). |
blueprint apply | Provision 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 list | List the bundled blueprint library. |
blueprint-test | Apply → assert → teardown a blueprint against a live environment. |
context create|list|get|destroy | Manage 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|invite | Manage 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|rotate | Manage scoped API keys (ssk_*). |
role create|list|get|delete | Manage context-scoped roles. |
access grant|revoke|list|get|explain | Manage 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. |
assume | Re-mint your own token with one or more identity.<namespace> values switched — needs a role's assumable grant. |
scripts push|list|get|delete | Manage script objects: the versioned JS source a trigger rule runs. --context is required on all four. |
agents list|get|create|version | Manage 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|verify | Manage 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|get | Manage scope-namespace registrations (whether scope:<namespace> values resolve to identity entities). |
domains register|list|delete|verify | Manage 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|delete | Manage 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|remove | Inspect 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
| Flag | Applies to | Meaning |
|---|---|---|
--env staging|production | creds-bearing verbs | Target environment (default production). |
--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). |
--no-merge | bootstrap | Still mints/stores — print the config snippet instead of merging it. |
--rotate | bootstrap | Revoke + re-mint this machine's key. |
--require-verified-issuers | bootstrap, blueprint apply | Exit 4 (after the apply completed) when an issuer is still pending_verification; without it a pending issuer still exits 0. |
--yes / -y | bootstrap, blueprint apply | Skip confirmations (agent / CI). apply requires it when there is no terminal. |
--seed | blueprint apply | Also write the blueprint's sample seed records. Off by default, in both tenants (the opposite of bootstrap, which seeds unless --no-seed). |
--prune | blueprint apply | Also 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|apply | Plan 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-principal | bootstrap, blueprint apply | Authorize 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-namespaces | bootstrap, blueprint apply | Permit 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-adoption | bootstrap, blueprint apply | Permit 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-adoption | bootstrap, blueprint apply | Permit 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. |
--keep | blueprint-test | Skip teardown; leave the graph for inspection. |
--force | context destroy | Skip the interactive re-type-the-id confirmation (required when stdin is not a terminal). |
--tenant test|live | bootstrap, blueprint-test, blueprint apply, join, context, role, access, key, scripts, agents, issuers, identity, provider-config create|list | Which 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, bootstrap | Supply 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.
bootstrapneeds a sign-in. It uses your storedvectros loginsession; without one it takes a bridge token from the developer portal (--token,VECTROS_BOOTSTRAP_TOKEN, or pasted at a prompt in a terminal). Runvectros loginonce and later runs,--yesruns included, need no token.--set/--valuesapply to file blueprints only. Bundled blueprints are fixed and declare no inputs; supplying values against one is a usage error.blueprint-testnever 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
agentsscopes, and most ofprofiles, 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.