@arbidocs/cli 0.3.40 → 0.3.42

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## v0.3.42
+
+[compare changes](https://github.com/arbicity/ARBI-frontend/compare/v0.3.40...HEAD)
+
+### 🚀 Enhancements
+
+- **cli:** Workspace improvements — --json, workspace current, delete + copy fixes ([#623](https://github.com/arbicity/ARBI-frontend/pull/623))
+
 ## v0.3.40
 
 [compare changes](https://github.com/arbicity/ARBI-frontend/compare/v0.3.39...HEAD)

package/SKILL.md

@@ -32,12 +32,12 @@ Documents, conversations, and tags are scoped per workspace. An active workspace
 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)
+- Active workspace ID: `arbi workspace current` (prints the ID, empty string if none) · `arbi workspace current --json` for full details
+- Pick/switch: `arbi workspace select <id-or-name>` — accepts a workspace ID or a unique (case-insensitive) name; clears the chat session; uploaded docs in other workspaces are unaffected
+- Create: `arbi workspace create "My WS"` — does NOT auto-select. Use `--select` to create + select in one go, `--json` for scripts
+- Rename / edit: `arbi workspace update '{"name":"New Name"}'` (add `--json` for scripts)
+- Delete: `arbi workspace delete [id-or-name]` — prompts for confirmation in interactive shells. In non-TTY shells you **must** pass `-y/--yes` (otherwise the command refuses to delete). If you delete the active workspace, the selection is cleared. `--json` outputs `{id, deleted}`
+- Share: `arbi workspace add-user <email> -r <role>` where role is `owner|collaborator|guest` (plan-limited — free tier has 0 collaborator slots)
 - 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
@@ -45,8 +45,10 @@ Common moves:
 Scripting notes:
 
 - The table output of `arbi workspaces` is NOT reliably parseable (names contain spaces, status cells may contain glyphs). Use `--json` or `--ids`.
+- Switch-by-name in one line: `arbi workspace select "My WS"`. If the name is ambiguous, the CLI lists the matches and exits non-zero — use the ID.
 - 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.
+- Agent accounts typically have 0 collaborator slots, so `workspace add-user` errors with "Collaborator limit reached" unless the plan is upgraded.
 
 ## Tips
 
@@ -54,7 +56,7 @@ Scripting notes:
 - 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.
+- Use `arbi status --json` and `arbi workspace current` to read CLI state from scripts. `arbi workspaces --json` lists every workspace with `is_selected` marked.
 
 ## For Automations / AI Agents
 
@@ -76,3 +78,19 @@ Scripting notes:
 - **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

@@ -3641,7 +3641,7 @@ function getLatestVersion(skipCache = false) {
   }
 }
 function getCurrentVersion() {
-  return "0.3.40";
+  return "0.3.42";
 }
 function readChangelog(fromVersion, toVersion) {
   try {
@@ -3694,17 +3694,17 @@ function showChangelog(fromVersion, toVersion) {
 async function checkForUpdates(autoUpdate) {
   try {
     const latest = getLatestVersion();
-    if (!latest || latest === "0.3.40") return;
+    if (!latest || latest === "0.3.42") return;
     if (autoUpdate) {
       warn(`
-Your arbi version is out of date (${"0.3.40"} \u2192 ${latest}). Updating...`);
+Your arbi version is out of date (${"0.3.42"} \u2192 ${latest}). Updating...`);
       child_process.execSync("npm install -g @arbidocs/cli@latest", { stdio: "inherit" });
-      showChangelog("0.3.40", latest);
+      showChangelog("0.3.42", latest);
       console.log(`Updated to ${latest}.`);
     } else {
       warn(
         `
-Your arbi version is out of date (${"0.3.40"} \u2192 ${latest}).
+Your arbi version is out of date (${"0.3.42"} \u2192 ${latest}).
 Run "arbi update" to upgrade, or "arbi update auto" to always stay up to date.`
       );
     }
@@ -3714,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.40") {
+    if (cached && cached.latest !== "0.3.42") {
       warn(
-        `Your arbi version is out of date (${"0.3.40"} \u2192 ${cached.latest}). Run "arbi update".`
+        `Your arbi version is out of date (${"0.3.42"} \u2192 ${cached.latest}). Run "arbi update".`
       );
     }
   } catch {
@@ -4417,12 +4417,49 @@ function registerStatusCommand(program2) {
     }
   });
 }
+function resolveWorkspaceSelector(list, selector) {
+  const byId = list.find((w) => w.external_id === selector);
+  if (byId) return { ok: true, id: byId.external_id, ws: byId };
+  const lower = selector.toLowerCase();
+  const byName = list.filter((w) => (w.name ?? "").toLowerCase() === lower);
+  if (byName.length === 1) return { ok: true, id: byName[0].external_id, ws: byName[0] };
+  if (byName.length > 1) return { ok: false, reason: "ambiguous", matches: byName };
+  return { ok: false, reason: "not-found" };
+}
+function printResolveError(list, selector, res) {
+  if (res.ok) return;
+  if (res.reason === "ambiguous") {
+    error(`Workspace name "${selector}" is ambiguous \u2014 multiple matches:`);
+    for (const w of res.matches ?? []) error(`  ${w.external_id}  ${w.name}`);
+    error("Use the workspace ID instead.");
+    return;
+  }
+  error(`Workspace ${selector} not found.`);
+  error("Available workspaces:");
+  for (const w of list) error(`  ${w.external_id}  ${w.name}`);
+}
 function registerWorkspacesCommand(program2) {
-  program2.command("workspaces").description("List workspaces").action(
-    runAction(async () => {
+  program2.command("workspaces").description("List workspaces").option("--json", "Output as JSON").option("--ids", "Output only workspace IDs (one per line)").action(
+    (opts) => runAction(async () => {
       const { arbi } = await resolveAuth();
       const data = await sdk.workspaces.listWorkspaces(arbi);
       updateCompletionCache(data);
+      if (opts.ids) {
+        for (const w of data) console.log(w.external_id);
+        return;
+      }
+      if (opts.json) {
+        const selectedId = getConfig()?.selectedWorkspaceId ?? null;
+        const out = data.map((w) => ({
+          id: w.external_id,
+          name: w.name,
+          docs: w.shared_document_count + w.private_document_count,
+          role: w.users?.[0]?.role ?? null,
+          is_selected: w.external_id === selectedId
+        }));
+        console.log(JSON.stringify(out, null, 2));
+        return;
+      }
       if (data.length === 0) {
         console.log("No workspaces found.");
         return;
@@ -4444,11 +4481,51 @@ function registerWorkspacesCommand(program2) {
         ],
         data
       );
-    })
+    })()
   );
   const workspace = program2.command("workspace").description("Workspace management");
-  workspace.command("select [id]").description("Select active workspace (interactive picker if no ID given)").action(
-    (id) => runAction(async () => {
+  workspace.command("current").description("Print the currently selected workspace ID (empty string if none)").option("--json", "Output full details as JSON").action(
+    (opts) => runAction(async () => {
+      const selectedId = getConfig()?.selectedWorkspaceId ?? "";
+      if (!opts.json) {
+        console.log(selectedId);
+        return;
+      }
+      if (!selectedId) {
+        console.log(JSON.stringify({ id: null, name: null, docs: 0, role: null }, null, 2));
+        return;
+      }
+      const { arbi } = await resolveAuth();
+      const data = await sdk.workspaces.listWorkspaces(arbi);
+      const ws = data.find((w) => w.external_id === selectedId);
+      if (!ws) {
+        console.log(
+          JSON.stringify(
+            { id: selectedId, name: null, docs: 0, role: null, stale: true },
+            null,
+            2
+          )
+        );
+        return;
+      }
+      console.log(
+        JSON.stringify(
+          {
+            id: ws.external_id,
+            name: ws.name,
+            docs: ws.shared_document_count + ws.private_document_count,
+            role: ws.users?.[0]?.role ?? null
+          },
+          null,
+          2
+        )
+      );
+    })()
+  );
+  workspace.command("select [id-or-name]").description(
+    "Select active workspace (accepts ID or unique name; interactive picker if nothing given)"
+  ).action(
+    (idOrName) => runAction(async () => {
       const { arbi } = await resolveAuth();
       const data = await sdk.workspaces.listWorkspaces(arbi);
       updateCompletionCache(data);
@@ -4457,15 +4534,13 @@ function registerWorkspacesCommand(program2) {
         return;
       }
       let selectedId;
-      if (id) {
-        const ws2 = data.find((w) => w.external_id === id);
-        if (!ws2) {
-          error(`Workspace ${id} not found.`);
-          error("Available workspaces:");
-          for (const w of data) error(`  ${w.external_id}  ${w.name}`);
+      if (idOrName) {
+        const res = resolveWorkspaceSelector(data, idOrName);
+        if (!res.ok) {
+          printResolveError(data, idOrName, res);
           process.exit(1);
         }
-        selectedId = id;
+        selectedId = res.id;
       } else {
         const choices = sdk.formatWorkspaceChoices(data);
         selectedId = await promptSelect("Select workspace", choices);
@@ -4476,7 +4551,7 @@ function registerWorkspacesCommand(program2) {
       success(`Selected: ${ws.name} (${ref(selectedId)})`);
     })()
   );
-  workspace.command("create <name>").description("Create a new workspace").option("-d, --description <text>", "Workspace description").option("--public", "Make workspace public", false).action(
+  workspace.command("create <name>").description("Create a new workspace").option("-d, --description <text>", "Workspace description").option("--public", "Make workspace public", false).option("--select", "Set the new workspace as the active selection", false).option("--json", "Output the new workspace as JSON").action(
     (name, opts) => runAction(async () => {
       const { arbi, loginResult } = await resolveAuth();
       const userProjects = await sdk.projects.listProjects(arbi);
@@ -4491,37 +4566,114 @@ function registerWorkspacesCommand(program2) {
         opts.description,
         opts.public ?? false
       );
+      if (opts.select) {
+        updateConfig({ selectedWorkspaceId: data.external_id });
+        clearChatSession();
+      }
+      if (opts.json) {
+        console.log(
+          JSON.stringify(
+            {
+              id: data.external_id,
+              name: data.name,
+              selected: opts.select ?? false
+            },
+            null,
+            2
+          )
+        );
+        return;
+      }
       success(`Created: ${data.name} (${ref(data.external_id)})`);
+      if (opts.select) success(`Selected: ${data.name} (${ref(data.external_id)})`);
     })()
   );
-  workspace.command("delete [id]").description("Delete a workspace (defaults to selected workspace)").action(
-    (id) => runAction(async () => {
+  workspace.command("delete [id-or-name]").description("Delete a workspace (defaults to selected workspace)").option("-y, --yes", "Skip confirmation prompt (required in non-interactive shells)", false).option("--json", "Output the result as JSON").action(
+    (idOrName, opts) => runAction(async () => {
       const { arbi } = await resolveAuth();
-      const targetId = id ?? getConfig()?.selectedWorkspaceId;
-      if (!targetId) {
-        error("No workspace ID given and no workspace selected. Run: arbi workspace select");
-        process.exit(1);
+      const config = getConfig();
+      let targetId;
+      let targetName;
+      if (idOrName) {
+        const data = await sdk.workspaces.listWorkspaces(arbi);
+        const res = resolveWorkspaceSelector(data, idOrName);
+        if (!res.ok) {
+          printResolveError(data, idOrName, res);
+          process.exit(1);
+        }
+        targetId = res.id;
+        targetName = res.ws.name;
+      } else {
+        targetId = config?.selectedWorkspaceId;
+        if (!targetId) {
+          error("No workspace ID given and no workspace selected. Run: arbi workspace select");
+          process.exit(1);
+        }
+      }
+      const isInteractive = process.stdin.isTTY === true && process.stdout.isTTY === true;
+      if (!opts.yes) {
+        if (!isInteractive) {
+          error(
+            `Refusing to delete ${targetId} without confirmation. Re-run with --yes (non-interactive shell).`
+          );
+          process.exit(1);
+        }
+        const label2 = targetName ? `"${targetName}" (${targetId})` : targetId;
+        const confirmed = await promptConfirm(
+          `Delete workspace ${label2}? This removes all documents, conversations, and tags in it.`,
+          false
+        );
+        if (!confirmed) {
+          console.log("Cancelled.");
+          return;
+        }
       }
       await sdk.workspaces.deleteWorkspaces(arbi, [targetId]);
+      if (config?.selectedWorkspaceId === targetId) {
+        updateConfig({ selectedWorkspaceId: void 0 });
+      }
       const session = getChatSession();
       if (session.workspaceId === targetId) {
         clearChatSession();
       }
+      if (opts.json) {
+        console.log(JSON.stringify({ id: targetId, deleted: true }, null, 2));
+        return;
+      }
       success(`Deleted workspace ${targetId}`);
     })()
   );
-  workspace.command("update <json>").description("Update workspace properties (pass JSON)").option("-w, --workspace <id>", "Workspace ID (defaults to selected workspace)").action(
+  workspace.command("update <json>").description("Update workspace properties (pass JSON)").option("-w, --workspace <id>", "Workspace ID (defaults to selected workspace)").option("--json", "Output the updated workspace as JSON").action(
     (json, opts) => runAction(async () => {
       const body = parseJsonArg(json, `arbi workspace update '{"name": "New Name"}'`);
       const { arbi } = await resolveWorkspace(opts.workspace);
       const data = await sdk.workspaces.updateWorkspace(arbi, body);
+      if (opts.json) {
+        console.log(JSON.stringify({ id: data.external_id, name: data.name }, null, 2));
+        return;
+      }
       success(`Updated: ${data.name} (${ref(data.external_id)})`);
     })()
   );
-  workspace.command("users").description("List users in the active workspace").option("-w, --workspace <id>", "Workspace ID (defaults to selected workspace)").action(
+  workspace.command("users").description("List users 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.workspaces.listWorkspaceUsers(arbi);
+      if (opts.json) {
+        const out = data.map((r) => {
+          const u = r.user ?? {};
+          return {
+            user_id: u.external_id ?? null,
+            email: u.email ?? null,
+            name: [u.given_name, u.family_name].filter(Boolean).join(" ") || null,
+            role: r.role,
+            document_count: r.document_count,
+            conversation_count: r.conversation_count
+          };
+        });
+        console.log(JSON.stringify(out, null, 2));
+        return;
+      }
       if (data.length === 0) {
         console.log("No users found.");
         return;
@@ -4598,7 +4750,18 @@ function registerWorkspacesCommand(program2) {
         signingPrivateKeyBase64
       );
       const data = await sdk.workspaces.copyDocuments(arbi, targetId, docIds, targetKey);
-      success(`${data.detail} (${data.documents_copied} document(s) copied)`);
+      const copied = data.documents_copied ?? 0;
+      const requested = docIds.length;
+      if (copied === 0) {
+        error(`Copied 0 of ${requested} document(s). ${data.detail ?? ""}`.trim());
+        error("Hint: documents must be fully indexed before they can be copied.");
+        process.exit(1);
+      }
+      if (copied < requested) {
+        error(`Copied ${copied} of ${requested} document(s). ${data.detail ?? ""}`.trim());
+        return;
+      }
+      success(`Copied ${copied} document(s) to ${targetId}`);
     })()
   );
 }
@@ -4756,7 +4919,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)) {
@@ -4967,10 +5141,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(
@@ -5705,7 +5888,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.'
         );
@@ -6209,7 +6392,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) {
@@ -6235,9 +6424,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)`
       );
@@ -8258,7 +8462,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.40");
+program.name("arbi").description("ARBI CLI \u2014 interact with ARBI from the terminal").version("0.3.42");
 registerConfigCommand(program);
 registerLoginCommand(program);
 registerRegisterCommand(program);