@rogeriq/cli 0.1.0

package/AGENTS.md

@@ -0,0 +1,166 @@
+# Using `rogeriq` from AI agents
+
+This document describes how to drive the RogerIQ CLI from an AI agent
+(Claude, GPT, Codex, internal tooling). The CLI is built for headless use:
+no interactive prompts when env vars are set, machine-readable output,
+structured error codes, and an MCP transport for direct LLM tool calls.
+
+## Setup
+
+```bash
+export RIQ_API_KEY=riq_xxx       # required
+export RIQ_PROJECT_ID=prj_xxx    # default project (per-command --project overrides)
+export RIQ_ORG_ID=org_xxx        # for org-level commands (orgs, projects, keys)
+```
+
+The CLI never prompts when these are set. No interactive `--browser` flow.
+
+## Output contract
+
+- Stdout = data. Stderr = logs and errors.
+- JSON output is auto-enabled when stdout is not a TTY (most subprocess
+  invocations), so agents always get JSON by default. Pass `--json` to
+  force it explicitly.
+- Errors print to stderr as JSON when in JSON mode:
+
+  ```json
+  { "error": "Conversation not found",
+    "code": "RESOURCE_NOT_FOUND",
+    "request_id": "req_abc123",
+    "status_code": 404 }
+  ```
+
+- Exit codes:
+
+  | Code | Meaning              |
+  |------|----------------------|
+  | 0    | Success              |
+  | 1    | User / usage error   |
+  | 2    | API error            |
+  | 3    | Auth error           |
+  | 4    | Rate-limited (after retry exhausted) |
+
+  Branch on `code` for fine-grained behavior; on exit code for
+  retry/abort decisions.
+
+- Rate limits: the API returns `X-RateLimit-Remaining` headers and on 429
+  the CLI auto-retries once after the server-suggested delay. Agents
+  don't need to handle 429 manually for short waits.
+
+## Two ways to use it
+
+### 1) Shell out to `rogeriq`
+
+Best for any agent harness that can invoke commands and read stdout:
+
+```bash
+# List open tickets, then pick high-priority ones
+rogeriq conversations list --status open --priority high --json \
+  | jq '.[] | { id, subject, contact_id }'
+
+# Reply on a conversation
+rogeriq conversations reply con_xxx "On it — checking now."
+
+# Trigger AI to draft + send a response
+rogeriq agent respond con_xxx
+```
+
+### 2) MCP (recommended for Claude)
+
+Run `rogeriq mcp` as an MCP server (stdio). Tools are exposed natively
+and the LLM doesn't have to know shell syntax.
+
+**Claude Desktop / Claude Code config:**
+
+```json
+{
+  "mcpServers": {
+    "rogeriq": {
+      "command": "rogeriq",
+      "args": ["mcp"],
+      "env": {
+        "RIQ_API_KEY": "riq_xxx",
+        "RIQ_PROJECT_ID": "prj_xxx",
+        "RIQ_ORG_ID": "org_xxx"
+      }
+    }
+  }
+}
+```
+
+Then the model can call tools like `list_conversations`,
+`reply_to_conversation`, `update_conversation`, `search_knowledge_base`,
+`agent_respond`, `update_widget_config`, etc.
+
+Run `rogeriq mcp list-tools` for the full schema.
+
+## Common workflows
+
+### Triage queue
+
+```bash
+# Get oldest open tickets
+rogeriq conversations list --status open --json \
+  | jq -r '.[] | .id'
+
+# For each, classify + tag
+for id in $(rogeriq conversations list --status open --quiet); do
+  rogeriq agent classify "$id"
+done
+```
+
+### Auto-respond high-confidence tickets
+
+```bash
+for id in $(rogeriq conversations list --status open --quiet); do
+  rogeriq agent respond "$id"   # respects agent_mode (autopilot/copilot)
+done
+```
+
+### Ingest a docs site into KB
+
+```bash
+rogeriq kb crawl https://docs.example.com
+# Poll status
+rogeriq kb crawl status crawl_xxx
+```
+
+### Wire a webhook to your own system
+
+```bash
+rogeriq webhooks create \
+  --url https://yourapp.com/rogeriq-hook \
+  --events 'conversation.*,message.created'
+rogeriq webhooks test wh_xxx     # immediate sample event
+rogeriq webhooks deliveries wh_xxx
+```
+
+## Project switching
+
+Many agents work across multiple projects. Either:
+
+- Set `RIQ_PROJECT_ID` per shell command:
+  ```bash
+  RIQ_PROJECT_ID=prj_a rogeriq conversations list
+  RIQ_PROJECT_ID=prj_b rogeriq conversations list
+  ```
+- Or pass `--project prj_xxx`:
+  ```bash
+  rogeriq conversations list --project prj_a
+  ```
+
+## Safety
+
+- Destructive commands (`projects delete`, `keys revoke`, `kb delete`)
+  do **not** prompt. Build confirmation into your agent if needed.
+- API keys are scoped (`read` / `write` / `admin`). Give agents a
+  least-privilege key.
+- All actions are audited server-side (audit log) with the API key id.
+
+## Discoverability
+
+- `rogeriq --help` lists commands.
+- `rogeriq <group>` lists subcommands.
+- `rogeriq <group> <cmd> --help` shows flags + examples.
+- OpenAPI spec: `GET /api/v1/openapi.json` (use for codegen, agent
+  function-call schemas, etc).

