Skip to main content

@gravity-rail/cli

Command-line interface for Gravity Rail — manage workspaces, Agents, Chats, Workflows, and other resources from your terminal.

gr workflows list -w $WORKSPACE
gr chats list -w $WORKSPACE -o json | jq '.[].summary'
gr members create -w $WORKSPACE --data '{"first_name":"Jane","email":"jane@example.com"}' --allow-write

Installation​

npm install -g @gravity-rail/cli
# or one-shot
npx @gravity-rail/cli --help

Requires Node.js 18+.

Authentication​

OAuth (interactive)​

gr login                    # opens browser for OAuth authorization
gr whoami # verify your identity
gr logout # clear cached credentials

gr login runs authorization code + PKCE (S256) against Gravity Rail's pinned first-party OAuth client, discovered from the server's /.well-known/oauth-authorization-server document. That client is public: it has no client secret, because a CLI distributed to end users cannot keep one (RFC 8252 §8.5). PKCE, not a shared secret, is what protects the exchange.

A self-hosted server old enough not to advertise a first-party client falls back to RFC 7591 dynamic client registration, which does issue this installation its own confidential client. Both kinds of profile refresh normally; nothing needs to be re-authorized when a server gains the pinned client, though the next gr login on that profile will switch to it.

Access tokens refresh automatically. When several gr commands on one machine need a refresh at the same time, one of them exchanges the refresh token while the others wait briefly and reuse the result, so parallel runs no longer sign each other out. A refresh that fails for a temporary reason (network error, timeout, or server error) keeps your stored credentials and exits with an error; retry the command. Only when the server rejects the stored refresh token is that one profile cleared, and gr login (or gr auth login --name <profile>) signs it back in.

Multi-account profiles​

Like aws --profile / gh auth switch, the public CLI supports multiple named accounts:

gr auth login --name work       # OAuth into a named profile (also sets it current)
gr auth login --name personal
gr auth list # list profiles for the current --env
gr auth switch --name personal # change the default profile
gr auth logout --name work # clear one profile

# Per-invocation selection (does not change the stored default)
gr whoami --profile work
gr tasks list -w $WORKSPACE --profile personal
export GRAVITY_RAIL_PROFILE=work

gr login / gr logout remain as shortcuts for the active profile (or --name).

Credential store (security)​

ItemDetail
Location~/.gr-cli/credentials-<env>.json (e.g. credentials-prod.json)
Directory mode0700 on ~/.gr-cli
File mode0600 on credential files
ContentsOAuth client id (+ secret only for a dynamically registered client) + tokens, and/or token-only dev profiles (+ optional workspace UUID)
Not storedGRAVITY_RAIL_API_KEY (process environment only; always overrides profiles)
Name validationProfiles allow name or workspace/member; env names are allowlisted
LoggingCLI code never writes token or secret values to stdout/stderr

Security review notes: tokens never leave the local filesystem except on HTTPS calls to the Gravity Rail API. There is no cloud sync of CLI credentials. Rotate by gr auth logout --name <profile> (or deleting the store file) and logging in again. Multi-user machines should rely on OS home-directory isolation plus the 0600/0700 modes. Do not commit ~/.gr-cli into repositories or bake it into container images.

Profile resolution order for a command:

  1. GRAVITY_RAIL_API_KEY (if set — skips the store entirely)
  2. --profile <name> (or --account)
  3. GRAVITY_RAIL_PROFILE
  4. currentProfile in the credential store (from gr auth switch / last login)
  5. Profile name default

API Key (non-interactive)​

export GRAVITY_RAIL_API_KEY=your-api-key
gr tasks list -w $WORKSPACE

Useful for scripts, CI/CD, and automation. Create scoped keys from Account API Keys or via @gravity-rail/sdk. API keys are not written into the profile store.

Organizations that require SSO​

Workspaces in an SSO-enforced organization need an org-scoped session in addition to your account login. When you run a gr command against such a workspace after gr login, the CLI opens your browser once to complete the organization's SSO, captures the resulting session over a local 127.0.0.1 callback, and caches it under your profile — subsequent commands reuse it silently until it expires. No token is ever placed in a URL.

