@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) |

Commands

Core

| Domain | Description | |---|---| | tasks | Workflow tasks — CRUD, archive, clone, convert-to-abilities | | 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 |

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 and invitations |

Recipes

Export all chats as JSON

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

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'

Related

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

License

MIT