@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] [--header "Name: 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

rgk openapi reads the authenticated /api/v1/openapi endpoint first, then falls back to Scramble's /docs/api.json document. rgk routes and rgk describe use the versioned /api/v1/api-operations projection so the server owns reference cycles, annotations, and OpenAPI compatibility. The CLI fails with an upgrade message when the server and CLI projection versions do not match.

Route searches treat spaces, hyphens, underscores, singular/plural words, and CamelCase tags as equivalent. JSON route results use a list envelope with data, hasMore, and total; terminal output warns when --limit truncates the result.

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

1. 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.
2. The CLI prints the URL and code, then polls POST /api/cli/device/token every few seconds.
3. The user visits the URL, signs in if needed, and approves the request from the dash. Approval binds the device code to their account.
4. 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.

Required request headers

Use repeatable --header (or -H) flags for endpoint headers. Landing-page writes require an Idempotency-Key UUID in the header; putting it in the JSON body alone does not satisfy this requirement. Reuse the same key when retrying the same write.

rgk api POST site-pages --header "Idempotency-Key: $request_key" --data - < page.json

Writes to an existing landing page also require its edit lock. Acquire the lock with the edit-lock API, then send the returned token and revision:

rgk api POST site-page-conversations \
  --header "Idempotency-Key: $request_key" \
  --header "X-Edit-Lock-Token: $lock_token" \
  --header "X-Edit-Lock-Revision: $lock_revision" \
  --data - < conversation.json

Read the endpoint and edit-lock schemas with rgk describe before constructing the payload. Do not take over another editor's active lock.