Driving the CLI from agents and CI

The CLI is designed to be safe to invoke from a non-interactive process. No prompts when env vars are set, machine-readable output, structured error codes, and an exit-code contract you can branch on.

Setup

bash
export RIQ_API_KEY=riq_xxx          # requiredexport RIQ_PROJECT_ID=prj_xxx       # default projectexport RIQ_ORG_ID=org_xxx           # for org-level commands

With these set, the CLI never prompts and never opens a browser.

Do NOT call rogeriq auth login (no args) from an agent. That starts the browser device flow and blocks for up to 10 minutes. Use --api-key riq_xxx or set RIQ_API_KEY instead.

Output contract

• Stdout = data, stderr = logs and errors.
• JSON is auto-enabled when stdout isn't a TTY. Agents always see JSON.
• --json forces JSON explicitly. --quiet prints only IDs.

Error JSON shape on stderr:

json
{  "error": "Conversation not found",  "code": "CONVERSATION_NOT_FOUND",  "request_id": "req_abc123",  "status_code": 404}

Branch on code for fine behavior; on exit code for retry decisions.

Exit codes

Rate limits handled for you

The CLI auto-retries 429 once when the server suggests a short backoff (≤30s) — agents don't need to handle the common case. For longer suggested delays (which only happen at extreme abuse), the CLI surfaces exit code 4 so you can wait and re-invoke.

Watch headroom via the X-RateLimit-Remaining header on every response.

Common agent workflows

Triage open tickets

bash
for id in $(rogeriq conversations list --status open --quiet); do  rogeriq agent classify "$id"done

Auto-reply when AI confidence is high

bash
rogeriq agent respond con_xxx# Respects project's agent_mode (autopilot/copilot/assist).# In autopilot mode the message is sent. In copilot, it's drafted as# internal note for human review.

KB ingest pipeline

bash
rogeriq kb crawl https://docs.example.com# Polljob=$(rogeriq kb crawl list --json | jq -r '.[0].id')while [ "$(rogeriq kb crawl status "$job" --json | jq -r '.status')" = "running" ]; do  sleep 10done

MCP server (recommended for LLMs)

For Claude Desktop / Claude Code, prefer MCP over shelling out. The LLM gets typed tools with descriptions instead of having to remember shell syntax. See MCP server.

Filesystem footprint

When RIQ_API_KEY is set the CLI does not read or write ~/.rogeriq/config.json for the key, but it does write orgId / projectId defaults when you run orgs use / projects use. In CI you typically don't run those — instead use RIQ_ORG_ID / RIQ_PROJECT_ID env vars or --project per command.

Security notes

• Destructive commands do NOT prompt. rogeriq projects delete, kb delete, keys revoke execute immediately. Build confirmation into your agent harness if needed.
• Use granular scopes to constrain what a key can do. An agent that only drafts KB articles needs kb:write,conversations:read, not admin.
• All actions are recorded in the audit log with the API key's id and name. Dashboard reviewers can see which key did what.