Skip to main content

CLI Getting Started

The gr CLI manages workspaces, Workflows, Agents, Chats, Members, and 40+ other resource types from your terminal. It is built for humans and for coding agents: output is machine-readable when piped, writes require an explicit opt-in flag, and gr get-started --format llm prints agent-readable bootstrap instructions you can paste straight into an LLM context.

Install​

npm install -g @gravity-rail/cli

Requires Node.js 18+. The package is @gravity-rail/cli on npm.

Authenticate​

Interactive (opens a browser for OAuth):

gr login
gr whoami      # verify your identity

Non-interactive, for scripts and CI — create a scoped API key in workspace settings, then:

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

GRAVITY_RAIL_API_KEY always takes precedence and is never written to disk. Multiple accounts work like aws --profile:

gr auth login --name work        # OAuth into a named profile
gr auth switch --name work       # change the default profile
gr whoami --profile work         # per-invocation selection

Credentials are stored in ~/.gr-cli/ with 0600 file modes and never leave your machine except on HTTPS calls to the API.

The command pattern​

Every command follows gr <domain> <action>, with -w selecting the workspace:

gr workspaces list                          # workspaces available to you
gr workflows list -w $WORKSPACE_ID          # list Workflows
gr workflows get -w $WORKSPACE_ID --id 42   # one Workflow
gr chats list -w $WORKSPACE_ID -o json      # JSON output
gr chats labels list -w $WORKSPACE_ID       # sub-resources nest one level

Run gr --help for all domains, or gr <domain> --help for one.

Reads are free, writes are explicit​

The CLI is read-only by default. Anything that creates, updates, or deletes requires --allow-write:

gr members create -w $WORKSPACE_ID \
  --data '{"first_name":"Jane","last_name":"Rivera","email":"jane.rivera@example.com"}' \
  --allow-write

This makes the CLI safe to hand to an automation or coding agent: exploration can't mutate anything by accident.

Output formats​

Output adapts to context — human tables in a terminal, JSON when piped:

gr tasks list -w $WORKSPACE_ID              # table in a TTY
gr tasks list -w $WORKSPACE_ID -o json      # explicit JSON
gr chats list -w $WORKSPACE_ID -o json | jq '.[].summary'

Built for agents​

Two commands exist specifically for LLM-driven use:

gr get-started --format llm     # agent-readable bootstrap steps
gr concierge chat --allow-write # chat with the workspace Concierge from the terminal

Point your coding agent at gr get-started --format llm and it can discover the rest of the surface itself via --help.

Next steps​