@rogeriq/cli 0.1.0 → 0.3.0

package/AGENTS.md

@@ -13,7 +13,13 @@ export RIQ_PROJECT_ID=prj_xxx    # default project (per-command --project overri
 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.
+The CLI never prompts when these are set. `rogeriq auth login --api-key`
+also works for one-time setup without a browser.
+
+**Do not** invoke `rogeriq auth login` without `--api-key` from an agent —
+the no-args form starts the browser-based device flow and will block for
+up to 10 minutes waiting for a human to confirm. Use `--api-key` or env
+vars instead.
 
 ## Output contract
 

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+## 0.3.0 — 2026-05-17
+
+### Added
+- KB articles + agent + integrations + forms + beacons now use the stable
+  `/api/v1/...` surface (joins projects + widget + conversations + contacts
+  + webhooks already on v1). Internal routes remain as the unstable mirror.
+- MCP server tools: `browse_integration_catalog`, `get_integration_install_url`,
+  `disconnect_integration`. Existing tools repointed to v1.
+- **Granular scopes** on API keys. In addition to coarse `read`/`write`/`admin`,
+  you can now scope keys per-resource: `kb:write`, `agent:read`,
+  `integrations:write`, `projects:admin`, etc. See README for the full table.
+- Audit log now captures `api_key_id` on mutations. `GET /api/projects/:pid/audit-log`
+  joins on `api_keys` and returns `api_key_name` + `api_key_prefix` so the
+  dashboard can show which key changed what.
+
+## 0.2.0 — 2026-05-17
+
+### Added
+- **Browser-based device authorization flow.** `rogeriq auth login` (no args)
+  now opens `rogeriq.com/device?code=XXXX-XXXX`, polls for confirmation, and
+  saves the API key automatically. Code is also printed to the terminal as a
+  fallback for SSH / headless environments. Pass `--no-browser` to suppress
+  the auto-open. `--api-key riq_xxx` still works for CI / scripting.
+- KB articles + search now use the stable `/api/v1/...` surface.
+- Agent status, config, respond, classify, suggest now use `/api/v1/...`.
+- MCP server (`rogeriq mcp`) tools updated to point at v1 endpoints.
+- Unit tests for argv parser, API client (incl. 429 auto-retry), and device
+  auth flow (happy path, denied, expired, slow-down backoff).
+
+### Fixed
+- `--help` after a subcommand now correctly prints per-command help instead
+  of root help.
+- `--json` / `--quiet` set at the top level now propagate into subcommand
+  flag parsing.
+- API client now treats `retry_after: 0` as a valid retry hint (previously
+  the 0 was discarded as falsy and the request did not retry).
+
+## 0.1.0 — 2026-05-17
+
+Initial release. 18 command groups covering conversations, contacts,
+projects, knowledge base, widget, integrations, webhooks, agent, plus an
+MCP server subcommand for Claude Desktop / Claude Code.

package/README.md

@@ -14,18 +14,35 @@ 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`):
+### Interactive (humans)
+
+```bash
+rogeriq auth login
+```
+
+Opens a browser to `rogeriq.com/device?code=XXXX-XXXX`. Confirm in the
+browser. The CLI picks up the key automatically. Code is also printed to
+the terminal as a fallback (SSH / no browser).
+
+Flags:
+- `--no-browser` — skip auto-open; print URL + code only.
+- `--api-base https://...` — point at a different deployment.
+
+### CI / agents / scripts
+
+Use `--api-key` (or env var) to skip the browser flow entirely:
 
 ```bash
 rogeriq auth login --api-key riq_xxx
+# Or pass per-invocation:
+RIQ_API_KEY=riq_xxx rogeriq conversations list
 ```
 
-For CI / agents, prefer env vars (no config file needed):
+Recommended for CI / agents (no config file needed):
 
 ```bash
 export RIQ_API_KEY=riq_xxx
-export RIQ_PROJECT_ID=prj_xxx   # default project for commands
+export RIQ_PROJECT_ID=prj_xxx
 ```
 
 ## Quick start
@@ -110,6 +127,30 @@ for command-specific flags.
 | orgId       | `RIQ_ORG_ID`     |
 | projectId   | `RIQ_PROJECT_ID` |
 
+## Scopes
+
+API keys can be coarse or granular:
+
+| Scope                 | Grants                                                         |
+|-----------------------|----------------------------------------------------------------|
+| `admin`               | Everything.                                                    |
+| `write`               | All `*:read` and `*:write`. Not `*:admin`.                     |
+| `read`                | All `*:read`.                                                  |
+| `<resource>:admin`    | `<resource>:read`, `:write`, `:admin`.                         |
+| `<resource>:write`    | `<resource>:read`, `:write`.                                   |
+| `<resource>:read`     | `<resource>:read` only.                                        |
+
+Resources: `conversations`, `messages`, `contacts`, `kb`, `agent`, `widget`,
+`integrations`, `forms`, `beacons`, `webhooks`, `projects`, `analytics`,
+`audit`.
+
+Examples — least privilege for an agent that only drafts KB articles + reads
+conversations:
+
+```bash
+rogeriq keys create kb-writer --scopes kb:write,conversations:read
+```
+
 ## Exit codes
 
 | Code | Meaning              |

