@arbidocs/cli 0.3.40 → 0.3.41

package/CHANGELOG.md

@@ -1,12 +1,12 @@
 # Changelog
 
-## v0.3.40
+## v0.3.41
 
-[compare changes](https://github.com/arbicity/ARBI-frontend/compare/v0.3.39...HEAD)
+[compare changes](https://github.com/arbicity/ARBI-frontend/compare/v0.3.40...HEAD)
 
-### 🚀 Enhancements
+### 🏡 Chore
 
-- **cli:** Add --json to list commands + agent-aware not-logged-in hint ([#629](https://github.com/arbicity/ARBI-frontend/pull/629))
+- Release v0.3.40 [skip ci] ([5e404545](https://github.com/arbicity/ARBI-frontend/commit/5e404545))
 
 ## v0.3.39
 

package/SKILL.md

@@ -76,3 +76,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.41";
 }
 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.41") 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.41"} \u2192 ${latest}). Updating...`);
       child_process.execSync("npm install -g @arbidocs/cli@latest", { stdio: "inherit" });
-      showChangelog("0.3.40", latest);
+      showChangelog("0.3.41", 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.41"} \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.41") {
       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.41"} \u2192 ${cached.latest}). Run "arbi update".`
       );
     }
   } catch {
@@ -4756,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)) {
@@ -4967,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(
@@ -5705,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.'
         );
@@ -6209,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) {
@@ -6235,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)`
       );
@@ -8258,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.40");
+program.name("arbi").description("ARBI CLI \u2014 interact with ARBI from the terminal").version("0.3.41");
 registerConfigCommand(program);
 registerLoginCommand(program);
 registerRegisterCommand(program);