@arbidocs/cli 0.3.39 → 0.3.41

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## v0.3.41
+
+[compare changes](https://github.com/arbicity/ARBI-frontend/compare/v0.3.40...HEAD)
+
+### 🏡 Chore
+
+- Release v0.3.40 [skip ci] ([5e404545](https://github.com/arbicity/ARBI-frontend/commit/5e404545))
+
 ## v0.3.39
 
 [compare changes](https://github.com/arbicity/ARBI-frontend/compare/v0.3.38...HEAD)

package/SKILL.md

@@ -6,15 +6,18 @@ ARBI is an enterprise document intelligence platform with E2E encrypted communic
 
 1. Install: `npm install -g @arbidocs/cli`
 2. Configure server: `arbi config set-url https://<deployment>.arbibox.com`
-3. Get a claim code from your parent user (via ARBI web UI → Settings → Agents → Authorize, or `arbi authorize agent`)
-4. Connect: `arbi connect --code <claim-code>`
-5. Verify: `arbi status`
+3. Log in (pick one):
+   - Interactive: `arbi quickstart` (wizard) or `arbi login -e <email> -p <password>`
+   - Scripted (humans with API access): `arbi register -e <email> -p <password> --verification-code <code>`
+   - Scripted (AI agents / bots, requires `SUPPORT_API_KEY`): `arbi agent-create --email agent-<name>@<domain> --workspace-name "<name>"`
+     - The email MUST start with `agent-`. This path creates the account, logs in, and selects the new workspace in one call.
+4. Verify: `arbi status` (add `--json` for machine-readable output)
 
-For multiple agents on the same machine, set `ARBI_ID=<name>` to isolate config in `~/.arbi/<name>/`.
+For multiple agents on the same machine, set `ARBI_ID=<name>` (or `ARBI_CONFIG_DIR=<path>`) to isolate config in `~/.arbi/<name>/`.
 
 ## When to Use
 
-- **Document questions**: `arbi ask <question>` — performs RAG retrieval across workspace documents
+- **Document questions**: `arbi ask <question>` — performs RAG retrieval across workspace documents (no quotes needed around the question)
 - **Document management**: `arbi docs`, `arbi upload`, `arbi download`, `arbi find`
 - **Local files**: `arbi local ls`, `arbi local find "**/*.pdf"`, `arbi local cat <file>`, `arbi local tree`
 - **Secure messaging**: `arbi dm send <recipient> <message>` — E2E encrypted
@@ -22,9 +25,70 @@ For multiple agents on the same machine, set `ARBI_ID=<name>` to isolate config
 
 Every command supports `--help`. Explore with `arbi --help` to discover all capabilities.
 
+## Workspaces
+
+Documents, conversations, and tags are scoped per workspace. An active workspace is stored in the CLI config and used by `arbi docs`, `arbi upload`, `arbi ask`, etc.
+
+Common moves:
+
+- List: `arbi workspaces` (human) · `arbi workspaces --json` (script) · `arbi workspaces --ids`
+- Active workspace ID: `arbi workspace current` (prints the ID, empty string if none)
+- Pick/switch: `arbi workspace select <id>` — clears the chat session; uploaded docs in other workspaces are unaffected
+- Create: `arbi workspace create "My WS"` — does NOT auto-select, follow with `workspace select`
+- Rename / edit: `arbi workspace update '{"name":"New Name"}'`
+- Delete: `arbi workspace delete [id]` — deletes immediately (no confirmation prompt); if you delete the active workspace, the selection is cleared
+- Share: `arbi workspace add-user <email> -r <role>` where role is `owner|collaborator|guest` (may be plan-limited)
+- List members: `arbi workspace users [--json]`
+- Remove member: `arbi workspace remove-user <user-id>`
+- Copy docs between workspaces: `arbi workspace copy <target-ws-id> <doc-id>...` — only copies documents that have finished indexing; partial/failed copies exit non-zero
+
+Scripting notes:
+
+- The table output of `arbi workspaces` is NOT reliably parseable (names contain spaces, status cells may contain glyphs). Use `--json` or `--ids`.
+- Sessions persist between CLI invocations via the config file (default `~/.arbi/`, override with `ARBI_CONFIG_DIR`).
+- Per-agent isolation: run agents with their own `ARBI_CONFIG_DIR=<path>` (or `ARBI_ID=<name>`) to avoid stomping each other's active workspace.
+
 ## Tips
 
-- If not logged in, run `arbi connect --code <code>` with a new claim code from your parent user.
+- Not logged in: run `arbi login` (interactive) or, with `SUPPORT_API_KEY` set, `arbi agent-create --email agent-<name>@<domain>`.
 - If a command fails with "fetch failed", check connectivity with `arbi health`.
 - Use `arbi ask -n` to start a fresh conversation (forget prior context).
 - Use `arbi ask -v` for verbose output showing retrieval steps.
+- Use `arbi status --json` and `arbi workspace current` to read CLI state from scripts.
+
+## For Automations / AI Agents
+
+- **Structured output (`--json`)**: supported on `status`, `config show`, `health`, `models`, `workspaces`, `workspace users`, `docs`, `conversations` (or `conversations list`), `tags` (or `tags list`), `contacts` (or `contacts list`), `find`, `settings get`, `task list`, `ask -b`, `upload`, `watch`. Use it whenever parsing output. `docs` also supports `--csv`, `--ids`, and `--count`.
+- **Human table output is lossy**: table rows may contain status glyphs (`●`, `🟩`, etc.) and emoji, and column widths truncate content. Never parse tables — always pass `--json`.
+- **Exit codes**:
+  - `0` success
+  - `1` failure (bad args / auth / API / network / server error)
+  - `2` `arbi health --json` when the server reports unhealthy (the JSON body is still printed so you can introspect)
+  - `130` user-cancelled interactive prompt (Ctrl+C in `quickstart`)
+  - Always check `$?` — `arbi ask` while logged-out, typo commands, and network failures all return non-zero.
+- **Avoid interactive prompts** — pass everything as flags/env vars:
+  - `arbi login -e $ARBI_EMAIL -p $ARBI_PASSWORD -w <workspace-id>` (or set `ARBI_EMAIL`/`ARBI_PASSWORD`).
+  - `arbi agent-create --email agent-<...> --workspace-name "<name>"` (requires `SUPPORT_API_KEY`).
+  - `arbi workspace select <id>` (ID directly, no picker).
+  - `arbi docs` auto-uses the selected workspace; pass `-w <id>` to override.
+  - Do **not** run `arbi quickstart` in non-interactive contexts — it is interactive-only.
+- **Health probe**: `arbi health --json` returns the raw payload and exits `2` if the server is not healthy — useful for pre-flight checks.
+- **No color leakage**: chalk auto-disables ANSI codes when stdout is not a TTY, so `arbi docs --json | jq`, `arbi workspaces --json | jq`, etc. work cleanly. Status messages and spinners go to stderr; stdout is safe to pipe.
+- **Typo suggestions**: `arbi updat` → `error: unknown command 'updat' (Did you mean update?)` (exit 1). Works for top-level commands and nested subcommands.
+- **Completion**: `arbi completion install` (no `bash`/`zsh` arg — auto-detected from `$SHELL`).
+
+## Document Lifecycle (for agents)
+
+All document list/search/meta commands support machine-readable output. Prefer `--json`.
+
+- **Upload**: `arbi add <paths...> --json --no-watch` — prints a single JSON summary line with `docIds` and `skippedDetails`. Progress and reconnect noise are routed to stderr; stdout stays clean when `--json` is set.
+- **List**: `arbi docs --json` returns an array (or `[]` when empty). `--ids` prints one doc id per line. `--csv` prints a CSV with header. All three work on an empty workspace without erroring.
+- **Filter**: `arbi docs --status completed,failed`, `--folder <pattern>`, `--ext pdf,docx`, `--query <text>`. Combine with `--limit <n>` to stop early.
+- **Lite mode**: `arbi docs --lite --json` skips per-doc decryption for speed, but `doctags` and `doc_metadata` come back empty/null. Use full mode (omit `--lite`) if you need those.
+- **Per-doc**: `arbi doc get <id...>` returns full JSON (no flag needed). `arbi doc delete <id...>` and `arbi doc update <id> '<json>'` take IDs directly.
+- **Upload by URL**: `arbi doc upload-url <url> --json`.
+- **Download**: `arbi download <id> -o <path>` writes the file; `-o -` streams raw bytes to stdout; `--json` emits a `{doc_id, path, bytes, filename}` metadata line after writing.
+- **Tags**: `arbi tags list --json`, `arbi tags create <name> -t <type>`, `arbi tags delete <id>`.
+- **Doctags** (tag↔doc link): `arbi doctags create <tag-id> <doc-id...>` / `arbi doctags delete <tag-id> <doc-id...>`.
+- **Retrieve only**: `arbi find <query> --json` returns raw retrieval results without running the LLM.
+- **Exit codes**: 0 on success (including clean skips), 1 on error. Errors print to stderr.

package/dist/index.js

@@ -216,8 +216,12 @@ function registerConfigCommand(program2) {
       process.exit(1);
     }
   });
-  config.command("show").description("Show current configuration").action(() => {
+  config.command("show").description("Show current configuration").option("--json", "Output as JSON").action((opts) => {
     const cfg = getConfig();
+    if (opts.json) {
+      console.log(JSON.stringify(cfg ?? {}, null, 2));
+      return;
+    }
     if (!cfg) {
       dim("Not configured. Run: arbi config set-url <url>");
       return;
@@ -3637,7 +3641,7 @@ function getLatestVersion(skipCache = false) {
   }
 }
 function getCurrentVersion() {
-  return "0.3.39";
+  return "0.3.41";
 }
 function readChangelog(fromVersion, toVersion) {
   try {
@@ -3690,17 +3694,17 @@ function showChangelog(fromVersion, toVersion) {
 async function checkForUpdates(autoUpdate) {
   try {
     const latest = getLatestVersion();
-    if (!latest || latest === "0.3.39") return;
+    if (!latest || latest === "0.3.41") return;
     if (autoUpdate) {
       warn(`
-Your arbi version is out of date (${"0.3.39"} \u2192 ${latest}). Updating...`);
+Your arbi version is out of date (${"0.3.41"} \u2192 ${latest}). Updating...`);
       child_process.execSync("npm install -g @arbidocs/cli@latest", { stdio: "inherit" });
-      showChangelog("0.3.39", latest);
+      showChangelog("0.3.41", latest);
       console.log(`Updated to ${latest}.`);
     } else {
       warn(
         `
-Your arbi version is out of date (${"0.3.39"} \u2192 ${latest}).
+Your arbi version is out of date (${"0.3.41"} \u2192 ${latest}).
 Run "arbi update" to upgrade, or "arbi update auto" to always stay up to date.`
       );
     }
@@ -3710,9 +3714,9 @@ Run "arbi update" to upgrade, or "arbi update auto" to always stay up to date.`
 function hintUpdateOnError() {
   try {
     const cached = readCache();
-    if (cached && cached.latest !== "0.3.39") {
+    if (cached && cached.latest !== "0.3.41") {
       warn(
-        `Your arbi version is out of date (${"0.3.39"} \u2192 ${cached.latest}). Run "arbi update".`
+        `Your arbi version is out of date (${"0.3.41"} \u2192 ${cached.latest}). Run "arbi update".`
       );
     }
   } catch {
@@ -4377,9 +4381,25 @@ function registerLogoutCommand(program2) {
 
 // src/commands/status.ts
 function registerStatusCommand(program2) {
-  program2.command("status").description("Show current configuration and login status").action(() => {
+  program2.command("status").description("Show current configuration and login status").option("--json", "Output as JSON for scripting").action((opts) => {
     const config = getConfig();
     const creds = getCredentials();
+    if (opts.json) {
+      console.log(
+        JSON.stringify(
+          {
+            configured: !!config?.baseUrl,
+            server: config?.baseUrl ?? null,
+            logged_in: !!creds,
+            user: creds?.email ?? null,
+            workspace: config?.selectedWorkspaceId ?? null
+          },
+          null,
+          2
+        )
+      );
+      return;
+    }
     if (!config?.baseUrl) {
       dim("Not configured. Run: arbi config set-url <url>");
       return;
@@ -4736,7 +4756,18 @@ function registerDocsCommand(program2) {
         if (hardLimit !== void 0 && totalFetched >= hardLimit) break;
       }
       if (totalFetched === 0 && data.length === 0) {
-        console.log("No documents found.");
+        if (opts.json) {
+          if (opts.output) fs5.writeFileSync(opts.output, "[]\n");
+          else console.log("[]");
+        } else if (opts.ids) {
+          if (opts.output) fs5.writeFileSync(opts.output, "");
+        } else if (opts.csv) {
+          if (opts.output) fs5.writeFileSync(opts.output, csvHeader + "\n");
+        } else if (opts.count) {
+          console.log("0");
+        } else {
+          console.log("No documents found.");
+        }
         return;
       }
       if (!bufferAll && (opts.ids || opts.csv)) {
@@ -4947,10 +4978,19 @@ function registerDocsCommand(program2) {
       }
     })()
   );
-  doc.command("upload-url <urls...>").description("Upload documents from URLs").option("-w, --workspace <id>", "Workspace ID (defaults to selected workspace)").option("--shared", "Make documents shared", false).action(
+  doc.command("upload-url <urls...>").description("Upload documents from URLs").option("-w, --workspace <id>", "Workspace ID (defaults to selected workspace)").option("--shared", "Make documents shared", false).option("--json", "Output results as JSON").action(
     (urls, opts) => runAction(async () => {
       const { arbi, workspaceId } = await resolveWorkspace(opts.workspace);
       const data = await sdk.documents.uploadUrl(arbi, urls, workspaceId, opts.shared ?? false);
+      if (opts.json) {
+        console.log(
+          JSON.stringify({
+            docIds: data.doc_ext_ids ?? [],
+            skipped: data.skipped ?? []
+          })
+        );
+        return;
+      }
       success(`Uploaded: ${(data.doc_ext_ids ?? []).join(", ")}`);
       if (data.skipped && data.skipped.length > 0) {
         warn(
@@ -5685,7 +5725,7 @@ Connection closed. ${pending.size} document(s) still processing.`);
           }
         });
         await done;
-      } else if (uploadedDocs.size > 0 && !willWatch) {
+      } else if (uploadedDocs.size > 0 && !willWatch && !opts.json) {
         dim(
           'Tip: Use -W/--watch to monitor processing progress, or run "arbi docs" to check status.'
         );
@@ -6189,7 +6229,13 @@ Connection closed. ${pending.size} document(s) still processing.`);
   }
 }
 function registerDownloadCommand(program2) {
-  program2.command("download [doc-id]").description("Download a document (interactive picker if no ID given)").option("-o, --output <path>", "Output file path").option("-w, --workspace <id>", "Workspace ID (defaults to selected workspace)").action(
+  program2.command("download [doc-id]").description("Download a document (interactive picker if no ID given)").option(
+    "-o, --output <path>",
+    'Output file path. Use "-" to stream raw bytes to stdout (for piping).'
+  ).option("-w, --workspace <id>", "Workspace ID (defaults to selected workspace)").option(
+    "--json",
+    'Emit a JSON metadata line to stdout after writing the file (doc_id, path, bytes, filename). Implies a file write \u2014 use "-o -" or pipe stdout to get bytes without JSON.'
+  ).action(
     (docId, opts) => runAction(async () => {
       const { arbi, config, accessToken } = await resolveWorkspace(opts.workspace);
       if (!docId) {
@@ -6215,9 +6261,24 @@ function registerDownloadCommand(program2) {
         const match = disposition.match(/filename[*]?=(?:UTF-8''|"?)([^";]+)/i);
         if (match) filename = decodeURIComponent(match[1].replace(/"/g, ""));
       }
-      const outputPath = opts.output || path5__default.default.join(process.cwd(), filename);
       const buffer = Buffer.from(await res.arrayBuffer());
+      if (opts.output === "-") {
+        process.stdout.write(buffer);
+        return;
+      }
+      const outputPath = opts.output || path5__default.default.join(process.cwd(), filename);
       fs5__default.default.writeFileSync(outputPath, buffer);
+      if (opts.json) {
+        console.log(
+          JSON.stringify({
+            doc_id: docId,
+            path: outputPath,
+            bytes: buffer.length,
+            filename: path5__default.default.basename(outputPath)
+          })
+        );
+        return;
+      }
       success(
         `Downloaded: ${path5__default.default.basename(outputPath)} (${(buffer.length / (1024 * 1024)).toFixed(1)} MB)`
       );
@@ -6615,10 +6676,14 @@ Timeout (${timeoutSec}s), closing.`));
 }
 function registerContactsCommand(program2) {
   const contacts = program2.command("contacts").description("Manage contacts");
-  contacts.command("list").description("List all contacts").action(
-    runAction(async () => {
+  contacts.command("list").description("List all contacts").option("--json", "Output as JSON").action(
+    (opts) => runAction(async () => {
       const { arbi } = await resolveAuth();
       const data = await sdk.contacts.listContacts(arbi);
+      if (opts.json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+      }
       if (data.length === 0) {
         console.log("No contacts found.");
         return;
@@ -6636,7 +6701,7 @@ function registerContactsCommand(program2) {
         ],
         data
       );
-    })
+    })()
   );
   contacts.command("add [emails...]").description("Add contacts by email (prompt if no emails given)").action(
     (emails) => runAction(async () => {
@@ -6678,8 +6743,10 @@ function registerContactsCommand(program2) {
       success(`Removed ${contactIds.length} contact(s).`);
     })()
   );
-  contacts.action(async () => {
-    await contacts.commands.find((c) => c.name() === "list").parseAsync([], { from: "user" });
+  contacts.option("--json", "Output as JSON").action(async (opts) => {
+    const args = [];
+    if (opts.json) args.push("--json");
+    await contacts.commands.find((c) => c.name() === "list").parseAsync(args, { from: "user" });
   });
 }
 function registerDmCommand(program2) {
@@ -6901,10 +6968,14 @@ async function fetchTagChoices(arbi) {
 }
 function registerTagsCommand(program2) {
   const tags = program2.command("tags").description("Manage tags");
-  tags.command("list").description("List tags in the active workspace").option("-w, --workspace <id>", "Workspace ID (defaults to selected workspace)").action(
+  tags.command("list").description("List tags in the active workspace").option("-w, --workspace <id>", "Workspace ID (defaults to selected workspace)").option("--json", "Output as JSON").action(
     (opts) => runAction(async () => {
       const { arbi } = await resolveWorkspace(opts.workspace);
       const data = await sdk.tags.listTags(arbi);
+      if (opts.json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+      }
       if (data.length === 0) {
         console.log("No tags found.");
         return;
@@ -6997,8 +7068,11 @@ function registerTagsCommand(program2) {
       success(`Updated: ${data.name} (${ref(data.external_id)})`);
     })()
   );
-  tags.action(async (_opts, cmd) => {
-    await cmd.commands.find((c) => c.name() === "list").parseAsync([], { from: "user" });
+  tags.option("--json", "Output as JSON").option("-w, --workspace <id>", "Workspace ID (defaults to selected workspace)").action(async (opts, cmd) => {
+    const args = [];
+    if (opts.json) args.push("--json");
+    if (opts.workspace) args.push("-w", opts.workspace);
+    await cmd.commands.find((c) => c.name() === "list").parseAsync(args, { from: "user" });
   });
 }
 async function pickTag(arbi, workspaceId, message = "Select tag") {
@@ -7106,10 +7180,14 @@ async function pickConversation(arbi, workspaceId, message = "Select conversatio
 }
 function registerConversationsCommand(program2) {
   const conv = program2.command("conversations").description("Manage conversations");
-  conv.command("list").description("List conversations in the active workspace").option("-w, --workspace <id>", "Workspace ID (defaults to selected workspace)").action(
+  conv.command("list").description("List conversations in the active workspace").option("-w, --workspace <id>", "Workspace ID (defaults to selected workspace)").option("--json", "Output as JSON").action(
     (opts) => runAction(async () => {
       const { arbi } = await resolveWorkspace(opts.workspace);
       const data = await sdk.conversations.listConversations(arbi);
+      if (opts.json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+      }
       if (data.length === 0) {
         console.log("No conversations found.");
         return;
@@ -7178,18 +7256,21 @@ function registerConversationsCommand(program2) {
       success(data?.detail ?? `Deleted message ${messageId}`);
     })()
   );
-  conv.action(async (_opts, cmd) => {
-    await cmd.commands.find((c) => c.name() === "list").parseAsync([], { from: "user" });
+  conv.option("--json", "Output as JSON").option("-w, --workspace <id>", "Workspace ID (defaults to selected workspace)").action(async (opts, cmd) => {
+    const args = [];
+    if (opts.json) args.push("--json");
+    if (opts.workspace) args.push("-w", opts.workspace);
+    await cmd.commands.find((c) => c.name() === "list").parseAsync(args, { from: "user" });
   });
 }
 function registerSettingsCommand(program2) {
   const settings = program2.command("settings").description("Manage user settings");
-  settings.command("get").description("Show current user settings").action(
-    runAction(async () => {
+  settings.command("get").description("Show current user settings (always JSON; --json accepted for consistency)").option("--json", "Output as JSON (default \u2014 always JSON)").action(
+    () => runAction(async () => {
       const { arbi } = await resolveAuth();
       const data = await sdk.settings.getSettings(arbi);
       console.log(JSON.stringify(data, null, 2));
-    })
+    })()
   );
   settings.command("set <json>").description("Update user settings (pass JSON object)").action(
     (json) => runAction(async () => {
@@ -7424,10 +7505,17 @@ function registerAgentconfigCommand(program2) {
   });
 }
 function registerHealthCommand(program2) {
-  program2.command("health").description("Show server health status").action(
-    runAction(async () => {
+  program2.command("health").description("Show server health status").option("--json", "Output raw JSON for scripting").action(
+    (opts) => runAction(async () => {
       const { arbi } = await resolveAuth();
       const data = await sdk.health.getHealth(arbi);
+      if (opts.json) {
+        console.log(JSON.stringify(data, null, 2));
+        if (data.status && data.status.toLowerCase() !== "healthy") {
+          process.exit(2);
+        }
+        return;
+      }
       label("Status:", status(data.status));
       if (data.backend_git_hash) label("Backend:", data.backend_git_hash);
       if (data.frontend_docker_version) label("Frontend:", data.frontend_docker_version);
@@ -7444,12 +7532,16 @@ Models (${data.models_health.application}):`);
           console.log(`  ${m.model}: ${status(m.status)}${m.detail ? ` \u2014 ${m.detail}` : ""}`);
         }
       }
-    })
+    })()
   );
-  program2.command("models").description("List available AI models").action(
-    runAction(async () => {
+  program2.command("models").description("List available AI models").option("--json", "Output as JSON").action(
+    (opts) => runAction(async () => {
       const { arbi } = await resolveAuth();
       const data = await sdk.health.getHealthModels(arbi);
+      if (opts.json) {
+        console.log(JSON.stringify(data.models, null, 2));
+        return;
+      }
       if (data.models.length === 0) {
         console.log("No models available.");
         return;
@@ -7462,7 +7554,7 @@ Models (${data.models_health.application}):`);
         ],
         data.models
       );
-    })
+    })()
   );
 }
 function registerTuiCommand(program2) {
@@ -8031,7 +8123,7 @@ function removeCompletionBlock(content) {
 }
 function registerCompletionCommand(program2) {
   const completion = program2.command("completion").description("Manage shell tab completion");
-  completion.command("install").description("Install shell tab completion (bash/zsh)").action(() => {
+  completion.command("install").description("Install shell tab completion (auto-detects bash or zsh \u2014 no shell arg needed)").action(() => {
     const rcPath = getShellRcPath2();
     if (isCompletionInstalled(rcPath)) {
       success(`Completion already installed in ${rcPath}`);
@@ -8207,7 +8299,7 @@ console.info = (...args) => {
   _origInfo(...args);
 };
 var program = new commander.Command();
-program.name("arbi").description("ARBI CLI \u2014 interact with ARBI from the terminal").version("0.3.39");
+program.name("arbi").description("ARBI CLI \u2014 interact with ARBI from the terminal").version("0.3.41");
 registerConfigCommand(program);
 registerLoginCommand(program);
 registerRegisterCommand(program);