package/dist/index.mjs

@@ -275,7 +275,7 @@ var ApiClient = class {
     const url = path.startsWith("http") ? path : `${this.apiBase}${path}`;
     const headers = {
       "X-API-Key": this.apiKey,
-      "User-Agent": `rogeriq-cli/0.1.0 node/${process.versions.node}`,
+      "User-Agent": `rogeriq-cli/0.3.0 node/${process.versions.node}`,
       "Accept": "application/json",
       ...init.headers
     };
@@ -318,7 +318,7 @@ var ApiClient = class {
       const code = err?.code ?? `HTTP_${res.status}`;
       const message = err?.error ?? `Request failed: ${res.status} ${res.statusText}`;
       const exitCode = res.status === 401 || res.status === 403 ? 3 : res.status === 429 ? 4 : 2;
-      if (res.status === 429 && err?.retry_after && err.retry_after <= 30) {
+      if (res.status === 429 && typeof err?.retry_after === "number" && err.retry_after >= 0 && err.retry_after <= 30) {
         await sleep(err.retry_after * 1e3);
         return this.request(method, path, body, init);
       }
@@ -371,39 +371,148 @@ function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
 
+// src/lib/device-auth.ts
+import { spawn } from "node:child_process";
+import { hostname, userInfo } from "node:os";
+async function runDeviceFlow(opts) {
+  const base = opts.apiBase.replace(/\/$/, "");
+  const clientName = opts.clientName ?? defaultClientName();
+  const codeRes = await fetch(`${base}/api/auth/device/code`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ client_name: clientName })
+  });
+  if (!codeRes.ok) {
+    throw new CliError(
+      `Failed to start device flow: ${codeRes.status} ${codeRes.statusText}`,
+      "DEVICE_CODE_FAILED",
+      2
+    );
+  }
+  const codeBody = await codeRes.json();
+  opts.onPrompt?.({
+    userCode: codeBody.user_code,
+    verificationUri: codeBody.verification_uri,
+    verificationUriComplete: codeBody.verification_uri_complete
+  });
+  if (!opts.noBrowser) {
+    openBrowser(codeBody.verification_uri_complete);
+  }
+  const intervalMs = Math.max(1, opts.pollInterval ?? codeBody.interval) * 1e3;
+  const deadline = Date.now() + (opts.timeoutSeconds ?? 600) * 1e3;
+  let interval = intervalMs;
+  let attempt = 0;
+  while (Date.now() < deadline) {
+    attempt += 1;
+    opts.onPoll?.(attempt);
+    await sleep2(interval);
+    const res = await fetch(`${base}/api/auth/device/token`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ device_code: codeBody.device_code })
+    });
+    if (res.status === 202) {
+      const pending = await safeJson(res);
+      if (pending?.interval) interval = Math.max(1, pending.interval) * 1e3;
+      continue;
+    }
+    if (res.status === 429) {
+      const body = await safeJson(res);
+      if (body?.interval) interval = Math.max(1, body.interval) * 1e3;
+      else interval = Math.min(6e4, interval * 2);
+      continue;
+    }
+    if (res.status === 410) {
+      throw new CliError(
+        "Device code expired. Run `rogeriq auth login` again.",
+        "DEVICE_CODE_EXPIRED",
+        3
+      );
+    }
+    if (res.status === 403) {
+      throw new CliError(
+        "Authorization denied.",
+        "ACCESS_DENIED",
+        3
+      );
+    }
+    if (!res.ok) {
+      const body = await safeJson(res);
+      throw new CliError(
+        body?.error ?? `Device flow failed: ${res.status} ${res.statusText}`,
+        body?.code ?? `HTTP_${res.status}`,
+        2
+      );
+    }
+    const token = await res.json();
+    const apiKey = token.access_token ?? token.api_key;
+    if (!apiKey) {
+      throw new CliError("Server returned no API key", "MISSING_API_KEY", 2);
+    }
+    return { apiKey, orgId: token.org_id, scopes: token.scopes };
+  }
+  throw new CliError(
+    "Timed out waiting for browser authorization (10 minutes).",
+    "DEVICE_FLOW_TIMEOUT",
+    3
+  );
+}
+function defaultClientName() {
+  try {
+    return `rogeriq-cli (${userInfo().username}@${hostname()})`.slice(0, 100);
+  } catch {
+    return "rogeriq-cli";
+  }
+}
+function openBrowser(url) {
+  const platform = process.platform;
+  const cmd = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
+  const args = platform === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {
+    });
+    child.unref();
+  } catch {
+  }
+}
+function sleep2(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+async function safeJson(res) {
+  try {
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+
 // src/commands/auth.ts
+var DEFAULT_API_BASE2 = "https://api.rogeriq.com";
 var auth = {
   summary: "Manage CLI authentication",
   subcommands: {
     login: {
-      summary: "Save an API key for future commands",
-      usage: "rogeriq auth login --api-key riq_xxx [--api-base https://api.rogeriq.com]",
+      summary: "Browser-based login (or pass --api-key for CI / scripting)",
+      usage: "rogeriq auth login [--api-key riq_xxx] [--no-browser] [--api-base https://api.rogeriq.com]",
       flags: [
         { name: "api-key", type: "string" },
-        { name: "api-base", type: "string" }
+        { name: "api-base", type: "string" },
+        { name: "no-browser", type: "boolean" },
+        { name: "client-name", type: "string" }
       ],
       async run({ flags }) {
+        const apiBase = flags["api-base"] ?? loadConfig().apiBase ?? DEFAULT_API_BASE2;
         const apiKey = flags["api-key"];
-        const apiBase = flags["api-base"];
-        if (!apiKey) {
-          throw new CliError(
-            "Pass --api-key riq_xxx. Generate one with `rogeriq keys create <name>` (after a one-time browser login) or in the dashboard.",
-            "MISSING_API_KEY",
-            1
-          );
-        }
-        if (!apiKey.startsWith("riq_")) {
-          throw new CliError("API key must start with riq_", "INVALID_API_KEY", 1);
+        if (apiKey) {
+          await loginWithApiKey({ apiKey, apiBase });
+          return;
         }
-        const updates = { apiKey };
-        if (apiBase) updates["apiBase"] = apiBase;
-        saveConfig(updates);
-        const client = new ApiClient();
-        const me = await client.get("/api/orgs");
-        const list = me.raw?.data ?? [];
-        if (list[0]?.id) saveConfig({ orgId: list[0].id });
-        logInfo(`Saved API key to ${configPath()}.`);
-        emit({ ok: true, org_id: list[0]?.id ?? null });
+        await loginWithBrowser({
+          apiBase,
+          noBrowser: flags["no-browser"] === true,
+          clientName: flags["client-name"]
+        });
       }
     },
     logout: {
@@ -419,7 +528,11 @@ var auth = {
       async run() {
         const cfg = loadConfig();
         if (!cfg.apiKey) {
-          throw new CliError("Not logged in. Run `rogeriq auth login --api-key riq_xxx`.", "NOT_LOGGED_IN", 3);
+          throw new CliError(
+            "Not logged in. Run `rogeriq auth login`.",
+            "NOT_LOGGED_IN",
+            3
+          );
         }
         const client = new ApiClient();
         const orgsRes = await client.get("/api/orgs");
@@ -435,6 +548,64 @@ var auth = {
     }
   }
 };
+async function loginWithApiKey({ apiKey, apiBase }) {
+  if (!apiKey.startsWith("riq_")) {
+    throw new CliError("API key must start with riq_", "INVALID_API_KEY", 1);
+  }
+  saveConfig({ apiKey, apiBase });
+  const client = new ApiClient();
+  const me = await client.get("/api/orgs");
+  const list = me.raw?.data ?? [];
+  if (list[0]?.id) saveConfig({ orgId: list[0].id });
+  logInfo(`Saved API key to ${configPath()}.`);
+  emit({ ok: true, org_id: list[0]?.id ?? null });
+}
+async function loginWithBrowser(opts) {
+  const result = await runDeviceFlow({
+    apiBase: opts.apiBase,
+    noBrowser: opts.noBrowser,
+    clientName: opts.clientName,
+    onPrompt: ({ userCode, verificationUri, verificationUriComplete }) => {
+      const sep = "\u2500".repeat(40);
+      process.stderr.write(`
+${sep}
+`);
+      process.stderr.write(`  Open this URL in your browser:
+`);
+      process.stderr.write(`    ${verificationUriComplete}
+
+`);
+      process.stderr.write(`  Or visit ${verificationUri}
+`);
+      process.stderr.write(`  and enter code:  ${userCode}
+`);
+      process.stderr.write(`${sep}
+
+`);
+      if (opts.noBrowser) {
+        process.stderr.write("  (Skipping browser open: --no-browser)\n\n");
+      } else {
+        process.stderr.write("  Opening browser\u2026\n\n");
+      }
+    },
+    onPoll: (attempt) => {
+      if (attempt === 1) process.stderr.write("Waiting for authorization\u2026\n");
+    }
+  });
+  saveConfig({
+    apiKey: result.apiKey,
+    apiBase: opts.apiBase,
+    orgId: result.orgId
+  });
+  logInfo(`
+Authorized. Saved API key to ${configPath()}.`);
+  emit({
+    ok: true,
+    org_id: result.orgId ?? null,
+    scopes: result.scopes ?? null,
+    api_key_prefix: result.apiKey.slice(0, 12) + "..."
+  });
+}
 
 // src/commands/config.ts
 var KEYS = ["apiKey", "apiBase", "orgId", "projectId"];
@@ -651,7 +822,7 @@ var keys = {
     },
     create: {
       summary: "Create an API key. Raw key returned ONCE \u2014 copy it now.",
-      usage: "rogeriq keys create <name> [--scopes read,write,admin] [--expires-days 90]",
+      usage: "rogeriq keys create <name> [--scopes read,write,admin | --scopes kb:write,agent:read,...] [--expires-days 90]",
       flags: [
         { name: "org", type: "string" },
         { name: "scopes", type: "string" },
@@ -1022,7 +1193,7 @@ var agent = {
       async run({ flags }) {
         const client = new ApiClient({ projectId: flags["project"] });
         const pid = client.requireProject();
-        const res = await client.get(`/api/projects/${pid}/agent/status`);
+        const res = await client.get(`/api/v1/projects/${pid}/agent/status`);
         emit(res.raw?.data ?? res.raw);
       }
     },
@@ -1044,11 +1215,11 @@ var agent = {
         if (flags["persona"]) body["persona"] = flags["persona"];
         if (flags["tone"]) body["tone"] = flags["tone"];
         if (Object.keys(body).length === 0) {
-          const res2 = await client.get(`/api/projects/${pid}/agent/config`);
+          const res2 = await client.get(`/api/v1/projects/${pid}/agent/config`);
           emit(res2.raw?.data ?? res2.raw);
           return;
         }
-        const res = await client.patch(`/api/projects/${pid}/agent/config`, body);
+        const res = await client.patch(`/api/v1/projects/${pid}/agent/config`, body);
         emit(res.raw?.data ?? res.raw);
       }
     },
@@ -1068,7 +1239,7 @@ var agent = {
         if (!conv) throw new CliError("Usage: rogeriq agent respond <conversation-id>", "BAD_USAGE", 1);
         const client = new ApiClient({ projectId: flags["project"] });
         const pid = client.requireProject();
-        const res = await client.post(`/api/projects/${pid}/agent/respond`, {
+        const res = await client.post(`/api/v1/projects/${pid}/agent/respond`, {
           conversation_id: conv
         });
         emit(res.raw?.data ?? res.raw);
@@ -1082,7 +1253,7 @@ var agent = {
         if (!conv) throw new CliError("Usage: rogeriq agent classify <conversation-id>", "BAD_USAGE", 1);
         const client = new ApiClient({ projectId: flags["project"] });
         const pid = client.requireProject();
-        const res = await client.post(`/api/projects/${pid}/agent/classify`, {
+        const res = await client.post(`/api/v1/projects/${pid}/agent/classify`, {
           conversation_id: conv
         });
         emit(res.raw?.data ?? res.raw);
@@ -1096,7 +1267,7 @@ var agent = {
         if (!conv) throw new CliError("Usage: rogeriq agent suggest <conversation-id>", "BAD_USAGE", 1);
         const client = new ApiClient({ projectId: flags["project"] });
         const pid = client.requireProject();
-        const res = await client.post(`/api/projects/${pid}/agent/suggest`, {
+        const res = await client.post(`/api/v1/projects/${pid}/agent/suggest`, {
           conversation_id: conv
         });
         emit(res.raw?.data ?? res.raw);
@@ -1129,7 +1300,7 @@ var kb = {
         if (flags["limit"]) qs.set("limit", flags["limit"]);
         if (flags["cursor"]) qs.set("cursor", flags["cursor"]);
         const suffix = qs.toString() ? `?${qs}` : "";
-        const res = await client.get(`/api/projects/${pid}/kb/articles${suffix}`);
+        const res = await client.get(`/api/v1/projects/${pid}/kb/articles${suffix}`);
         emit(res.raw?.data ?? res.raw);
       }
     },
@@ -1141,7 +1312,7 @@ var kb = {
         if (!id) throw new CliError("Usage: rogeriq kb get <article-id>", "BAD_USAGE", 1);
         const client = new ApiClient({ projectId: flags["project"] });
         const pid = client.requireProject();
-        const res = await client.get(`/api/projects/${pid}/kb/articles/${id}`);
+        const res = await client.get(`/api/v1/projects/${pid}/kb/articles/${id}`);
         emit(res.raw?.data ?? res.raw);
       }
     },
@@ -1166,7 +1337,7 @@ var kb = {
         const body = { title, content };
         if (flags["category-id"]) body["category_id"] = flags["category-id"];
         if (flags["status"]) body["status"] = flags["status"];
-        const res = await client.post(`/api/projects/${pid}/kb/articles`, body);
+        const res = await client.post(`/api/v1/projects/${pid}/kb/articles`, body);
         emit(res.raw?.data ?? res.raw);
       }
     },
@@ -1190,7 +1361,7 @@ var kb = {
         else if (flags["content"]) body["content"] = flags["content"];
         if (flags["status"]) body["status"] = flags["status"];
         if (Object.keys(body).length === 0) throw new CliError("No updates provided", "NO_UPDATES", 1);
-        const res = await client.patch(`/api/projects/${pid}/kb/articles/${id}`, body);
+        const res = await client.patch(`/api/v1/projects/${pid}/kb/articles/${id}`, body);
         emit(res.raw?.data ?? res.raw);
       }
     },
@@ -1202,7 +1373,7 @@ var kb = {
         if (!id) throw new CliError("Usage: rogeriq kb delete <id>", "BAD_USAGE", 1);
         const client = new ApiClient({ projectId: flags["project"] });
         const pid = client.requireProject();
-        await client.del(`/api/projects/${pid}/kb/articles/${id}`);
+        await client.del(`/api/v1/projects/${pid}/kb/articles/${id}`);
         emit({ ok: true, deleted: id });
       }
     },
@@ -1214,7 +1385,7 @@ var kb = {
         if (!id) throw new CliError("Usage: rogeriq kb publish <id>", "BAD_USAGE", 1);
         const client = new ApiClient({ projectId: flags["project"] });
         const pid = client.requireProject();
-        const res = await client.post(`/api/projects/${pid}/kb/articles/${id}/publish`);
+        const res = await client.post(`/api/v1/projects/${pid}/kb/articles/${id}/publish`);
         emit(res.raw?.data ?? res.raw);
       }
     },
@@ -1226,7 +1397,7 @@ var kb = {
         if (!q) throw new CliError("Usage: rogeriq kb search <query>", "BAD_USAGE", 1);
         const client = new ApiClient({ projectId: flags["project"] });
         const pid = client.requireProject();
-        const res = await client.get(`/api/projects/${pid}/kb/search?q=${encodeURIComponent(q)}`);
+        const res = await client.get(`/api/v1/projects/${pid}/kb/search?q=${encodeURIComponent(q)}`);
         emit(res.raw?.data ?? res.raw);
       }
     },
@@ -1246,7 +1417,7 @@ var kb = {
           statSync(target);
           const content = readFileSync2(target, "utf8");
           const title = target.split("/").pop().replace(/\.[^.]+$/, "");
-          const res = await client.post(`/api/projects/${pid}/kb/articles`, { title, content });
+          const res = await client.post(`/api/v1/projects/${pid}/kb/articles`, { title, content });
           emit(res.raw?.data ?? res.raw);
         }
       }
@@ -1357,68 +1528,97 @@ var integrations = {
   summary: "Manage third-party integrations (Slack, Shopify, Stripe, Linear, GitHub, Discord)",
   subcommands: {
     list: {
-      summary: "List integrations connected to current project",
+      summary: "List integrations installed on the current project",
       async run({ flags }) {
         const client = new ApiClient({ projectId: flags["project"] });
         const pid = client.requireProject();
-        const res = await client.get(`/api/projects/${pid}/integrations`);
+        const res = await client.get(`/api/v1/projects/${pid}/integrations`);
+        emit(res.raw?.data ?? res.raw);
+      }
+    },
+    catalog: {
+      summary: "Browse the full integration catalog (installed + available)",
+      flags: [
+        { name: "q", type: "string" },
+        { name: "category", type: "string" },
+        { name: "status", type: "string" }
+      ],
+      async run({ flags }) {
+        const client = new ApiClient({ projectId: flags["project"] });
+        const pid = client.requireProject();
+        const qs = new URLSearchParams();
+        if (flags["q"]) qs.set("q", flags["q"]);
+        if (flags["category"]) qs.set("category", flags["category"]);
+        if (flags["status"]) qs.set("status", flags["status"]);
+        const suffix = qs.toString() ? `?${qs}` : "";
+        const res = await client.get(`/api/v1/projects/${pid}/integrations/catalog${suffix}`);
         emit(res.raw?.data ?? res.raw);
       }
     },
     get: {
-      summary: "Get one integration",
-      usage: "rogeriq integrations get <integration-id>",
+      summary: "Get catalog entry + install state for one provider",
+      usage: "rogeriq integrations get <provider>",
       async run({ positional, flags }) {
-        const [id] = positional;
-        if (!id) throw new CliError("Usage: rogeriq integrations get <id>", "BAD_USAGE", 1);
+        const [provider] = positional;
+        if (!provider) throw new CliError("Usage: rogeriq integrations get <provider>", "BAD_USAGE", 1);
         const client = new ApiClient({ projectId: flags["project"] });
         const pid = client.requireProject();
-        const res = await client.get(`/api/projects/${pid}/integrations/${id}`);
+        const res = await client.get(`/api/v1/projects/${pid}/integrations/catalog/${provider}`);
         emit(res.raw?.data ?? res.raw);
       }
     },
     connect: {
-      summary: "Get OAuth install URL for a provider (open in browser to complete)",
-      usage: "rogeriq integrations connect <slack|github|shopify|stripe|linear|discord>",
+      summary: "Get the install URL for a provider (open in browser to complete OAuth)",
+      usage: "rogeriq integrations connect <provider>",
       async run({ positional, flags }) {
         const [provider] = positional;
         if (!provider) throw new CliError("Usage: rogeriq integrations connect <provider>", "BAD_USAGE", 1);
         const client = new ApiClient({ projectId: flags["project"] });
         const pid = client.requireProject();
-        const res = await client.get(`/api/projects/${pid}/integrations/${provider}/install-url`);
+        const res = await client.post(`/api/v1/projects/${pid}/integrations/${provider}/install-url`);
         emit(res.raw?.data ?? res.raw);
       }
     },
-    configure: {
-      summary: "Update integration config (provider-specific JSON payload)",
-      usage: "rogeriq integrations configure <id> --config '{...}'",
-      flags: [{ name: "config", type: "string" }],
+    lifecycle: {
+      summary: "Update integration lifecycle (status, display name, sidebar, settings)",
+      usage: "rogeriq integrations lifecycle <provider> [--status active|paused] [--display-name ...] [--sidebar true|false] [--settings '{...}']",
+      flags: [
+        { name: "status", type: "string" },
+        { name: "display-name", type: "string" },
+        { name: "sidebar", type: "string" },
+        { name: "settings", type: "string" }
+      ],
       async run({ positional, flags }) {
-        const [id] = positional;
-        const raw = flags["config"];
-        if (!id || !raw) throw new CliError("Usage: rogeriq integrations configure <id> --config '{...}'", "BAD_USAGE", 1);
-        let body;
-        try {
-          body = JSON.parse(raw);
-        } catch {
-          throw new CliError("--config must be valid JSON", "BAD_JSON", 1);
+        const [provider] = positional;
+        if (!provider) throw new CliError("Usage: rogeriq integrations lifecycle <provider>", "BAD_USAGE", 1);
+        const body = {};
+        if (flags["status"]) body["status"] = flags["status"];
+        if (flags["display-name"]) body["display_name"] = flags["display-name"];
+        if (flags["sidebar"]) body["sidebar_enabled"] = flags["sidebar"] === "true";
+        if (flags["settings"]) {
+          try {
+            body["settings"] = JSON.parse(flags["settings"]);
+          } catch {
+            throw new CliError("--settings must be valid JSON", "BAD_JSON", 1);
+          }
         }
+        if (Object.keys(body).length === 0) throw new CliError("No lifecycle changes provided", "NO_UPDATES", 1);
         const client = new ApiClient({ projectId: flags["project"] });
         const pid = client.requireProject();
-        const res = await client.patch(`/api/projects/${pid}/integrations/${id}`, body);
+        const res = await client.patch(`/api/v1/projects/${pid}/integrations/${provider}/lifecycle`, body);
         emit(res.raw?.data ?? res.raw);
       }
     },
     disconnect: {
       summary: "Disconnect an integration",
-      usage: "rogeriq integrations disconnect <id>",
+      usage: "rogeriq integrations disconnect <provider>",
       async run({ positional, flags }) {
-        const [id] = positional;
-        if (!id) throw new CliError("Usage: rogeriq integrations disconnect <id>", "BAD_USAGE", 1);
+        const [provider] = positional;
+        if (!provider) throw new CliError("Usage: rogeriq integrations disconnect <provider>", "BAD_USAGE", 1);
         const client = new ApiClient({ projectId: flags["project"] });
         const pid = client.requireProject();
-        await client.del(`/api/projects/${pid}/integrations/${id}`);
-        emit({ ok: true, disconnected: id });
+        await client.del(`/api/v1/projects/${pid}/integrations/${provider}`);
+        emit({ ok: true, disconnected: provider });
       }
     }
   }
@@ -1434,7 +1634,7 @@ var forms = {
       async run({ flags }) {
         const client = new ApiClient({ projectId: flags["project"] });
         const pid = client.requireProject();
-        const res = await client.get(`/api/projects/${pid}/forms`);
+        const res = await client.get(`/api/v1/projects/${pid}/forms`);
         emit(res.raw?.data ?? res.raw);
       }
     },
@@ -1446,7 +1646,7 @@ var forms = {
         if (!id) throw new CliError("Usage: rogeriq forms get <id>", "BAD_USAGE", 1);
         const client = new ApiClient({ projectId: flags["project"] });
         const pid = client.requireProject();
-        const res = await client.get(`/api/projects/${pid}/forms/${id}`);
+        const res = await client.get(`/api/v1/projects/${pid}/forms/${id}`);
         emit(res.raw?.data ?? res.raw);
       }
     },
@@ -1467,7 +1667,7 @@ var forms = {
         else throw new CliError("--schema or --schema-file required", "MISSING_SCHEMA", 1);
         const client = new ApiClient({ projectId: flags["project"] });
         const pid = client.requireProject();
-        const res = await client.post(`/api/projects/${pid}/forms`, { name, schema });
+        const res = await client.post(`/api/v1/projects/${pid}/forms`, { name, schema });
         emit(res.raw?.data ?? res.raw);
       }
     },
@@ -1489,7 +1689,7 @@ var forms = {
         if (Object.keys(body).length === 0) throw new CliError("No updates provided", "NO_UPDATES", 1);
         const client = new ApiClient({ projectId: flags["project"] });
         const pid = client.requireProject();
-        const res = await client.patch(`/api/projects/${pid}/forms/${id}`, body);
+        const res = await client.patch(`/api/v1/projects/${pid}/forms/${id}`, body);
         emit(res.raw?.data ?? res.raw);
       }
     },
@@ -1501,7 +1701,7 @@ var forms = {
         if (!id) throw new CliError("Usage: rogeriq forms archive <id>", "BAD_USAGE", 1);
         const client = new ApiClient({ projectId: flags["project"] });
         const pid = client.requireProject();
-        const res = await client.post(`/api/projects/${pid}/forms/${id}/archive`);
+        const res = await client.post(`/api/v1/projects/${pid}/forms/${id}/archive`);
         emit(res.raw?.data ?? res.raw);
       }
     },
@@ -1513,7 +1713,7 @@ var forms = {
         if (!id) throw new CliError("Usage: rogeriq forms submissions <id>", "BAD_USAGE", 1);
         const client = new ApiClient({ projectId: flags["project"] });
         const pid = client.requireProject();
-        const res = await client.get(`/api/projects/${pid}/forms/${id}/submissions`);
+        const res = await client.get(`/api/v1/projects/${pid}/forms/${id}/submissions`);
         emit(res.raw?.data ?? res.raw);
       }
     }
@@ -1529,7 +1729,7 @@ var beacons = {
       async run({ flags }) {
         const client = new ApiClient({ projectId: flags["project"] });
         const pid = client.requireProject();
-        const res = await client.get(`/api/projects/${pid}/beacons`);
+        const res = await client.get(`/api/v1/projects/${pid}/beacons`);
         emit(res.raw?.data ?? res.raw);
       }
     },
@@ -1541,7 +1741,7 @@ var beacons = {
         if (!id) throw new CliError("Usage: rogeriq beacons get <id>", "BAD_USAGE", 1);
         const client = new ApiClient({ projectId: flags["project"] });
         const pid = client.requireProject();
-        const res = await client.get(`/api/projects/${pid}/beacons/${id}`);
+        const res = await client.get(`/api/v1/projects/${pid}/beacons/${id}`);
         emit(res.raw?.data ?? res.raw);
       }
     },
@@ -1566,7 +1766,7 @@ var beacons = {
         }
         const client = new ApiClient({ projectId: flags["project"] });
         const pid = client.requireProject();
-        const res = await client.post(`/api/projects/${pid}/beacons`, body);
+        const res = await client.post(`/api/v1/projects/${pid}/beacons`, body);
         emit(res.raw?.data ?? res.raw);
       }
     },
@@ -1586,7 +1786,7 @@ var beacons = {
         }
         const client = new ApiClient({ projectId: flags["project"] });
         const pid = client.requireProject();
-        const res = await client.patch(`/api/projects/${pid}/beacons/${id}`, body);
+        const res = await client.patch(`/api/v1/projects/${pid}/beacons/${id}`, body);
         emit(res.raw?.data ?? res.raw);
       }
     },
@@ -1598,7 +1798,7 @@ var beacons = {
         if (!id) throw new CliError("Usage: rogeriq beacons archive <id>", "BAD_USAGE", 1);
         const client = new ApiClient({ projectId: flags["project"] });
         const pid = client.requireProject();
-        const res = await client.post(`/api/projects/${pid}/beacons/${id}/archive`);
+        const res = await client.post(`/api/v1/projects/${pid}/beacons/${id}/archive`);
         emit(res.raw?.data ?? res.raw);
       }
     }
@@ -1912,7 +2112,7 @@ var tools = [
     },
     async call(client, args) {
       const pid = client.requireProject();
-      const res = await client.get(`/api/projects/${pid}/kb/search?q=${encodeURIComponent(String(args["q"]))}`);
+      const res = await client.get(`/api/v1/projects/${pid}/kb/search?q=${encodeURIComponent(String(args["q"]))}`);
       return res.raw;
     }
   },