package/README.md

@@ -0,0 +1,136 @@
+# `@rogeriq/cli`
+
+Command-line interface for [RogerIQ](https://rogeriq.com). Manage tickets,
+projects, knowledge base, widget, integrations, and webhooks from your
+terminal or AI agent.
+
+## Install
+
+```bash
+npm install -g @rogeriq/cli
+# or via npx:
+npx @rogeriq/cli --help
+```
+
+## Auth
+
+Create an API key in the dashboard or via the CLI (after one-time browser
+login from `app.rogeriq.com`):
+
+```bash
+rogeriq auth login --api-key riq_xxx
+```
+
+For CI / agents, prefer env vars (no config file needed):
+
+```bash
+export RIQ_API_KEY=riq_xxx
+export RIQ_PROJECT_ID=prj_xxx   # default project for commands
+```
+
+## Quick start
+
+```bash
+rogeriq auth whoami
+rogeriq projects list
+rogeriq projects use prj_xxx
+rogeriq conversations list --status open
+rogeriq conversations reply con_xxx "Thanks, looking into it now."
+rogeriq conversations resolve con_xxx
+
+rogeriq kb search "refund policy"
+rogeriq agent respond con_xxx        # let AI draft + send reply
+
+rogeriq widget config
+rogeriq widget set --theme dark --primary-color '#5b21b6'
+
+rogeriq webhooks create \
+  --url https://example.com/hook \
+  --events 'conversation.*,message.created'
+rogeriq webhooks test wh_xxx         # fire sample event
+```
+
+## Output
+
+- Default: human-readable tables.
+- Auto-JSON when stdout is piped (clean for agents and `jq`).
+- `--json` forces JSON. `--quiet` prints only IDs.
+- Stderr for logs/errors. Stdout is always data.
+
+```bash
+# Pipe to jq
+rogeriq conversations list --status open | jq '.[].id'
+
+# Use IDs in a shell loop
+for id in $(rogeriq conversations list --status open --quiet); do
+  rogeriq conversations resolve "$id"
+done
+```
+
+## Commands
+
+```
+auth          login | logout | whoami
+config        get | set | path
+orgs          list | get | create | use | members
+projects      list | get | create | update | delete | use
+keys          list | create | revoke
+
+conversations list | get | create | update | reply | resolve | snooze | assign
+messages      list | send
+contacts      list | get | upsert | update
+
+agent         status | config | models | respond | classify | suggest | knowledge-map
+kb            list | get | create | update | delete | publish | search | ingest | crawl | categories
+
+widget        config | set | snippet | custom-fields
+integrations  list | get | connect | configure | disconnect
+forms         list | get | create | update | archive | submissions
+beacons       list | get | create | update | archive
+
+webhooks      list | get | create | update | delete | test | deliveries | rotate-secret
+analytics     overview | report-views
+status        (project status overview)
+
+mcp           Run as an MCP server (stdio) — for Claude Desktop / Claude Code
+mcp list-tools
+```
+
+Run `rogeriq <group>` to see all subcommands, or `rogeriq <group> <sub> --help`
+for command-specific flags.
+
+## Config
+
+`~/.rogeriq/config.json` (mode 0600). Overridden by env vars:
+
+| Key         | Env var          |
+|-------------|------------------|
+| apiKey      | `RIQ_API_KEY`    |
+| apiBase     | `RIQ_API_BASE`   |
+| orgId       | `RIQ_ORG_ID`     |
+| projectId   | `RIQ_PROJECT_ID` |
+
+## Exit codes
+
+| Code | Meaning              |
+|------|----------------------|
+| 0    | Success              |
+| 1    | User error / usage   |
+| 2    | API error            |
+| 3    | Auth error           |
+| 4    | Rate-limited (after retry exhausted) |
+
+## AI agents
+
+See `AGENTS.md`. TL;DR: pass `RIQ_API_KEY` and `RIQ_PROJECT_ID` as env, use
+`--json`, branch on `code` from stderr error JSON, or run `rogeriq mcp`
+and let Claude call tools directly over MCP.
+
+## Develop
+
+```bash
+npm install
+npm run build          # bundle to dist/index.mjs
+npm run typecheck
+./dist/index.mjs --help
+```