@arbidocs/cli 0.3.39 → 0.3.40

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## v0.3.40
+
+[compare changes](https://github.com/arbicity/ARBI-frontend/compare/v0.3.39...HEAD)
+
+### 🚀 Enhancements
+
+- **cli:** Add --json to list commands + agent-aware not-logged-in hint ([#629](https://github.com/arbicity/ARBI-frontend/pull/629))
+
 ## 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,54 @@ 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`).

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.40";
 }
 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.40") 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.40"} \u2192 ${latest}). Updating...`);
       child_process.execSync("npm install -g @arbidocs/cli@latest", { stdio: "inherit" });
-      showChangelog("0.3.39", latest);
+      showChangelog("0.3.40", 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.40"} \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.40") {
       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.40"} \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;
@@ -6615,10 +6635,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 +6660,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 +6702,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 +6927,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 +7027,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 +7139,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 +7215,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 +7464,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 +7491,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 +7513,7 @@ Models (${data.models_health.application}):`);
         ],
         data.models
       );
-    })
+    })()
   );
 }
 function registerTuiCommand(program2) {
@@ -8031,7 +8082,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 +8258,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.40");
 registerConfigCommand(program);
 registerLoginCommand(program);
 registerRegisterCommand(program);