@@ -1922,7 +2122,7 @@ var tools = [
     inputSchema: { type: "object", properties: {} },
     async call(client) {
       const pid = client.requireProject();
-      const res = await client.get(`/api/projects/${pid}/kb/articles`);
+      const res = await client.get(`/api/v1/projects/${pid}/kb/articles`);
       return res.raw;
     }
   },
@@ -1941,7 +2141,7 @@ var tools = [
     },
     async call(client, args) {
       const pid = client.requireProject();
-      const res = await client.post(`/api/projects/${pid}/kb/articles`, args);
+      const res = await client.post(`/api/v1/projects/${pid}/kb/articles`, args);
       return res.raw;
     }
   },
@@ -1955,7 +2155,7 @@ var tools = [
     },
     async call(client, args) {
       const pid = client.requireProject();
-      const res = await client.post(`/api/projects/${pid}/agent/respond`, args);
+      const res = await client.post(`/api/v1/projects/${pid}/agent/respond`, args);
       return res.raw;
     }
   },
@@ -2021,7 +2221,57 @@ var tools = [
     inputSchema: { type: "object", properties: {} },
     async call(client) {
       const pid = client.requireProject();
-      const res = await client.get(`/api/projects/${pid}/integrations`);
+      const res = await client.get(`/api/v1/projects/${pid}/integrations`);
+      return res.raw;
+    }
+  },
+  {
+    name: "browse_integration_catalog",
+    description: "Browse all available integrations with install state. Optional category/status/query filters.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        q: { type: "string", description: "Free-text search" },
+        category: { type: "string" },
+        status: { type: "string" }
+      }
+    },
+    async call(client, args) {
+      const pid = client.requireProject();
+      const qs = new URLSearchParams();
+      for (const k of ["q", "category", "status"]) {
+        const v = args[k];
+        if (v !== void 0 && v !== null) qs.set(k, String(v));
+      }
+      const res = await client.get(`/api/v1/projects/${pid}/integrations/catalog?${qs}`);
+      return res.raw;
+    }
+  },
+  {
+    name: "get_integration_install_url",
+    description: "Return a browser URL the user should open to install or reconnect an integration.",
+    inputSchema: {
+      type: "object",
+      properties: { provider: { type: "string", description: "e.g. slack, github, shopify" } },
+      required: ["provider"]
+    },
+    async call(client, args) {
+      const pid = client.requireProject();
+      const res = await client.post(`/api/v1/projects/${pid}/integrations/${args["provider"]}/install-url`);
+      return res.raw;
+    }
+  },
+  {
+    name: "disconnect_integration",
+    description: "Disconnect an integration (status=disconnected, sidebar hidden).",
+    inputSchema: {
+      type: "object",
+      properties: { provider: { type: "string" } },
+      required: ["provider"]
+    },
+    async call(client, args) {
+      const pid = client.requireProject();
+      const res = await client.del(`/api/v1/projects/${pid}/integrations/${args["provider"]}`);
       return res.raw;
     }
   },
