> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rogeriq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent guide

How to drive the rogeriq CLI headlessly from CI, scripts, or AI agents.

# 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          # required
export RIQ_PROJECT_ID=prj_xxx       # default project
export 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

| Code | Meaning              |
|------|----------------------|
| 0    | Success              |
| 1    | User / usage error   |
| 2    | API error            |
| 3    | Auth error           |
| 4    | Rate-limited after retry exhausted |

## 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
# Poll
job=$(rogeriq kb crawl list --json | jq -r '.[0].id')
while [ "$(rogeriq kb crawl status "$job" --json | jq -r '.status')" = "running" ]; do
  sleep 10
done
```

## 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](/cli/mcp).

## 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](/api/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.