@romegadigital/cli

@romegadigital/cli

Headless CLI for the RGK platform. Designed so a human or an AI agent can exercise any API endpoint without leaving the terminal.

Quick start

# Always-latest invocation. Recommended for non-technical users.
npx -y @romegadigital/cli@latest login

# Or install once and let the CLI nag about updates.
npm install -g @romegadigital/cli
rgk login

rgk login walks an OAuth 2.0 Device Authorization Grant (RFC 8628): it prints a short code, asks you to visit https://dash.rgk.app/settings/cli, and waits until you approve the request in the browser. The token is stored locally with 0600 permissions under $XDG_CONFIG_HOME/rgk/credentials.json (or the OS-appropriate equivalent).

Commands

Command	Purpose
rgk login	Authenticate with an RGK server via device flow.
rgk logout	Forget local credentials and revoke the server-side token.
rgk whoami	Show the user and token tied to the current credentials.
rgk openapi	Print the OpenAPI document used for route discovery.
rgk routes [query]	List/search available API operations.
rgk describe <method> <path>	Show parameters, request body, response schemas, and CLI usage for an operation.
rgk api <method> <path> [--data <json>] [--form key=value]	Send an authenticated request against any endpoint. --form repeats for multipart uploads; prefix the value with @ to attach a file (--form file=@/path/to/contract.pdf).

All commands accept --json to emit machine-readable output to stdout (and default to JSON when stdout is not a TTY). Errors exit with a non-zero status and a JSON body on stderr when --json is active.

Agent discovery workflow

AI agents should discover the API before calling it:

# Dump the full OpenAPI document.
rgk openapi --json

# Search routes by keyword, method, or tag.
rgk routes organizations --json
rgk routes --method POST --tag Billing --json

# Inspect the expected payload and response shape.
rgk describe POST /v1/organizations --json

# Call the endpoint with the described shape.
rgk api POST /api/v1/organizations --data '{"name":"Example Co"}' --json

The CLI reads the authenticated /api/v1/openapi endpoint first, then falls back to Scramble's local /docs/api.json document when the authenticated route is unavailable.

Examples

# Human-readable identity check.
rgk whoami

# List the first page of organizations as JSON for an agent.
rgk api GET organizations --json

# Pipe a payload from stdin.
cat new-org.json | rgk api POST organizations --data -

# Upload a file via multipart/form-data. Repeat --form per field; prefix the
# value with @ to attach a file from disk.
rgk api POST /api/v1/customer-services/svc_abc/contracts \
  --form file=@./contract.pdf \
  --form 'name=3D Digital hosting contract' \
  --form 'notes=Imported from acquisition archive.'

Environment

Variable	Effect
RGK_SERVER	Default server URL (overridden per-command by --server).
RGK_TOKEN	Skip the credentials file entirely — useful in CI.
XDG_CONFIG_HOME	Honoured for credential storage on Linux/macOS.

How the device flow works

• rgk login calls POST /api/cli/device/code and receives a device_code (secret), a user_code (8 characters, shown to the user), and a poll interval.
• The CLI prints the URL and code, then polls POST /api/cli/device/token every few seconds.
• The user visits the URL, signs in if needed, and approves the request from the dash. Approval binds the device code to their account.
• The next poll returns a Sanctum bearer token, which the CLI stores locally.

The CLI never sees the user's password and the dash never sees the CLI's machine — the device_code is the only thing linking the two sessions.

Building and testing locally

npm install
npm run build --workspace @romegadigital/cli
./packages/rgk-cli/dist/main.js --help

# Run against a local dash instance.
RGK_SERVER=http://localhost ./packages/rgk-cli/dist/main.js login

OpenAPI codegen

The first iteration of this CLI is hand-written. The intent is to grow the rgk api <tag> <operation> command tree directly from Scramble's OpenAPI document. To regenerate types:

RGK_OPENAPI=https://dash.rgk.app/docs/api.json npm run generate --workspace @romegadigital/cli

The full command-tree codegen step is not wired up yet. Until it lands, the rgk routes, rgk describe, and rgk api <method> <path> commands are the surface every endpoint is reachable through.

Roadmap

• Generate rgk api <tag> <operation> subcommands from the OpenAPI document.
• Curated workflows for the most-used domains (rgk organizations create, rgk projects log-time, etc.) with @inquirer/prompts.
• update-notifier banner so users on stale installs find out.
• One-line installer that drops an rgk shim invoking npx -y @romegadigital/cli@latest.
• keytar-backed credential storage as an opt-in upgrade over the permissions-restricted file store.