For non-interactive use (CI, scripts, code-interpreter sandboxes, or any machine with no browser), org SSO cannot run; use an API key instead — API keys are exempt from the org SSO gate:

export GRAVITY_RAIL_API_KEY=your-api-key   # set GRAVITY_RAIL_NO_BROWSER=1 to force the API-key hint

Work with a Coding Agent​

Give an agent the CLI's bootstrap instructions, then use each domain's --help to discover its commands:

gr get-started --format llm

Command Pattern​

gr <domain> <action> [options]
gr <domain> <sub-resource> <action> [options]
gr tasks list -w $WORKSPACE                            # list tasks
gr tasks get -w $WORKSPACE --id 42 # get specific task
gr tasks create -w $WORKSPACE --data '{"name":"New"}' --allow-write # create
gr chats labels list -w $WORKSPACE # sub-resource

Every domain supports --help:

gr --help               # all domains
gr tasks --help # task commands
gr chats labels --help # sub-resource commands

Write Safety​

The CLI is read-only by default. Any command that creates, updates, or deletes data requires the --allow-write flag:

# Reads — no flag needed
gr members list -w $WORKSPACE
gr members list -w $WORKSPACE --search "Smith"
gr members list -w $WORKSPACE --page 2 --page-size 100
gr members list -w $WORKSPACE --all
gr workflows get -w $WORKSPACE --id 5

# Writes — must opt in
gr members create -w $WORKSPACE --data '{"first_name":"Test"}' --allow-write
gr tasks delete -w $WORKSPACE --id 42 --allow-write

This prevents accidental mutations when exploring production data or running under automation.

Output Formats​

Output adapts to context: human-readable tables in interactive terminals, JSON when piped.

# Table (default in TTY)
gr tasks list -w $WORKSPACE

# JSON (default when piped, or explicit)
gr tasks list -w $WORKSPACE -o json

# JSONL (one object per line — great for streaming)
gr tasks list -w $WORKSPACE -o jsonl

# Pipe to jq
gr members list -w $WORKSPACE -o json | jq '.[].email'

--jq — filter without a pipe​

--jq runs the filter against the JSON the CLI just produced, so the input is valid by construction and there is no pipeline to get wrong. It implies -o json.

gr tasks list -w $WORKSPACE --jq 'length'
gr workflows get -w $WORKSPACE --id 3 --jq '{id, name}'

Prefer it over | jq in scripts and agent tooling: a mistake in the filter is reported as a filter error, rather than surfacing as a parse error about output you cannot see. It needs the jq binary on PATH.

# Chain commands
gr chats list -w $WORKSPACE -o json | jq '.[0].id' | xargs -I{} gr chats get -w $WORKSPACE --id {}

Data Input​

Pass data for create/update operations via inline JSON, file, or stdin:

# Inline JSON
gr tasks create -w $WORKSPACE --data '{"name":"My Task"}' --allow-write

# From file
gr workflows create -w $WORKSPACE --file workflow.json --allow-write

# From stdin (pipe)
echo '{"name":"Piped Task"}' | gr tasks create -w $WORKSPACE --allow-write
cat member.json | gr members update -w $WORKSPACE --id 42 --allow-write

Global Options​

FlagDescription
--api-url <url>Override API base URL
--profile <name>Named account profile (alias: --account)
-w, --workspace <uuid>Workspace UUID (required for most commands)
-o, --output-format <fmt>Output format: json, jsonl, table
-v, --verboseVerbose output to stderr
--allow-writeRequired for create/update/delete operations
--id <id>Entity ID (for get/update/delete)
-d, --data <json>Inline JSON payload
-f, --file <path>Read JSON payload from file
--helpShow help
--versionShow version

Environment Variables​

