@gravity-rail/cli 0.1.0

package/README.md

@@ -0,0 +1,252 @@
+# @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