@gravity-rail/cli

Command-line interface for Gravity Rail — manage workspaces, AI assistants, conversations, workflows, and 40+ resource types 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":"[email protected]"}' --allow-write

Installation

npm install -g @gravity-rail/cli

Requires Node.js 18+.

Authentication

OAuth (interactive)

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

Credentials are cached locally per environment.

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 workspace settings or via @gravity-rail/sdk.

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 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'

# 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

| Flag | Description | |---|---| | --api-url <url> | Override API base URL | | -w, --workspace <uuid> | Workspace UUID (required for most commands) | | -o, --output-format <fmt> | Output format: json, jsonl, table | | -v, --verbose | Verbose output to stderr | | --allow-write | Required 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 | | --help | Show help | | --version | Show version |

Environment Variables

| Variable | Description | |---|---| | GRAVITY_RAIL_API_KEY | API key for non-interactive authentication | | GRAVITY_RAIL_API_URL | Override API base URL (default: https://api.gravityrail.com) | | GRAVITY_RAIL_FRONTEND_URL | Override frontend URL (default: https://app.gravityrail.com) |

Exit Codes

| Code | Meaning | |---|---| | 0 | Success | | 1 | General error | | 2 | Authentication required (run gr login or set GRAVITY_RAIL_API_KEY) | | 3 | A human-in-the-loop (HITL) interrupt requires out-of-band action before the operation can continue |

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

| Domain | Description | |---|---| | tasks | Workflow tasks — CRUD, archive, clone | | chats | Conversations — CRUD, labels, filters, messages, export, summaries | | members | Contacts and team — CRUD, labels, filters, roles, fields, import/export | | workspaces | Workspace management — CRUD, features, themes, invitations, export/import | | workflows | Conversational workflows — CRUD, notes, contributors, templates, analytics | | agents | Autonomous AI members — CRUD, archive | | assistants | AI personas — CRUD with model and voice configuration | | assignments | Task-based conversations — CRUD, messages, tools |

Data & Content

| Domain | Description | |---|---| | data-types | Schema-driven forms and records — CRUD, field indexing, computed fields | | files | Documents and folders — CRUD, sharing, semantic search, labels | | sites | Customer portals — CRUD, pages, menus, web crawling | | events | Automation rules — triggers, CEL conditions, delayed actions, webhooks | | calendars | Scheduling — calendars, events, event types, availability, Google sync | | qualifications | Skills evaluation — requirements, submissions, scoring |

Global (no workspace)

| Domain | Description | |---|---| | concierge | Global Concierge — interactive chat, PSTN --call, SMS --sms | | account verify-phone | Verify your account phone (required before concierge outbound) |

Communication

| Domain | Description | |---|---| | phone-numbers | Voice and SMS phone numbers — provisioning, calls, messages | | inboxes | Email inboxes — threads, attachments, routing | | operator-groups | Live operator routing — groups, presence, strategies | | notification-rules | Alert configuration — event-based notifications |

Integrations

| Domain | Description | |---|---| | discord-bots | Discord bot management — slash commands, threads, account linking | | slack-apps | Slack app management — installations, threads, accounts | | fhir-connections | FHIR healthcare connections — patients, practitioners, encounters | | app-connections | Platform app integrations | | monday | Monday.com — boards, columns, webhooks |

Platform

| Domain | Description | |---|---| | api-keys | API key management — workspace and global scopes | | subscriptions | Subscription management | | reports | Usage reports — AI tokens, voice minutes, SMS, storage | | ai-models | Available AI models (no workspace required) | | features | Feature registry (no workspace required) | | custom-toolkits | Custom tool definitions | | mcp-servers | MCP server connections | | milestones | Goal tracking | | supervisors | AI supervisor management | | access-grants | Temporary access delegation | | pronunciations | Voice pronunciation overrides | | apps | OAuth app management | | oauth | OAuth provider connections | | auth | Two-factor authentication, credentials, and password management | | org | Organization membership, invitations, and org domains |

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 and link a phone number to a workspace

# 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

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: enable custom site routing, then verify CNAME
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

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

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.

Related

• @gravity-rail/sdk — TypeScript SDK for programmatic access (500+ methods, full type safety)
• Developer Docs — Full API reference and guides

License

MIT