VariableDescription
GRAVITY_RAIL_API_KEYAPI key for non-interactive authentication
GRAVITY_RAIL_PROFILEDefault named credential profile
GRAVITY_RAIL_API_URLOverride API base URL (default: https://api.gravityrail.com)
GRAVITY_RAIL_FRONTEND_URLOverride frontend URL (default: https://app.gravityrail.com)

Exit Codes​

CodeMeaning
0Success
1General error
2Authentication required (run gr login or set GRAVITY_RAIL_API_KEY)
3A human-in-the-loop (HITL) interrupt requires out-of-band action before the operation can continue
4No assistant reply — a --message turn made tool calls but returned no final summary, or an inference error occurred with no final message (side effects may have been applied)

UI prompts (present_choice_list / render_ui, and the connect_*_account login prompts) do not pause the agent. The tool returns straight away and the prompt arrives as a tool result, which the CLI draws in the terminal when stdin is a TTY: OpenUI markup becomes an arrow-key picker (ChoiceButtons, with Space to tick a multi-select) or field-by-field form prompts, and a connect prompt prints the link to open. Your answer is then sent as an ordinary chat message, so the agent picks it up on its next turn. Manager (gr manage) and Concierge (gr concierge chat) share this path. Typing prose instead of using the controls sends exactly what you typed. When stdin is not a TTY the prompt is printed and left unanswered, and the turn ends normally.

Proposed messages. When the Manager wants to send an email from your Gmail or a Slack or Teams message, it does not send it and does not pause: the draft arrives as a tool result. With a TTY, gr manage prints it and asks Send, Discard or Not now. Send and Discard settle it once, for every surface. Not now, and any run without a TTY, leaves the draft open; open the Chat on the web to edit it or decide later.

Approvals, access grants and checkout still interrupt the run and resume it in place; unsupported interrupt types exit 3 with the JSON contract below.

When a concierge command run with --message (non-interactive mode) hits a HITL interrupt the CLI cannot resolve on its own, it exits 3 and writes a single machine-readable JSON object to stdout:

{
"error": "hitl_interrupt",
"message": "A human-in-the-loop interrupt requires out-of-band action before the operation can continue.",
"resume": { "chatId": 42, "chatUuid": "…", "interruptId": "int-abc" },
"interrupt": { "type": "stripe_checkout", "interrupt_id": "int-abc", "url": "…" }
}

The interrupt object is intentionally limited to routing fields (type, interrupt_id, and a redirect url when present); the raw server payload is not forwarded, as it may contain sensitive data. Use resume.chatUuid / resume.interruptId to continue the flow out-of-band (e.g. in the web app).

Commands​

Core​

DomainDescription
tasksWorkflow tasks — CRUD, archive, clone
chatsConversations — CRUD, labels, filters, messages, export, summaries
membersContacts and team — CRUD, labels, filters, roles, fields, import/export
workspacesWorkspace management — CRUD, features, themes, invitations, export/import
workflowsConversational workflows — CRUD, notes, contributors, templates, analytics
journeysJourney definitions — CRUD, authoring, drafts
agentsAutonomous AI members — CRUD, archive
assistantsAI personas — CRUD with model and voice configuration
assignmentsTask-based conversations — CRUD, messages, tools

Data & Content​

DomainDescription
data-typesSchema-driven forms and records — CRUD, field indexing, computed fields
filesDocuments and folders — CRUD, sharing, semantic search, labels
sitesCustomer portals — CRUD, pages, menus, web crawling
eventsEvent rules — triggers, CEL conditions, delayed actions
calendarsScheduling — calendars, events, event types, availability, Google sync
qualificationsWorkflow Scenarios, synthetic test runs, and criterion results
queriesUnified Query Engine — fields, validate, preview, run, syntax reference
data-reportsForm Reports — preview a report as the Agent would run it

Global (no workspace)​

DomainDescription
conciergeGlobal Concierge — interactive chat, PSTN --call, SMS --sms
account verify-phoneVerify your account phone (required before concierge outbound)

Communication​

DomainDescription
phone-numbersVoice and SMS phone numbers — provisioning, calls, messages
recordingsCall recordings — get a presigned download URL, save the WAV
inboxesEmail inboxes — threads, attachments, routing
operator-groupsLive operator routing — groups, presence, strategies
notification-rulesAlert configuration — event-based notifications

Integrations​

DomainDescription
discord-botsDiscord bot management — slash commands, threads, account linking
slack-appsSlack app management — installations, threads, accounts
fhir-connectionsFHIR healthcare connections — patients, practitioners, encounters
patientsyncPatientSync PSTN-transfer connection — configure / status / delete (singleton per workspace)
documo-faxDocumo (mFax) inbound fax — install / configure / setup / verify / status / faxes
app-connectionsPlatform app integrations
mondayMonday.com — boards, columns, webhooks

Platform​

DomainDescription
api-keysAPI key management — workspace and global scopes
subscriptionsSubscription management
reportsUsage reports — AI tokens, voice minutes, SMS, storage
ai-modelsAvailable AI models (no workspace required)
featuresFeature registry (no workspace required)
custom-toolkitsCustom tool definitions
mcp-serversMCP server connections
milestonesGoal tracking
supervisorsAI supervisor management
access-grantsTemporary access delegation
pronunciationsVoice pronunciation overrides
appsOAuth app management
oauthOAuth provider connections
authTwo-factor authentication, credentials, and password management
orgOrganization membership, invitations, org domains, and webhooks

Recipes​

Export all chats as JSON​

gr chats list -w $WORKSPACE -o json > chats.json

List chat messages with pagination​

# Default returns up to 100 messages (API max)
gr chats messages list -w $WORKSPACE --id $CHAT_ID

# Paginate with --limit and --offset
gr chats messages list -w $WORKSPACE --id $CHAT_ID --limit 50 --offset 100

Filter chats by type​

# Only manager (operator-side) chats, sorted most-recent-first.
gr chats list -w $WORKSPACE --chat-type manager
# Assign a phone number from the org pool to a workspace…
gr org phone-numbers assign --org-uuid $ORG_UUID --phone-number-id $PN_ID --workspace-uuid $WORKSPACE --allow-write

# …then enable it (link inboxes, voice config) so it can place/receive calls.
gr phone-numbers link -w $WORKSPACE --id $PN_ID --allow-write

Manage pronunciations from the workspace context​

# `pronunciations` resolves the org from -w; you don't need --org-uuid.
gr pronunciations list -w $WORKSPACE
gr pronunciations create -w $WORKSPACE --term "GravityRail" --respelling "GRA-vit-ee rail" --allow-write

Download a call recording​

# Get a single short-lived presigned URL for the whole call.
gr recordings download-url -w $WORKSPACE --chat-id 42

# Or download the WAV straight to a file.
gr recordings download -w $WORKSPACE --chat-id 42 -o call.wav --allow-write

Register and verify an org domain​

# Register the domain and get the ownership TXT record
gr org domains register --org-uuid $ORG_UUID --domain example.com --allow-write

# Verify ownership TXT
gr org domains verify-ownership --org-uuid $ORG_UUID --domain-uuid $DOMAIN_UUID --allow-write

# Email DNS: enable records, then verify SPF/DKIM/DMARC/MX/return-path
gr org domains email enable --org-uuid $ORG_UUID --domain-uuid $DOMAIN_UUID --allow-write
gr org domains email verify-mx --org-uuid $ORG_UUID --domain-uuid $DOMAIN_UUID --allow-write

# Site DNS: check the CNAME resolves, enable custom site routing, then verify
gr org domains site preflight --org-uuid $ORG_UUID --domain-uuid $DOMAIN_UUID
gr org domains site enable --org-uuid $ORG_UUID --domain-uuid $DOMAIN_UUID --allow-write
gr org domains site verify-cname --org-uuid $ORG_UUID --domain-uuid $DOMAIN_UUID --allow-write

Host many sites under one wildcard​

# Enable a verified domain as a parent: publish *.<domain> first, then enable
gr org domains site preflight --org-uuid $ORG_UUID --domain-uuid $PARENT_UUID --child-hosting
gr org domains site enable --org-uuid $ORG_UUID --domain-uuid $PARENT_UUID --child-hosting --allow-write

# Add hosts one at a time; each reports its own result, and the command exits
# non-zero if any failed. New hosts verify on their own within minutes.
gr org domains site children add --org-uuid $ORG_UUID --domain-uuid $PARENT_UUID \
--label clinic-a --label clinic-b --allow-write
gr org domains site children add --org-uuid $ORG_UUID --domain-uuid $PARENT_UUID \
--labels-file labels.txt --allow-write
gr org domains site children list --org-uuid $ORG_UUID --domain-uuid $PARENT_UUID

# Remove hosts: certificate, routing and registration. --confirm also removes
# hosts that still route sites.
gr org domains site children remove --org-uuid $ORG_UUID --domain-uuid $PARENT_UUID \
--label clinic-a --allow-write

Find members by label​

gr members list -w $WORKSPACE -o json | jq '[.[] | select(.labels[]?.name == "VIP")]'

Bulk create from a file​

# members.jsonl — one JSON object per line
cat members.jsonl | while read line; do
echo "$line" | gr members create -w $WORKSPACE --allow-write
done

Pipe workspace config between environments​

gr workspaces get -w $SOURCE_WORKSPACE -o json | \
gr workspaces create --data "$(cat -)" --allow-write

Check configuration readiness​

gr workspaces configuration-readiness -w $WORKSPACE -o json

The combined read fails closed in its configurationReady field when configuration-health collectors fail, critical or warning findings remain, post-import bindings are missing, skipped EventRules remain outstanding, or a readiness scan is truncated. Informational configuration findings are reported but do not block. This is a saved-configuration check, not an end-to-end launch or patient-experience certification.

List all workflows with their task counts​

gr workflows list -w $WORKSPACE -o json | jq '.[] | {name, task_count: (.tasks | length)}'

Check who's live as an operator​

gr operator-groups list -w $WORKSPACE -o json | jq '.[].name'

Concierge setup over your phone (PSTN / SMS)​

Outbound concierge modes ring or text your verified account phone only — no destination argument. Verify once, then initiate:

# One-time: OTP SMS + TCPA notice (writes Account.phone + phone_verified_at)
gr account verify-phone --allow-write
# Optional: pass E.164 inline instead of the prompt
gr account verify-phone --phone +15551234567 --allow-write

# Server originates call; CLI exits when Twilio returns callSid
gr concierge chat --call --allow-write

# Server sends opening SMS; CLI exits when messageSid is returned
gr concierge chat --sms --allow-write

--call and --sms are mutually exclusive. They cannot be combined with --voice or --realtime on the same gr concierge chat invocation. (gr concierge --call / --sms are equivalent shorthand.)

If the API returns 412 account_phone_unverified, run gr account verify-phone first.

Journey authoring​

The same commands are available through the internal yarn gr entry point. All examples require workspace membership and journeys:write (which implies journeys:read, also checked when cloning).

gr journeys create -w $WORKSPACE --data '{"name":"Onboarding","status":"draft"}' --allow-write
gr journeys authoring -w $WORKSPACE --id 42 -o json
gr journeys definition put -w $WORKSPACE --id 42 --file definition.json --allow-write
gr journeys definition validate -w $WORKSPACE --id 42 -o json

definition put replaces the complete executable definition. Include expectedUpdatedAt from the latest authoring read, ordered touches, and endings. Each touch can carry eventRules, an incoming wait, and a branch with ordered routes. Endings carry celCondition and/or filterId predicates and eventRules; they need no incoming edge. Omitting goals preserves them; sending an empty array removes them. removals ([{stepUuid, continueAt}]) names where members of a removed step continue; a removed step that enrollments hold without an entry is refused with 409 journey_v2_removal_needs_continuation, which lists each such step's stepUuid and enrollmentCount. A minimal definition.json is:

{
"expectedUpdatedAt": "2026-09-26T00:00:00Z",
"touches": [{ "name": "Welcome", "eventRules": [] }],
"endings": []
}

A branch route can include memberPredicate, an unnamed Query IR condition owned by the route. For example, this branch selects Members with an email:

{
"routes": [
{
"name": "Has email",
"memberPredicate": {
"kind": "compare",
"field": "member.email",
"op": "notEmpty"
}
},
{ "name": "Otherwise", "memberPredicate": null }
]
}

Use this object as a touch's branch in the complete definition. The owned predicate is ANDed with any filterId and celCondition; it creates no saved MemberFilter. Reading or changing it additionally requires members:read and access to its fields. On definition put, omission preserves an existing owned predicate and explicit null clears it. definition validate reports decision_rule_predicate_invalid when a stored owned predicate cannot compile.

Existing steps and routes retain identity through their UUIDs. Omit a step or route UUID to create it; use request-local key values for new rejoin targets. EventRules require UUIDs: preserve existing ones when editing, and generate new ones when copying actions into another Journey. Read responses are not replacement payloads; construct the touches/endings structure explicitly.

To preserve an unfinished editor document without changing the executable Journey, use the separate draft commands:

gr journeys draft put -w $WORKSPACE --id 42 --file draft.json --allow-write
gr journeys authoring -w $WORKSPACE --id 42 -o json
gr journeys draft delete -w $WORKSPACE --id 42 --expected-updated-at '2026-09-26T00:00:00Z' --allow-write

draft.json contains expectedUpdatedAt and document with version, model, and optional goalsDirty. Use the editor's document format. Read it back as authoringDraft through journeys authoring. Discarding that document preserves the executable definition. Neither draft command publishes a Journey.

Use journeys update --id 42 --data '{"status":"active"}' --allow-write to publish, or status: "paused" to pause. Publishing runs server validation; definition validate reports stored-definition issues without publishing. A stale expectedUpdatedAt is rejected: reload and reconcile rather than blindly retrying.

Preview how a Journey would run for a Persona's test Member or a real Member. The preview sends and writes nothing:

gr journeys simulate -w $WORKSPACE --id 42 --persona 7
gr journeys simulate -w $WORKSPACE --id 42 --member 1001 --source enrollment --until 2026-12-01T00:00:00Z
gr journeys simulate -w $WORKSPACE --id 42 --persona 7 --changes what-if.json --conversation-default noReply -o json

--changes holds an array of what-if changes, or an object with any of changes, conversationDefault and conversationOutcomes. A change sets target to value at at, or relative to a step or action with anchor: {kind: afterStep|afterAction|beforeStep, uuid, offsetSeconds?}. --conversation-default overrides the file. The default view prints one line per event and the outcome, without values or message bodies; -o json prints the full response.

Workflow revision exports​

workspaces export defaults to the active Workflow snapshot. Use --revision-mode all to include history and drafts. Version 2.0 archives require a revision-aware server and create new Workflows when imported, preserving active/draft roles. They refuse existing Workflow matches; use --create-all to create a separate copy.

gr workspaces export -w "$WORKSPACE_UUID" --workflow-id 14 --revision-id 87
gr workspaces export -w "$WORKSPACE_UUID" --revision-mode all
gr workspaces export -w "$WORKSPACE_UUID" --format zip --output export.zip

--revision-id requires --workflow-id. Selected and active snapshots use version 1.0 and apply to an editable draft when imported into an existing Workflow. They do not activate the selected revision. JSON and ZIP use the same selection options.

The public workspace export API supports only the channels exclusion in every revision mode. All-revision archives preserve that exclusion. Other public exclusion values are rejected.

The CLI rejects legacy active-only responses to all-revision or selected exports. It checks JSON selection metadata or server ZIP provenance before saving, preserving an existing output file on rejection. ZIP provenance requires the server update before this client release; revision-aware JSON alone does not satisfy the ZIP guard. The default active snapshot remains compatible with legacy servers. Validation adds no archive size limit or permission requirement.

Shared dependency definitions are current exported Forms, files, and integrations, not historical snapshots of those resources.

License​

MIT

Publish and consume reusable Workflows​

Author in the owning workspace. workflows publish freezes the draft and queues its shared release. Bundles are how a published Workflow reaches another workspace: workflows catalog lists released Workflow and revision UUIDs to pin in a Bundle draft.

# Publisher
gr workflows publish -w "$PUBLISHER" --workflow-id "$WORKFLOW" --allow-write
gr workflows catalog -w "$PUBLISHER" -o json
gr bundles create -w "$PUBLISHER" --name "Starter Kit" --allow-write
gr bundles draft set -w "$PUBLISHER" --bundle "$BUNDLE" --file items.json --allow-write
gr bundles publish -w "$PUBLISHER" --bundle "$BUNDLE" --allow-write
gr bundles grant -w "$PUBLISHER" --bundle "$BUNDLE" \
--to organization --uuid "$ORGANIZATION" --allow-write

# Consumer: installs the latest version, then opts into updates
gr bundles install -w "$CONSUMER" --bundle "$BUNDLE" --allow-write
gr bundles policy -w "$CONSUMER" --installation "$INSTALLATION" --set auto --allow-write
gr bundles readiness -w "$CONSUMER" --installation "$INSTALLATION"

# Edit the installed Workflows: detach the Bundle. Updates stop.
gr bundles unsubscribe -w "$CONSUMER" --installation "$INSTALLATION" --allow-write

Installation creates the consumer's local Workflow ID and UUID; use those for consumer reads. Detaching keeps them and makes the Workflows editable. Installation and policy changes require workflows:admin in the destination plus publisher access; organization-admin status is not an additional requirement. When a Bundle upgrade changes an installed Form schema, the acting administrator also needs datatypes:write and Form write permission (Form admin permission for field-policy changes, including new fields). Missing Form authority or an archived Form leaves the held release active and reports that repair is required; it does not revoke the Bundle subscription.

Bundle lifecycle​

TaskCommand
Find published Workflow/revision UUIDs for compositionworkflows catalog
Inspect publisher subscriber versions/policiesbundles subscribers --bundle <uuid>
Edit package metadatabundles update --bundle <uuid> --name "Starter Kit" --description "Contents"
Create a packagebundles create --name "Starter Kit"
Inspect/edit the package draftbundles draft get/set --bundle <uuid>
See what the next version would change, publishing nothingbundles draft preview --bundle <uuid>
Publish an immutable version: every Workflow's newest published revision and every other item as its source is now; prints what changes firstbundles publish --bundle <uuid> --release-notes "What's new"
Inspect summary and latest contentbundles get --bundle <uuid>
Inspect history or one versionbundles versions/version --bundle <uuid>
Share within the publisher organizationbundles grant --bundle <uuid> --to organization --uuid <organization>
Install the latest version (initially pinned; pre-selects the workspace default, when one exists and you hold phones:read, for phone slots the bindings leave out)bundles install --bundle <uuid>
Follow new releasesbundles policy --installation <uuid> --set auto
Hold the installed releasebundles policy --installation <uuid> --set pinned
Detach: stop updates, keep installed content, make its Workflows editablebundles unsubscribe --installation <uuid>
Preview an upgradebundles preview --installation <uuid> --to 2
Apply an upgradebundles upgrade --installation <uuid> --to 2
Inspect missing local dependenciesbundles readiness --installation <uuid>
Supply local dependencies ({"kind": "new_phone_number"} creates the installation's phone number; {"kind": "provider_phone_number", "uuid": "<uuid>"} creates one and links one of the organization's numbers to it, listed by phone-numbers linkable; an operator_groups.<key> slot takes {"kind": "operator_group", "id": <group id>})bundles bind --installation <uuid> --bindings bindings.json
Fill an Inbox slot by creating its Inbox: with an address now, on the platform domain (--create-inbox, {"kind": "new_inbox"}), or with no address yet, for an address on your organization's domain later (--create-inbox-without-address, {"kind": "new_inbox_without_address"}; it sends and receives nothing until given an address in its settings, and readiness reports it as waiting)bundles bind --installation <uuid> --create-inbox-without-address program.inbox
Read per-workspace Ability settingsbundles settings --installation <uuid>
Change a filled Ability setting, a shared install field (one value several settings hold, such as the Pathways practice ID a Site and an Ability share), a Workflow's Inbox or phone number, the phone number or Inbox a Bundle's routing answers on, or the operator group it rings (a group is bound with, or after, an endpoint that rings it), without detachingbundles bind --installation <uuid> --bindings setting.json --replace

Commands require a workspace (-w or a workspace profile); mutations also require --allow-write. Draft item files contain { "items": [...] }; Workflow items name workflowUuid and revisionUuid, and Form/Site items carry definitions. Configuration is reusable software. Records and credentials stay local.

Publishing does not ship the revision a draft names: each Workflow goes out at its newest published revision, and each Data Type (kind form), Journey, saved filter and routing item is read from its source again (a Data Type definition in the file is replaced by the source Data Type's). bundles publish prints each item the version adds, changes or removes, a Workflow's revision before and after, and each item whose newest state cannot go into a Bundle with a closed reason and its status: held (it stays as the last published version carried it, which can still go) or blocked (fix or remove it first: an item the last published version did not carry, and so every item of a first version, blocks the version when it cannot go, and so does a carried one whose last published state cannot go either). It then publishes exactly that list and refuses if it changed in between, or if nothing would change. With -o json the published version carries the list as publishPlan. bundles draft preview prints the same list and publishes nothing; it needs no --allow-write.

For safe editing, retain draftGeneration from bundles draft get -o json and pass it as --expected-generation to draft set or publish. Omitting it reads the current generation just before the write and only detects changes during that request sequence. The server's refusal details are preserved.

Use bundles get --bundle <uuid> or bundles install --bundle <uuid> to reach a Bundle by UUID without paging bundles list. The Bundle must be visible to the workspace: it owns the Bundle, or a live grant names it.

bundles grant --to organization --uuid <org-uuid> shares a published Bundle with its publishing organization. bundles grant --to global shares it with every workspace and requires a superuser account. A draft set file may carry "links": [{"label", "url"}], up to ten named https links published with the Bundle; a file without links keeps the draft's current links.

bundles get -o json returns one { summary, version } object; version is null before publication. Revocations also return JSON when requested. Full UUIDs in tables can be copied directly into later commands.

Bundle grants use full source visibility; restricted Bundle disclosure remains unavailable while Form and Site definitions are copied at installation.

Workflow qualification runs​

Create a Persona and Scenario in the Workflow Evaluate screen, or use gr personas create and gr qualifications scenarios create --file scenario.json. A Persona's test Member is created on first use; manage it with gr personas test-member get|create|reset --id <persona-id> (create and reset need --allow-write). Pick the intended Member role for the Persona. If the Persona has no role, test launch uses the workspace default Member role; missing or unsafe role setup must be corrected by an authorized workspace administrator. The CLI never changes a role or permissions to make a run start.

Run one Scenario against a fixed revision before repeating it:

gr qualifications runs batch -w $WORKSPACE_UUID --workflow-id 42 \
--workflow-revision-id 108 --scenario-ids 7 \
--realtime-models xai:realtime:voice-agent-2 --rounds 1 \
--evaluate --out qualification-results.jsonl --allow-write

Increase --rounds and optionally --concurrency for a fixed cohort. The first run completes before parallel dispatch. A refused start stops remaining jobs; check the API error, Persona role, workspace default role, and requested model. A start refusal has no attributed realtime spend. An uncertain transport failure or a started run without timing retains a conservative estimate. Spend is an estimate from available duration, not a provider invoice.

gr qualifications runs get -w $WORKSPACE_UUID --id 123 and gr qualifications runs list -w $WORKSPACE_UUID --workflow-id 42 include evaluationStatus and criterionCounts. Batch JSONL includes evaluation_status and a status on each criterion_results item. With --evaluate, evaluation_request distinguishes a requested grade from a retained existing grade. The server decides which stored grades are eligible for recovery; the CLI does not force re-grading. A failed criterion is a failed assertion, not necessarily a model defect. Skipped rubrics have no grade; grading_error and instrument_failure require separate investigation. Retry incomplete grading with gr qualifications runs evaluate -w $WORKSPACE_UUID --id 123 --allow-write.

Compare results only after checking the actual model, revision, and lane. A Scenario's simulated datetime does not change external service clocks. Verify captured routing time separately. Test paging can simulate an action without delivering a page; a simulated receipt is not proof of delivery.