npm package: @gravity-rail/cli
Description: Gravity Rail CLI — manage workspaces from the command line
Latest version: 0.2.0

# @gravity-rail/cli

Command-line interface for [Gravity Rail](https://gravityrail.com) — 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":"jane@example.com"}' --allow-write
```

## Installation

```sh
npm install -g @gravity-rail/cli
```

Requires Node.js 18+.

## Authentication

### OAuth (interactive)

```sh
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)

```sh
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`](https://www.npmjs.com/package/@gravity-rail/sdk).

## Command Pattern

```
gr <domain> <action> [options]
gr <domain> <sub-resource> <action> [options]
```

```sh
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`:

```sh
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:

```sh
# 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.

```sh
# 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:

```sh
# 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

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

### Find members by label

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

### Bulk create from a file

```sh
# 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

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

### List all workflows with their task counts

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

### Check who's live as an operator

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

## Related

- [`@gravity-rail/sdk`](https://www.npmjs.com/package/@gravity-rail/sdk) — TypeScript SDK for programmatic access (500+ methods, full type safety)
- [Developer Docs](https://developer.gravityrail.com) — Full API reference and guides

## License

MIT