@@ -2090,7 +2340,7 @@ async function runMcpServer() {
         return {
           protocolVersion: "2024-11-05",
           capabilities: { tools: {} },
-          serverInfo: { name: "rogeriq", version: "0.1.0" }
+          serverInfo: { name: "rogeriq", version: "0.3.0" }
         };
       case "notifications/initialized":
         return void 0;
@@ -2213,7 +2463,7 @@ var GLOBAL_FLAGS = [
   { name: "version", alias: "v", type: "boolean" },
   { name: "project", type: "string" }
 ];
-var VERSION = "0.1.0";
+var VERSION = "0.3.0";
 async function main() {
   const argv = process.argv.slice(2);
   const { positional, flags } = parseArgs(argv, GLOBAL_FLAGS);
@@ -2226,7 +2476,7 @@ async function main() {
 `);
     return;
   }
-  if (positional.length === 0 || flagBool(flags, "help")) {
+  if (positional.length === 0) {
     printRootHelp();
     return;
   }
@@ -2252,6 +2502,9 @@ async function main() {
   const cmdParsed = parseArgs(cmdArgsRaw, [...GLOBAL_FLAGS, ...cmd.flags ?? []]);
   const project = flagString(cmdParsed.flags, "project") ?? flagString(flags, "project");
   if (project) cmdParsed.flags["project"] = project;
+  if (flagBool(flags, "help")) cmdParsed.flags["help"] = true;
+  if (flagBool(flags, "json")) cmdParsed.flags["json"] = true;
+  if (flagBool(flags, "quiet")) cmdParsed.flags["quiet"] = true;
   if (flagBool(cmdParsed.flags, "help")) {
     printCommandHelp(groupName, subName ?? "", cmd);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rogeriq/cli",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Command-line interface for RogerIQ. Manage conversations, projects, knowledge base, widget, integrations, and webhooks from your terminal or AI agents.",
   "license": "MIT",
   "type": "module",
@@ -10,18 +10,21 @@
   "files": [
     "dist",
     "README.md",
-    "AGENTS.md"
+    "AGENTS.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "esbuild src/index.ts --bundle --platform=node --target=node18 --format=esm --outfile=dist/index.mjs --banner:js='#!/usr/bin/env node' --packages=external",
     "dev": "esbuild src/index.ts --bundle --platform=node --target=node18 --format=esm --outfile=dist/index.mjs --banner:js='#!/usr/bin/env node' --watch",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
   },
   "dependencies": {},
   "devDependencies": {
     "@types/node": "^22.10.0",
     "esbuild": "^0.24.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
   },
   "engines": {
     "node": ">=18"