@docmana/sdk 0.4.0 → 0.8.0

package/dist/cli.mjs

@@ -1,14 +1,42 @@
 #!/usr/bin/env node
 
-// src/cli.ts
-import { existsSync, realpathSync } from "fs";
-import { mkdir, readFile as readFile2, rm, writeFile } from "fs/promises";
-import { dirname, resolve } from "path";
-import { createInterface } from "readline/promises";
+// src/cli/cli.ts
+import { realpathSync } from "fs";
+import { resolve as resolve2 } from "path";
 import { fileURLToPath } from "url";
 import { Command, CommanderError } from "commander";
 
-// src/errors.ts
+// src/sdk/config.ts
+var DEFAULTS = {
+  tokenEndpoint: "https://4fe70f5b-e013-4f65-9fa7-3109a33beba5.ciamlogin.com/4fe70f5b-e013-4f65-9fa7-3109a33beba5/oauth2/v2.0/token",
+  scope: "api://d781e6ba-cc08-4618-8099-ad968abd2b9e/.default",
+  timeoutMs: 3e5,
+  pollIntervalMs: 2e3,
+  pollMaxIntervalMs: 1e4
+};
+function resolveConfig(config) {
+  if (!config.apiBaseUrl) throw new Error("DocmanaConfig.apiBaseUrl is required");
+  if (!config.accessToken && !config.getAccessToken) {
+    throw new Error("DocmanaConfig.accessToken or DocmanaConfig.getAccessToken is required");
+  }
+  const apiBaseUrl = normalizeApiBaseUrl(config.apiBaseUrl);
+  return {
+    apiBaseUrl,
+    accessToken: config.accessToken,
+    getAccessToken: config.getAccessToken,
+    timeoutMs: config.timeoutMs ?? DEFAULTS.timeoutMs,
+    pollIntervalMs: config.pollIntervalMs ?? DEFAULTS.pollIntervalMs,
+    pollMaxIntervalMs: config.pollMaxIntervalMs ?? DEFAULTS.pollMaxIntervalMs,
+    fetchImpl: config.fetch ?? fetch,
+    headers: config.headers ?? {}
+  };
+}
+function normalizeApiBaseUrl(value) {
+  const trimmed = value.replace(/\/+$/, "");
+  return /\/v\d+$/i.test(trimmed) ? trimmed : `${trimmed}/v1`;
+}
+
+// src/sdk/errors.ts
 var DocmanaError = class extends Error {
   status;
   requestId;
@@ -86,117 +114,7 @@ function errorFromResponse(status, message, requestId, retryAfterMs) {
   }
 }
 
-// src/auth/token-manager.ts
-var SAFETY_MARGIN_MS = 6e4;
-var TokenManager = class {
-  constructor(opts) {
-    this.opts = opts;
-  }
-  opts;
-  token = null;
-  expiresAt = 0;
-  inflight = null;
-  invalidate() {
-    this.token = null;
-    this.expiresAt = 0;
-    void this.opts.tokenCache?.clear().catch(() => void 0);
-  }
-  async getToken() {
-    if (this.token && Date.now() < this.expiresAt) return this.token;
-    const cached = await this.readCachedToken();
-    if (cached) return cached;
-    if (this.inflight) return this.inflight;
-    this.inflight = this.acquire().finally(() => {
-      this.inflight = null;
-    });
-    return this.inflight;
-  }
-  async acquire() {
-    const body = new URLSearchParams({
-      grant_type: "client_credentials",
-      client_id: this.opts.clientId,
-      client_secret: this.opts.clientSecret,
-      scope: this.opts.scope
-    });
-    const res = await this.opts.fetchImpl(this.opts.tokenEndpoint, {
-      method: "POST",
-      headers: { "content-type": "application/x-www-form-urlencoded" },
-      body: body.toString()
-    });
-    if (!res.ok) {
-      throw new DocmanaAuthError("Failed to acquire Docmana access token", { status: res.status });
-    }
-    const json = await res.json();
-    if (typeof json.access_token !== "string" || json.access_token.length === 0 || typeof json.expires_in !== "number" || !Number.isFinite(json.expires_in)) {
-      throw new DocmanaAuthError("Malformed token response from Docmana CIAM", {
-        status: res.status
-      });
-    }
-    this.token = json.access_token;
-    this.expiresAt = Date.now() + json.expires_in * 1e3 - SAFETY_MARGIN_MS;
-    await this.writeCachedToken().catch(() => void 0);
-    return this.token;
-  }
-  async readCachedToken() {
-    if (!this.opts.tokenCache) return null;
-    let entry;
-    try {
-      entry = await this.opts.tokenCache.read();
-    } catch {
-      return null;
-    }
-    if (!entry) return null;
-    if (entry.clientId !== this.opts.clientId || entry.tokenEndpoint !== this.opts.tokenEndpoint || entry.scope !== this.opts.scope || Date.now() >= entry.expiresAt) {
-      await this.opts.tokenCache.clear().catch(() => void 0);
-      return null;
-    }
-    this.token = entry.accessToken;
-    this.expiresAt = entry.expiresAt;
-    return this.token;
-  }
-  async writeCachedToken() {
-    if (!this.opts.tokenCache || !this.token) return;
-    await this.opts.tokenCache.write({
-      accessToken: this.token,
-      expiresAt: this.expiresAt,
-      clientId: this.opts.clientId,
-      tokenEndpoint: this.opts.tokenEndpoint,
-      scope: this.opts.scope
-    });
-  }
-};
-
-// src/config.ts
-var DEFAULTS = {
-  tokenEndpoint: "https://4fe70f5b-e013-4f65-9fa7-3109a33beba5.ciamlogin.com/4fe70f5b-e013-4f65-9fa7-3109a33beba5/oauth2/v2.0/token",
-  scope: "api://d781e6ba-cc08-4618-8099-ad968abd2b9e/.default",
-  timeoutMs: 3e5,
-  pollIntervalMs: 2e3,
-  pollMaxIntervalMs: 1e4
-};
-function resolveConfig(config) {
-  if (!config.apiBaseUrl) throw new Error("DocmanaConfig.apiBaseUrl is required");
-  if (!config.accessToken && !config.getAccessToken) {
-    throw new Error("DocmanaConfig.accessToken or DocmanaConfig.getAccessToken is required");
-  }
-  const apiBaseUrl = normalizeApiBaseUrl(config.apiBaseUrl);
-  return {
-    apiBaseUrl,
-    accessToken: config.accessToken,
-    getAccessToken: config.getAccessToken,
-    timeoutMs: config.timeoutMs ?? DEFAULTS.timeoutMs,
-    pollIntervalMs: config.pollIntervalMs ?? DEFAULTS.pollIntervalMs,
-    pollMaxIntervalMs: config.pollMaxIntervalMs ?? DEFAULTS.pollMaxIntervalMs,
-    fetchImpl: config.fetch ?? fetch,
-    headers: config.headers ?? {}
-  };
-}
-function normalizeApiBaseUrl(value) {
-  const trimmed = value.replace(/\/+$/, "");
-  return /\/v\d+$/i.test(trimmed) ? trimmed : `${trimmed}/v1`;
-}
-
-// src/http/http-client.ts
+// src/sdk/http/http-client.ts
 var HttpClient = class {
   constructor(opts) {
     this.opts = opts;
@@ -212,6 +130,10 @@ var HttpClient = class {
       throw new DocmanaError("Invalid JSON response from Docmana", { status: res.status });
     }
   }
+  async requestBytes(method, path, options = {}) {
+    const res = await this.requestRaw(method, path, options);
+    return { bytes: new Uint8Array(await res.arrayBuffer()), headers: res.headers };
+  }
   async requestRaw(method, path, options = {}) {
     let res = await this.send(method, path, options);
     if (res.status === 401 && this.opts.getAccessToken) {
@@ -281,7 +203,7 @@ function parseRetryAfterMs(value) {
   return void 0;
 }
 
-// src/files/resolve-input.ts
+// src/sdk/files/resolve-input.ts
 import { readFile } from "fs/promises";
 import { basename } from "path";
 var CONTENT_TYPES = {
@@ -306,6 +228,11 @@ function isReadable(x) {
 function isPathInput(x) {
   return typeof x === "object" && x !== null && typeof x.path === "string";
 }
+function isNamedFileInput(x) {
+  if (typeof x !== "object" || x === null) return false;
+  const value = x;
+  return typeof value.filename === "string" && (value.data instanceof Uint8Array || isReadable(value.data));
+}
 async function streamToBuffer(stream) {
   const chunks = [];
   for await (const chunk of stream) chunks.push(Buffer.from(chunk));
@@ -314,38 +241,30 @@ async function streamToBuffer(stream) {
 function toBlobBytes(bytes) {
   return new Uint8Array(bytes);
 }
-async function resolveOne(input, fallbackName) {
+async function resolveOne(input) {
   if (typeof input === "string" || isPathInput(input)) {
     const path = typeof input === "string" ? input : input.path;
     const data = await readFile(path);
     const filename = basename(path);
     return { data: new Blob([toBlobBytes(data)]), filename, contentType: contentTypeFor(filename) };
   }
-  if (input instanceof Uint8Array) {
-    return {
-      data: new Blob([toBlobBytes(input)]),
-      filename: fallbackName,
-      contentType: contentTypeFor(fallbackName)
-    };
-  }
-  if (isReadable(input)) {
-    const buf = await streamToBuffer(input);
+  if (isNamedFileInput(input)) {
+    const bytes = input.data instanceof Uint8Array ? input.data : await streamToBuffer(input.data);
     return {
-      data: new Blob([toBlobBytes(buf)]),
-      filename: fallbackName,
-      contentType: contentTypeFor(fallbackName)
+      data: new Blob([toBlobBytes(bytes)]),
+      filename: input.filename,
+      contentType: input.contentType ?? contentTypeFor(input.filename)
     };
   }
   throw new Error("Unsupported file input type");
 }
 async function resolveInputs(input) {
-  const list = input.files ?? (input.file !== void 0 ? [input.file] : []);
-  if (list.length === 0) throw new Error("runFlow requires `file` or `files`");
-  const fallback = input.fileName ?? "upload.bin";
-  return Promise.all(list.map((item) => resolveOne(item, fallback)));
+  const list = input.files;
+  if (list.length === 0) throw new Error("runFlow requires `files`");
+  return Promise.all(list.map((item) => resolveOne(item)));
 }
 
-// src/api/run-flow.ts
+// src/sdk/api/run-flow.ts
 async function runFlow(http, flowId, parts, signal, useDraftVersion = false, context, callbackUrl, language) {
   const form = new FormData();
   for (const part of parts) {
@@ -362,7 +281,7 @@ async function runFlow(http, flowId, parts, signal, useDraftVersion = false, con
   );
 }
 
-// src/api/execution-status.ts
+// src/sdk/api/execution-status.ts
 async function getStatus(http, executionResultId, signal) {
   const res = await http.requestRaw("GET", `/executions/${executionResultId}/status`, { signal });
   const text = await res.text();
@@ -376,7 +295,7 @@ function parsePositiveInt(value) {
   return Number.isFinite(parsed) && parsed >= 0 ? parsed : void 0;
 }
 
-// src/api/execution-result.ts
+// src/sdk/api/execution-result.ts
 async function getResult(http, executionResultId, signal, language) {
   return http.requestJson("GET", `/executions/${executionResultId}/result`, {
     query: language ? { language } : void 0,
@@ -384,7 +303,119 @@ async function getResult(http, executionResultId, signal, language) {
   });
 }
 
-// src/polling/poll.ts
+// src/sdk/api/list-flows.ts
+async function listFlows(http) {
+  const flows = await http.requestJson("GET", "/flows");
+  return Array.isArray(flows) ? flows.map(toFlowListItem) : [];
+}
+function toFlowListItem(flow) {
+  const value = flow && typeof flow === "object" ? flow : {};
+  return {
+    id: toStringValue(value.id),
+    name: toStringValue(value.name),
+    state: toStateValue(value.state)
+  };
+}
+function toStringValue(value) {
+  return typeof value === "string" ? value : "";
+}
+function toStateValue(value) {
+  return typeof value === "string" && value.trim() ? value : "unknown";
+}
+
+// src/sdk/api/list-organizations.ts
+async function listOrganizations(http) {
+  const organizations = await http.requestJson("GET", "/organizations");
+  return Array.isArray(organizations) ? organizations.map(toAccessibleOrganization).filter(isAccessibleOrganization) : [];
+}
+function toAccessibleOrganization(organization) {
+  const value = organization && typeof organization === "object" ? organization : {};
+  const id = toStringValue2(value.id).trim();
+  if (!id) return void 0;
+  const name = toStringValue2(value.name).trim() || id;
+  return {
+    id,
+    name
+  };
+}
+function isAccessibleOrganization(organization) {
+  return organization !== void 0;
+}
+function toStringValue2(value) {
+  return typeof value === "string" ? value : "";
+}
+
+// src/sdk/api/flow-metadata.ts
+async function getFlowMetadata(http, flowId) {
+  return http.requestJson("GET", `/flows/${encodeURIComponent(flowId)}/metadata`);
+}
+
+// src/sdk/api/flow-definition.ts
+async function getFlowDefinition(http, flowId) {
+  return http.requestJson("GET", `/flows/${encodeURIComponent(flowId)}/definition`);
+}
+
+// src/sdk/api/organization-documents.ts
+async function listOrganizationDocuments(http, options = {}) {
+  const result = await http.requestJson("GET", "/organization-documents", {
+    query: options.prefix ? { prefix: options.prefix } : void 0
+  });
+  const value = result && typeof result === "object" ? result : {};
+  return {
+    configured: value.configured === true,
+    documents: Array.isArray(value.documents) ? value.documents.map(toOrganizationDocument).filter(isOrganizationDocument) : []
+  };
+}
+async function downloadOrganizationDocument(http, path) {
+  const result = await http.requestBytes("GET", "/organization-documents/download", {
+    query: { path }
+  });
+  return {
+    bytes: result.bytes,
+    filename: filenameFromHeaders(result.headers) ?? filenameFromPath(path),
+    contentType: result.headers.get("content-type") || void 0
+  };
+}
+async function downloadOrganizationDocuments(http, paths) {
+  return Promise.all(paths.map((path) => downloadOrganizationDocument(http, path)));
+}
+function toOrganizationDocument(document) {
+  const value = document && typeof document === "object" ? document : {};
+  const path = toStringValue3(value.path).trim();
+  if (!path) return void 0;
+  const contentType = toStringValue3(value.contentType).trim();
+  return {
+    path,
+    name: toStringValue3(value.name).trim() || filenameFromPath(path),
+    size: toNumberValue(value.size),
+    lastModified: toStringValue3(value.lastModified).trim(),
+    ...contentType ? { contentType } : {}
+  };
+}
+function isOrganizationDocument(document) {
+  return document !== void 0;
+}
+function filenameFromHeaders(headers) {
+  const disposition = headers.get("content-disposition");
+  if (!disposition) return void 0;
+  const utf8 = /filename\*=UTF-8''([^;]+)/i.exec(disposition);
+  if (utf8?.[1]) return decodeURIComponent(utf8[1]);
+  const quoted = /filename="([^"]+)"/i.exec(disposition);
+  if (quoted?.[1]) return quoted[1];
+  const plain = /filename=([^;]+)/i.exec(disposition);
+  return plain?.[1]?.trim();
+}
+function filenameFromPath(path) {
+  return path.replace(/\\/g, "/").split("/").filter(Boolean).pop() || path;
+}
+function toStringValue3(value) {
+  return typeof value === "string" ? value : "";
+}
+function toNumberValue(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+// src/sdk/polling/poll.ts
 var TERMINAL = /* @__PURE__ */ new Set(["Completed", "Failed"]);
 var defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
 async function pollUntilTerminal(opts) {
@@ -429,7 +460,7 @@ function fullJitterDelay(intervalMs, maxIntervalMs, attempt, random) {
   return Math.round(intervalMs + random() * (capDelay - intervalMs));
 }
 
-// src/client.ts
+// src/sdk/client.ts
 var Docmana = class {
   config;
   http;
@@ -443,30 +474,17 @@ var Docmana = class {
       headers: this.config.headers
     });
   }
-  async runFlowAsync(flowId, input) {
-    const parts = await resolveInputs(input);
-    return runFlow(
-      this.http,
-      flowId,
-      parts,
-      input.signal,
-      input.useDraftVersion ?? false,
-      input.context,
-      void 0,
-      input.language
-    );
-  }
-  async runFlowWithCallback(flowId, input) {
-    const parts = await resolveInputs(input);
+  async runFlowAsync(flowId, params, options = {}) {
+    const parts = await resolveInputs(params);
     return runFlow(
       this.http,
       flowId,
       parts,
-      input.signal,
-      input.useDraftVersion ?? false,
-      input.context,
-      input.callbackUrl,
-      input.language
+      options.signal,
+      params.useDraftVersion ?? false,
+      params.context,
+      params.callbackUrl,
+      params.language
     );
   }
   async getStatus(executionResultId, signal) {
@@ -475,18 +493,20 @@ var Docmana = class {
   async getResult(executionResultId, signal, language) {
     return getResult(this.http, executionResultId, signal, language);
   }
-  async runFlow(flowId, input) {
-    const { executionResultId } = await this.runFlowAsync(flowId, input);
+  async runFlow(flowId, params, options = {}) {
+    const { executionResultId } = await this.runFlowAsync(flowId, params, {
+      signal: options.signal
+    });
     let attempt = 0;
     const startedAt = Date.now();
     await pollUntilTerminal({
       check: async () => {
         attempt += 1;
         try {
-          const statusResult = await this.getStatus(executionResultId, input.signal);
+          const statusResult = await this.getStatus(executionResultId, options.signal);
           const status = statusResult.status;
           const nextPollAfterMs = this.isTerminalStatus(status) ? void 0 : statusResult.pollAfterMs;
-          input.onPoll?.({
+          options.onPoll?.({
             executionResultId,
             status,
             attempt,
@@ -496,22 +516,22 @@ var Docmana = class {
           return { status, nextDelayMs: nextPollAfterMs };
         } catch (err) {
           if (err instanceof DocmanaRateLimitError) {
-            input.onRateLimit?.({
+            options.onRateLimit?.({
               executionResultId,
               attempt,
               elapsedMs: Date.now() - startedAt,
-              retryAfterMs: err.retryAfterMs ?? input.pollIntervalMs ?? this.config.pollIntervalMs
+              retryAfterMs: err.retryAfterMs ?? options.pollIntervalMs ?? this.config.pollIntervalMs
             });
           }
           throw err;
         }
       },
-      intervalMs: input.pollIntervalMs ?? this.config.pollIntervalMs,
-      maxIntervalMs: input.pollMaxIntervalMs ?? this.config.pollMaxIntervalMs,
-      timeoutMs: input.timeoutMs ?? this.config.timeoutMs,
-      signal: input.signal
+      intervalMs: options.pollIntervalMs ?? this.config.pollIntervalMs,
+      maxIntervalMs: options.pollMaxIntervalMs ?? this.config.pollMaxIntervalMs,
+      timeoutMs: options.timeoutMs ?? this.config.timeoutMs,
+      signal: options.signal
     });
-    const result = await this.getResult(executionResultId, input.signal, input.language);
+    const result = await this.getResult(executionResultId, options.signal, params.language);
     if (result.status === "Failed") {
       throw new DocmanaExecutionError(
         `Flow ${flowId} execution failed`,
@@ -521,12 +541,33 @@ var Docmana = class {
     }
     return result;
   }
+  async listFlows() {
+    return listFlows(this.http);
+  }
+  async listOrganizations() {
+    return listOrganizations(this.http);
+  }
+  async getFlowMetadata(flowId) {
+    return getFlowMetadata(this.http, flowId);
+  }
+  async getFlowDefinition(flowId) {
+    return getFlowDefinition(this.http, flowId);
+  }
+  async listOrganizationDocuments(options = {}) {
+    return listOrganizationDocuments(this.http, options);
+  }
+  async downloadOrganizationDocument(path) {
+    return downloadOrganizationDocument(this.http, path);
+  }
+  async downloadOrganizationDocuments(paths) {
+    return downloadOrganizationDocuments(this.http, paths);
+  }
   isTerminalStatus(status) {
     return status === "Completed" || status === "Failed";
   }
 };
 
-// src/cli.ts
+// src/cli/errors.ts
 var CliUsageError = class extends Error {
   constructor(message) {
     super(message);
@@ -542,243 +583,212 @@ var CliSilentError = class extends Error {
     Object.setPrototypeOf(this, new.target.prototype);
   }
 };
-var HELP = {
-  root: "Run Docmana document-analysis flows.",
-  flow: "Manage and run Docmana flows.",
-  config: "Manage Docmana CLI configuration.",
-  configInit: "Create or update a local Docmana CLI config file.",
-  login: "Acquire and cache a Docmana OAuth2 access token.",
-  run: "Upload documents, run a Docmana flow, wait for completion, and print the result."
-};
-var DEFAULT_CONFIG_FILE = "docmana.config.json";
-var DEFAULT_TOKEN_CACHE_FILE = "docmana.token.json";
-async function runCli(argv = process.argv.slice(2), env = process.env, io = {
-  stdout: (text) => process.stdout.write(text),
-  stderr: (text) => process.stderr.write(text)
-}, clientFactory = (config) => new Docmana(config), deps = {}) {
-  const program = buildProgram(env, io, clientFactory, deps);
-  if (argv.length === 0) {
-    io.stdout(program.helpInformation());
-    return 0;
+
+// src/cli/formatting.ts
+function formatFlowList(flows) {
+  if (flows.length === 0) return "No flows found.\n";
+  const lines = ["Docmana flows"];
+  for (const flow of flows) {
+    const id = flow.id || "(no id)";
+    const name = flow.name || "(no name)";
+    const state = flow.state ? ` [${flow.state}]` : "";
+    lines.push(`- ${id} - ${name}${state}`);
   }
-  try {
-    await program.parseAsync(argv, { from: "user" });
-    return 0;
-  } catch (err) {
-    if (err instanceof CliSilentError) {
-      return err.exitCode;
-    }
-    if (err instanceof CliUsageError) {
-      io.stderr(`Error: ${err.message}
-`);
-      return 2;
-    }
-    if (err instanceof CommanderError) {
-      return err.exitCode === 0 ? 0 : 2;
-    }
-    io.stderr(`${formatRuntimeError(err)}
-`);
-    return 1;
+  return `${lines.join("\n")}
+`;
+}
+function formatOrganizationList(organizations) {
+  if (organizations.length === 0) return "No organizations found.\n";
+  const lines = ["Docmana organizations"];
+  for (const organization of organizations) {
+    const id = organization.id || "(no id)";
+    const name = organization.name || "(no name)";
+    lines.push(`- ${id} - ${name}`);
   }
+  return `${lines.join("\n")}
+`;
 }
-function buildProgram(env, io, clientFactory, deps) {
-  const program = new Command();
-  program.name("docmana").description(HELP.root).showHelpAfterError().configureOutput({
-    writeOut: io.stdout,
-    writeErr: io.stderr,
-    outputError: (str, write) => write(str)
-  }).exitOverride();
-  program.command("login").description(HELP.login).option("--client-id <id>", "OAuth2 client id; defaults to DOCMANA_CLIENT_ID").option("--client-secret <secret>", "OAuth2 client secret; defaults to DOCMANA_CLIENT_SECRET").option("--token-url <url>", "OAuth2 token endpoint; defaults to DOCMANA_TOKEN_URL").option("--scope <scope>", "OAuth2 scope; defaults to DOCMANA_SCOPE").option("--config <path>", `Config file path; defaults to ./${DEFAULT_CONFIG_FILE}`).option("--token-cache <path>", `Token cache path; defaults to ./${DEFAULT_TOKEN_CACHE_FILE}`).action(async (options) => {
-    await loginCommand(options, env, io, deps);
-  });
-  const flow = program.command("flow").description(HELP.flow).action(() => {
-    io.stdout(flow.helpInformation());
-  });
-  flow.command("run").description(HELP.run).argument("<flow-id>", "Docmana flow id").requiredOption("--files <csv>", "Comma-separated file paths to upload").option("--api-url <url>", "Consumer API base URL; defaults to DOCMANA_API_URL").option("--access-token <token>", "Bearer token; defaults to DOCMANA_ACCESS_TOKEN").option("--config <path>", `Config file path; defaults to ./${DEFAULT_CONFIG_FILE}`).option("--token-cache <path>", `Token cache path; defaults to ./${DEFAULT_TOKEN_CACHE_FILE}`).option("--json", "Print the raw JSON result").option("--language <lang>", "Translate output to specified language").option("--draft", "Run the current draft flow version").action(async (flowId, options) => {
-    await runFlowCommand(flowId, options, env, io, clientFactory, deps);
-  });
-  const config = program.command("config").description(HELP.config).action(() => {
-    io.stdout(config.helpInformation());
-  });
-  config.command("init").description(HELP.configInit).option("--config <path>", `Config file path; defaults to ./${DEFAULT_CONFIG_FILE}`).action(async (options) => {
-    await configInitCommand(options, io, deps);
-  });
-  return program;
+function formatOrganizationDocumentList(documents) {
+  if (documents.length === 0) return "No organization documents found.\n";
+  const lines = ["Docmana organization documents"];
+  for (const document of documents) {
+    const contentType = document.contentType ? ` [${document.contentType}]` : "";
+    lines.push(`- ${document.path} - ${document.name} (${document.size} bytes)${contentType}`);
+  }
+  return `${lines.join("\n")}
+`;
 }
-async function runFlowCommand(flowId, options, env, io, clientFactory, deps) {
-  try {
-    const files = parseFiles(options.files);
-    const cliConfig = await loadCliConfig(options.config, getCwd(deps), Boolean(options.config));
-    const apiBaseUrl = firstNonEmpty(options.apiUrl, env.DOCMANA_API_URL, cliConfig.apiBaseUrl);
-    if (!apiBaseUrl) {
-      throw new CliUsageError("Missing API base URL. Use --api-url or DOCMANA_API_URL.");
+function formatHumanResult(result) {
+  const lines = ["Docmana flow completed", `Status: ${String(result.status ?? "Unknown")}`];
+  const executionId = result.executionId;
+  if (executionId) lines.push(`Execution id: ${String(executionId)}`);
+  if (result.documents && result.documents.mappings) {
+    lines.push(`Results: ${result.documents.mappings.length}`);
+  }
+  if (result.errors && result.errors.length > 0) {
+    lines.push(`Errors: ${result.errors.length}`);
+  }
+  const previewData = {};
+  if (result.documents && result.documents.mappings) {
+    for (const mapping of result.documents.mappings.slice(0, 3)) {
+      const docKey = mapping.reference;
+      previewData[mapping.name] = result.documents[docKey];
     }
-    const tokenCache = createFileTokenCache(
-      resolveTokenCachePath(options.tokenCache, getCwd(deps))
-    );
-    const accessToken = firstNonEmpty(options.accessToken, env.DOCMANA_ACCESS_TOKEN) ?? await resolveFlowAccessToken(env, cliConfig, tokenCache, deps, io);
-    const client = clientFactory({
-      apiBaseUrl,
-      accessToken
-    });
-    const result = await client.runFlow(flowId, {
-      files: files.map((path) => ({ path })),
-      language: options.language,
-      useDraftVersion: options.draft === true,
-      onPoll: (event) => {
-        const nextPoll = event.nextPollAfterMs === void 0 ? "" : `, next poll in ${formatElapsedSeconds(event.nextPollAfterMs)}`;
-        io.stderr(
-          `Polling execution ${event.executionResultId}: ${event.status} (attempt ${event.attempt}, elapsed ${formatElapsedSeconds(event.elapsedMs)}${nextPoll})
-`
-        );
-      },
-      onRateLimit: (event) => {
-        io.stderr(
-          `Polling execution ${event.executionResultId}: rate limited (attempt ${event.attempt}, retrying in ${formatElapsedSeconds(event.retryAfterMs)})
-`
-        );
+  }
+  const preview = formatResultsPreview(previewData);
+  if (preview) lines.push("", "Result preview:", preview);
+  lines.push("", "Use --json to print the complete result payload.");
+  return `${lines.join("\n")}
+`;
+}
+function formatRuntimeError(err) {
+  return formatHumanError(err);
+}
+function formatHumanError(err) {
+  if (err instanceof DocmanaExecutionError) {
+    const lines = [`Error: ${err.message}`];
+    if (err.errors && err.errors.length > 0) {
+      lines.push("Global errors:");
+      for (const e of err.errors) {
+        lines.push(`  - ${formatSingleError(e)}`);
       }
-    });
-    if (options.json) {
-      io.stdout(`${JSON.stringify(result, null, 2)}
-`);
-      return;
     }
-    io.stdout(formatHumanResult(result));
-  } catch (err) {
-    if (options.json) {
-      if (err instanceof DocmanaExecutionError && err.result) {
-        io.stdout(`${JSON.stringify(err.result, null, 2)}
-`);
-      } else {
-        const errorPayload = {
-          error: err instanceof Error ? err.message : String(err)
-        };
-        if (err instanceof DocmanaError) {
-          errorPayload.code = err.code;
-          if (err.status !== void 0) errorPayload.status = err.status;
-          if (err.requestId !== void 0) errorPayload.requestId = err.requestId;
+    const result = err.result;
+    if (result?.documents?.mappings && result.documents.mappings.length > 0) {
+      lines.push("Document execution results:");
+      for (const mapping of result.documents.mappings) {
+        const docKey = mapping.reference;
+        const docName = mapping.name;
+        const docResult = result.documents[docKey];
+        if (!docResult) {
+          lines.push(`  - Document: ${docName} (Status: Unknown)`);
+          continue;
+        }
+        const status = docResult.status || "Unknown";
+        const nodes = [];
+        if (docResult.classifications) nodes.push(...Object.values(docResult.classifications));
+        if (docResult.metadataExtraction) nodes.push(docResult.metadataExtraction);
+        if (docResult.extractions) nodes.push(...Object.values(docResult.extractions));
+        if (docResult.validations) nodes.push(...Object.values(docResult.validations));
+        const hasNodeFailures = nodes.some(
+          (n) => n.status === "Failed" || n.errors && n.errors.length > 0
+        );
+        lines.push(`  - Document: ${docName} (Status: ${status})`);
+        if (docResult.status !== "Failed" && !hasNodeFailures) continue;
+        if (docResult.classifications) {
+          for (const [nodeName, node] of Object.entries(docResult.classifications)) {
+            if (node.errors && node.errors.length > 0) {
+              lines.push(`    Classification: ${nodeName} (Status: ${node.status})`);
+              for (const nodeErr of node.errors) lines.push(`      - ${nodeErr}`);
+            }
+          }
+        }
+        if (docResult.metadataExtraction?.errors?.length) {
+          lines.push(`    MetadataExtraction: (Status: ${docResult.metadataExtraction.status})`);
+          for (const nodeErr of docResult.metadataExtraction.errors) {
+            lines.push(`      - ${nodeErr}`);
+          }
+        }
+        if (docResult.extractions) {
+          for (const [nodeName, node] of Object.entries(docResult.extractions)) {
+            if (node.status === "Failed" || node.errors && node.errors.length > 0) {
+              lines.push(`    Extraction: ${nodeName} (Status: ${node.status})`);
+              if (node.errors) {
+                for (const nodeErr of node.errors) lines.push(`      - ${nodeErr}`);
+              }
+            }
+          }
+        }
+        if (docResult.validations) {
+          for (const [nodeName, node] of Object.entries(docResult.validations)) {
+            if (node.status === "Failed" || node.errors && node.errors.length > 0) {
+              lines.push(`    Validation: ${nodeName} (Status: ${node.status})`);
+              if (node.errors) {
+                for (const nodeErr of node.errors) lines.push(`      - ${nodeErr}`);
+              }
+            }
+          }
         }
-        io.stdout(`${JSON.stringify(errorPayload, null, 2)}
-`);
       }
-      throw new CliSilentError(err instanceof CliUsageError ? 2 : 1);
     }
-    throw err;
+    return lines.join("\n");
   }
-}
-async function resolveFlowAccessToken(env, cliConfig, tokenCache, deps, io) {
-  const cached = await readFreshCachedToken(tokenCache);
-  if (cached) return cached;
-  const clientId = firstNonEmpty(env.DOCMANA_CLIENT_ID, cliConfig.clientId);
-  const clientSecret = firstNonEmpty(env.DOCMANA_CLIENT_SECRET, cliConfig.clientSecret);
-  if (!clientId || !clientSecret) {
-    throw new CliUsageError(
-      "Missing access token. Use --access-token, DOCMANA_ACCESS_TOKEN, docmana login, or configure OAuth credentials."
-    );
+  if (err instanceof DocmanaError) {
+    return `Error: ${err.message} (Code: ${err.code})`;
   }
-  const tokenManager = new TokenManager({
-    clientId,
-    clientSecret,
-    tokenEndpoint: firstNonEmpty(env.DOCMANA_TOKEN_URL, cliConfig.tokenEndpoint) ?? DEFAULTS.tokenEndpoint,
-    scope: firstNonEmpty(env.DOCMANA_SCOPE, cliConfig.scope) ?? DEFAULTS.scope,
-    fetchImpl: deps.fetch ?? fetch,
-    tokenCache
-  });
-  const token = await tokenManager.getToken();
-  io.stderr("Generated new access token and updated the token cache.\n");
-  return token;
+  if (err instanceof Error) {
+    return `Error: ${err.message}`;
+  }
+  return `Error: ${String(err)}`;
 }
-async function readFreshCachedToken(tokenCache) {
-  const cached = await tokenCache.read().catch(() => null);
-  if (!cached || Date.now() >= cached.expiresAt) return void 0;
-  return cached.accessToken;
+function formatResultsPreview(results) {
+  if (!results) return void 0;
+  const preview = JSON.stringify(results, null, 2);
+  if (!preview) return void 0;
+  return preview.length > 2e3 ? `${preview.slice(0, 2e3)}
+...` : preview;
 }
-async function loginCommand(options, env, io, deps) {
-  const auth = await resolveAuthConfig(options, env, deps);
-  const tokenCachePath = resolveTokenCachePath(options.tokenCache, getCwd(deps));
-  const tokenCache = createFileTokenCache(tokenCachePath);
-  const hadFreshCachedToken = Boolean(await readFreshCachedToken(tokenCache));
-  const tokenManager = new TokenManager({
-    clientId: auth.clientId,
-    clientSecret: auth.clientSecret,
-    tokenEndpoint: auth.tokenEndpoint,
-    scope: auth.scope,
-    fetchImpl: deps.fetch ?? fetch,
-    tokenCache
-  });
-  await tokenManager.getToken();
-  const cached = await tokenCache.read();
-  if (!hadFreshCachedToken) {
-    io.stdout("Generated new access token and updated the token cache.\n");
+function formatSingleError(e) {
+  if (typeof e === "string") return e;
+  if (e && typeof e === "object") {
+    const obj = e;
+    if (typeof obj.msg === "string") return obj.msg;
+    if (typeof obj.message === "string") return obj.message;
+    if (typeof obj.error === "string") return obj.error;
+    try {
+      return JSON.stringify(e);
+    } catch {
+      return String(e);
+    }
   }
-  io.stdout(`Logged in. Token cached at ${tokenCachePath}
-`);
-  if (cached) io.stdout(formatTokenExpiry(cached.expiresAt));
+  return String(e);
 }
-function formatTokenExpiry(expiresAt) {
-  const expiresAtDate = new Date(expiresAt);
-  return [
-    `Token expires at local time ${expiresAtDate.toLocaleString()}`,
-    `Token expires at UTC ${expiresAtDate.toISOString()}`
-  ].join("\n") + "\n";
+
+// src/cli/types.ts
+var DEFAULT_CONFIG_FILE = "docmana.config.json";
+var DEFAULT_TOKEN_CACHE_FILE = "docmana.token.json";
+var HELP = {
+  root: "Run Docmana document-analysis flows.",
+  flow: "Manage and run Docmana flows.",
+  organization: "Manage Docmana organizations.",
+  organizationDocument: "Manage organization documents.",
+  config: "Manage Docmana CLI configuration.",
+  configInit: "Create or update a local Docmana CLI config file.",
+  login: "Acquire and cache a Docmana OAuth2 access token.",
+  run: "Upload documents, run a Docmana flow, wait for completion, and print the result.",
+  list: "List Docmana flows available to the Bearer token.",
+  metadata: "Print Docmana flow runtime metadata as JSON.",
+  definition: "Print Docmana flow definition as JSON.",
+  organizationList: "List Docmana organizations available to the Bearer token.",
+  organizationDocumentList: "List organization documents available to the Bearer token.",
+  organizationDocumentDownload: "Download an organization document."
+};
+
+// src/cli/config-store.ts
+import { existsSync } from "fs";
+import { mkdir, readFile as readFile2, rm, writeFile } from "fs/promises";
+import { dirname, resolve } from "path";
+import { createInterface } from "readline/promises";
+
+// src/cli/utils.ts
+function getCwd(deps) {
+  return deps.cwd ?? process.cwd();
 }
-async function resolveAuthConfig(options, env, deps) {
-  const cliConfig = await loadCliConfig(options.config, getCwd(deps), Boolean(options.config));
-  const clientId = firstNonEmpty(options.clientId, env.DOCMANA_CLIENT_ID, cliConfig.clientId);
-  const clientSecret = firstNonEmpty(
-    options.clientSecret,
-    env.DOCMANA_CLIENT_SECRET,
-    cliConfig.clientSecret
-  );
-  const tokenEndpoint = firstNonEmpty(options.tokenUrl, env.DOCMANA_TOKEN_URL, cliConfig.tokenEndpoint) ?? DEFAULTS.tokenEndpoint;
-  const scope = firstNonEmpty(options.scope, env.DOCMANA_SCOPE, cliConfig.scope) ?? DEFAULTS.scope;
-  if (!clientId)
-    throw new CliUsageError("Missing client id. Use --client-id or DOCMANA_CLIENT_ID.");
-  if (!clientSecret) {
-    throw new CliUsageError("Missing client secret. Use --client-secret or DOCMANA_CLIENT_SECRET.");
-  }
-  return { clientId, clientSecret, tokenEndpoint, scope };
+function firstNonEmpty(...values) {
+  return values.map((value) => value?.trim()).find(Boolean);
 }
-async function configInitCommand(options, io, deps) {
-  const cwd = getCwd(deps);
-  const configPath = resolveConfigPath(options.config, cwd);
-  const existing = await loadCliConfig(options.config, cwd, false);
-  const defaultPrompt = deps.prompt ? void 0 : createDefaultPrompt();
-  const prompt = deps.prompt ?? defaultPrompt?.prompt;
-  if (!prompt) throw new CliUsageError("Unable to initialize interactive prompt");
-  try {
-    const config = {
-      apiBaseUrl: await prompt("API base URL", {
-        defaultValue: existing.apiBaseUrl
-      }),
-      tokenEndpoint: await prompt("OAuth2 token endpoint", {
-        defaultValue: existing.tokenEndpoint ?? DEFAULTS.tokenEndpoint
-      }),
-      scope: await prompt("OAuth2 scope", {
-        defaultValue: existing.scope ?? DEFAULTS.scope
-      }),
-      clientId: await prompt("Client id", {
-        defaultValue: existing.clientId
-      }),
-      clientSecret: await prompt("Client secret", {
-        defaultValue: existing.clientSecret,
-        secret: true
-      })
-    };
-    await mkdir(dirname(configPath), { recursive: true });
-    await writeFile(configPath, `${JSON.stringify(config, null, 2)}
-`, "utf8");
-    io.stdout(`Wrote ${configPath}
-`);
-    io.stdout(
-      `Warning: ${DEFAULT_CONFIG_FILE} contains credentials and should stay ignored by Git.
-`
-    );
-  } finally {
-    defaultPrompt?.close();
+function parseFiles(filesCsv) {
+  const files = filesCsv?.split(",").map((file) => file.trim()).filter(Boolean) ?? [];
+  if (files.length === 0) {
+    throw new CliUsageError("Missing files. Use --files <path[,path]>.");
   }
+  return files;
 }
+function formatElapsedSeconds(elapsedMs) {
+  return `${Math.floor(elapsedMs / 1e3)}s`;
+}
+
+// src/cli/config-store.ts
 async function loadCliConfig(configPathOption, cwd, requireExisting) {
   const configPath = resolveConfigPath(configPathOption, cwd);
   if (!existsSync(configPath)) {
@@ -810,18 +820,12 @@ function normalizeCliConfig(config) {
     clientSecret: stringValue(config.clientSecret)
   };
 }
-function stringValue(value) {
-  return typeof value === "string" && value.trim() ? value : void 0;
-}
 function resolveConfigPath(configPathOption, cwd) {
   return resolve(cwd, configPathOption ?? DEFAULT_CONFIG_FILE);
 }
 function resolveTokenCachePath(tokenCachePathOption, cwd) {
   return resolve(cwd, tokenCachePathOption ?? DEFAULT_TOKEN_CACHE_FILE);
 }
-function getCwd(deps) {
-  return deps.cwd ?? process.cwd();
-}
 function createFileTokenCache(path) {
   return {
     async read() {
@@ -854,6 +858,11 @@ function createFileTokenCache(path) {
     }
   };
 }
+async function writeCliConfig(configPath, config) {
+  await mkdir(dirname(configPath), { recursive: true });
+  await writeFile(configPath, `${JSON.stringify(config, null, 2)}
+`, "utf8");
+}
 function createDefaultPrompt() {
   if (!process.stdin.isTTY) {
     let index = 0;
@@ -877,169 +886,527 @@ function createDefaultPrompt() {
     close: () => rl.close()
   };
 }
+function stringValue(value) {
+  return typeof value === "string" && value.trim() ? value : void 0;
+}
 function formatPrompt(label, options) {
   const defaultHint = options.defaultValue && !options.secret ? ` [${options.defaultValue}]` : options.defaultValue && options.secret ? " [current value hidden]" : "";
   return `${label}${defaultHint}: `;
 }
-function formatElapsedSeconds(elapsedMs) {
-  return `${Math.floor(elapsedMs / 1e3)}s`;
-}
 async function readStdinLines() {
   let input = "";
   for await (const chunk of process.stdin) input += String(chunk);
   return input.split(/\r?\n/);
 }
-function parseFiles(filesCsv) {
-  const files = filesCsv?.split(",").map((file) => file.trim()).filter(Boolean) ?? [];
-  if (files.length === 0) throw new CliUsageError("Missing files. Use --files <path[,path]>.");
-  return files;
+
+// src/cli/commands/config-init.ts
+async function configInitCommand(options, io, deps) {
+  const cwd = getCwd(deps);
+  const configPath = resolveConfigPath(options.config, cwd);
+  const existing = await loadCliConfig(options.config, cwd, false);
+  const defaultPrompt = deps.prompt ? void 0 : createDefaultPrompt();
+  const prompt = deps.prompt ?? defaultPrompt?.prompt;
+  if (!prompt) throw new CliUsageError("Unable to initialize interactive prompt");
+  try {
+    const config = {
+      apiBaseUrl: await prompt("API base URL", {
+        defaultValue: existing.apiBaseUrl
+      }),
+      tokenEndpoint: await prompt("OAuth2 token endpoint", {
+        defaultValue: existing.tokenEndpoint ?? DEFAULTS.tokenEndpoint
+      }),
+      scope: await prompt("OAuth2 scope", {
+        defaultValue: existing.scope ?? DEFAULTS.scope
+      }),
+      clientId: await prompt("Client id", {
+        defaultValue: existing.clientId
+      }),
+      clientSecret: await prompt("Client secret", {
+        defaultValue: existing.clientSecret,
+        secret: true
+      })
+    };
+    await writeCliConfig(configPath, config);
+    io.stdout(`Wrote ${configPath}
+`);
+    io.stdout(
+      `Warning: ${DEFAULT_CONFIG_FILE} contains credentials and should stay ignored by Git.
+`
+    );
+  } finally {
+    defaultPrompt?.close();
+  }
 }
-function firstNonEmpty(...values) {
-  return values.map((value) => value?.trim()).find(Boolean);
+
+// src/cli/auth/token-manager.ts
+var SAFETY_MARGIN_MS = 6e4;
+var TokenManager = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  opts;
+  token = null;
+  expiresAt = 0;
+  inflight = null;
+  invalidate() {
+    this.token = null;
+    this.expiresAt = 0;
+    void this.opts.tokenCache?.clear().catch(() => void 0);
+  }
+  async getToken() {
+    if (this.token && Date.now() < this.expiresAt) return this.token;
+    const cached = await this.readCachedToken();
+    if (cached) return cached;
+    if (this.inflight) return this.inflight;
+    this.inflight = this.acquire().finally(() => {
+      this.inflight = null;
+    });
+    return this.inflight;
+  }
+  async acquire() {
+    const body = new URLSearchParams({
+      grant_type: "client_credentials",
+      client_id: this.opts.clientId,
+      client_secret: this.opts.clientSecret,
+      scope: this.opts.scope
+    });
+    const res = await this.opts.fetchImpl(this.opts.tokenEndpoint, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: body.toString()
+    });
+    if (!res.ok) {
+      throw new DocmanaAuthError("Failed to acquire Docmana access token", { status: res.status });
+    }
+    const json = await res.json();
+    if (typeof json.access_token !== "string" || json.access_token.length === 0 || typeof json.expires_in !== "number" || !Number.isFinite(json.expires_in)) {
+      throw new DocmanaAuthError("Malformed token response from Docmana CIAM", {
+        status: res.status
+      });
+    }
+    this.token = json.access_token;
+    this.expiresAt = Date.now() + json.expires_in * 1e3 - SAFETY_MARGIN_MS;
+    await this.writeCachedToken().catch(() => void 0);
+    return this.token;
+  }
+  async readCachedToken() {
+    if (!this.opts.tokenCache) return null;
+    let entry;
+    try {
+      entry = await this.opts.tokenCache.read();
+    } catch {
+      return null;
+    }
+    if (!entry) return null;
+    if (entry.clientId !== this.opts.clientId || entry.tokenEndpoint !== this.opts.tokenEndpoint || entry.scope !== this.opts.scope || Date.now() >= entry.expiresAt) {
+      await this.opts.tokenCache.clear().catch(() => void 0);
+      return null;
+    }
+    this.token = entry.accessToken;
+    this.expiresAt = entry.expiresAt;
+    return this.token;
+  }
+  async writeCachedToken() {
+    if (!this.opts.tokenCache || !this.token) return;
+    await this.opts.tokenCache.write({
+      accessToken: this.token,
+      expiresAt: this.expiresAt,
+      clientId: this.opts.clientId,
+      tokenEndpoint: this.opts.tokenEndpoint,
+      scope: this.opts.scope
+    });
+  }
+};
+
+// src/cli/auth/access-token.ts
+async function resolveFlowAccessToken(env, cliConfig, tokenCache, deps, io) {
+  const cached = await readFreshCachedToken(tokenCache);
+  if (cached) return cached;
+  const clientId = firstNonEmpty(env.DOCMANA_CLIENT_ID, cliConfig.clientId);
+  const clientSecret = firstNonEmpty(env.DOCMANA_CLIENT_SECRET, cliConfig.clientSecret);
+  if (!clientId || !clientSecret) {
+    throw new CliUsageError(
+      "Missing access token. Use --access-token, DOCMANA_ACCESS_TOKEN, docmana login, or configure OAuth credentials."
+    );
+  }
+  const tokenManager = new TokenManager({
+    clientId,
+    clientSecret,
+    tokenEndpoint: firstNonEmpty(env.DOCMANA_TOKEN_URL, cliConfig.tokenEndpoint) ?? DEFAULTS.tokenEndpoint,
+    scope: firstNonEmpty(env.DOCMANA_SCOPE, cliConfig.scope) ?? DEFAULTS.scope,
+    fetchImpl: deps.fetch ?? fetch,
+    tokenCache
+  });
+  const token = await tokenManager.getToken();
+  io.stderr("Generated new access token and updated the token cache.\n");
+  return token;
 }
-function formatHumanResult(result) {
-  const lines = ["Docmana flow completed", `Status: ${String(result.status ?? "Unknown")}`];
-  const executionId = result.executionId;
-  if (executionId) lines.push(`Execution id: ${String(executionId)}`);
-  if (result.documents && result.documents.mappings) {
-    lines.push(`Results: ${result.documents.mappings.length}`);
+async function readFreshCachedToken(tokenCache) {
+  const cached = await tokenCache.read().catch(() => null);
+  if (!cached || Date.now() >= cached.expiresAt) return void 0;
+  return cached.accessToken;
+}
+async function resolveAuthConfig(options, env, deps) {
+  const cliConfig = await loadCliConfig(options.config, getCwd(deps), Boolean(options.config));
+  const clientId = firstNonEmpty(options.clientId, env.DOCMANA_CLIENT_ID, cliConfig.clientId);
+  const clientSecret = firstNonEmpty(
+    options.clientSecret,
+    env.DOCMANA_CLIENT_SECRET,
+    cliConfig.clientSecret
+  );
+  const tokenEndpoint = firstNonEmpty(options.tokenUrl, env.DOCMANA_TOKEN_URL, cliConfig.tokenEndpoint) ?? DEFAULTS.tokenEndpoint;
+  const scope = firstNonEmpty(options.scope, env.DOCMANA_SCOPE, cliConfig.scope) ?? DEFAULTS.scope;
+  if (!clientId) {
+    throw new CliUsageError("Missing client id. Use --client-id or DOCMANA_CLIENT_ID.");
   }
-  if (result.errors && result.errors.length > 0) {
-    lines.push(`Errors: ${result.errors.length}`);
+  if (!clientSecret) {
+    throw new CliUsageError("Missing client secret. Use --client-secret or DOCMANA_CLIENT_SECRET.");
   }
-  const previewData = {};
-  if (result.documents && result.documents.mappings) {
-    for (const mapping of result.documents.mappings.slice(0, 3)) {
-      const docKey = mapping.reference;
-      previewData[mapping.name] = result.documents[docKey];
+  return { clientId, clientSecret, tokenEndpoint, scope };
+}
+
+// src/cli/commands/api-client.ts
+async function resolveApiClient(options, env, io, clientFactory, deps) {
+  const cliConfig = await loadCliConfig(options.config, getCwd(deps), Boolean(options.config));
+  const apiBaseUrl = firstNonEmpty(options.apiUrl, env.DOCMANA_API_URL, cliConfig.apiBaseUrl);
+  if (!apiBaseUrl) {
+    throw new CliUsageError("Missing API base URL. Use --api-url or DOCMANA_API_URL.");
+  }
+  const tokenCache = createFileTokenCache(resolveTokenCachePath(options.tokenCache, getCwd(deps)));
+  const accessToken = firstNonEmpty(options.accessToken, env.DOCMANA_ACCESS_TOKEN) ?? await resolveFlowAccessToken(env, cliConfig, tokenCache, deps, io);
+  return clientFactory({ apiBaseUrl, accessToken });
+}
+
+// src/cli/commands/flow-definition.ts
+async function flowDefinitionCommand(flowId, options, env, io, clientFactory, deps) {
+  try {
+    const client = await resolveApiClient(options, env, io, clientFactory, deps);
+    const definition = await client.getFlowDefinition(flowId);
+    io.stdout(`${JSON.stringify(definition, null, 2)}
+`);
+  } catch (err) {
+    const errorPayload = {
+      error: err instanceof Error ? err.message : String(err)
+    };
+    if (err instanceof DocmanaError) {
+      errorPayload.code = err.code;
+      if (err.status !== void 0) errorPayload.status = err.status;
+      if (err.requestId !== void 0) errorPayload.requestId = err.requestId;
     }
+    io.stdout(`${JSON.stringify(errorPayload, null, 2)}
+`);
+    throw new CliSilentError(err instanceof CliUsageError ? 2 : 1);
   }
-  const preview = formatResultsPreview(previewData);
-  if (preview) lines.push("", "Result preview:", preview);
-  lines.push("", "Use --json to print the complete result payload.");
-  return `${lines.join("\n")}
-`;
 }
-function formatResultsPreview(results) {
-  if (!results) return void 0;
-  const preview = JSON.stringify(results, null, 2);
-  if (!preview) return void 0;
-  return preview.length > 2e3 ? `${preview.slice(0, 2e3)}
-...` : preview;
+
+// src/cli/commands/flow-list.ts
+async function listFlowsCommand(options, env, io, clientFactory, deps) {
+  try {
+    const client = await resolveApiClient(options, env, io, clientFactory, deps);
+    const flows = await client.listFlows();
+    if (options.json) {
+      io.stdout(`${JSON.stringify(flows, null, 2)}
+`);
+      return;
+    }
+    io.stdout(formatFlowList(flows));
+  } catch (err) {
+    if (options.json) {
+      const errorPayload = {
+        error: err instanceof Error ? err.message : String(err)
+      };
+      if (err instanceof DocmanaError) {
+        errorPayload.code = err.code;
+        if (err.status !== void 0) errorPayload.status = err.status;
+        if (err.requestId !== void 0) errorPayload.requestId = err.requestId;
+      }
+      io.stdout(`${JSON.stringify(errorPayload, null, 2)}
+`);
+      throw new CliSilentError(err instanceof CliUsageError ? 2 : 1);
+    }
+    throw err;
+  }
 }
-function formatRuntimeError(err) {
-  return formatHumanError(err);
+
+// src/cli/commands/flow-metadata.ts
+async function flowMetadataCommand(flowId, options, env, io, clientFactory, deps) {
+  try {
+    const client = await resolveApiClient(options, env, io, clientFactory, deps);
+    const metadata = await client.getFlowMetadata(flowId);
+    io.stdout(`${JSON.stringify(metadata, null, 2)}
+`);
+  } catch (err) {
+    const errorPayload = {
+      error: err instanceof Error ? err.message : String(err)
+    };
+    if (err instanceof DocmanaError) {
+      errorPayload.code = err.code;
+      if (err.status !== void 0) errorPayload.status = err.status;
+      if (err.requestId !== void 0) errorPayload.requestId = err.requestId;
+    }
+    io.stdout(`${JSON.stringify(errorPayload, null, 2)}
+`);
+    throw new CliSilentError(err instanceof CliUsageError ? 2 : 1);
+  }
 }
-function formatHumanError(err) {
-  if (err instanceof DocmanaExecutionError) {
-    const lines = [`Error: ${err.message}`];
-    if (err.errors && err.errors.length > 0) {
-      lines.push("Global errors:");
-      for (const e of err.errors) {
-        lines.push(`  - ${formatSingleError(e)}`);
+
+// src/cli/commands/organization-document-download.ts
+import { mkdir as mkdir2, writeFile as writeFile2 } from "fs/promises";
+import { dirname as dirname2, join } from "path";
+async function organizationDocumentDownloadCommand(path, options, env, io, clientFactory, deps) {
+  try {
+    const client = await resolveApiClient(options, env, io, clientFactory, deps);
+    const document = await client.downloadOrganizationDocument(path);
+    const outputPath = options.output ?? join(getCwd(deps), path);
+    await mkdir2(dirname2(outputPath), { recursive: true });
+    await writeFile2(outputPath, document.bytes);
+    io.stdout(`Downloaded ${document.filename} to ${outputPath}
+`);
+  } catch (err) {
+    const errorPayload = {
+      error: err instanceof Error ? err.message : String(err)
+    };
+    if (err instanceof DocmanaError) {
+      errorPayload.code = err.code;
+      if (err.status !== void 0) errorPayload.status = err.status;
+      if (err.requestId !== void 0) errorPayload.requestId = err.requestId;
+    }
+    io.stdout(`${JSON.stringify(errorPayload, null, 2)}
+`);
+    throw new CliSilentError(err instanceof CliUsageError ? 2 : 1);
+  }
+}
+
+// src/cli/commands/organization-document-list.ts
+async function organizationDocumentListCommand(options, env, io, clientFactory, deps) {
+  try {
+    const client = await resolveApiClient(options, env, io, clientFactory, deps);
+    const payload = await client.listOrganizationDocuments({ prefix: options.prefix });
+    if (options.json) {
+      io.stdout(`${JSON.stringify(payload, null, 2)}
+`);
+      return;
+    }
+    if (!payload.configured) {
+      io.stdout("Organization document depot is not configured.\n");
+      return;
+    }
+    io.stdout(formatOrganizationDocumentList(payload.documents));
+  } catch (err) {
+    const errorPayload = {
+      error: err instanceof Error ? err.message : String(err)
+    };
+    if (err instanceof DocmanaError) {
+      errorPayload.code = err.code;
+      if (err.status !== void 0) errorPayload.status = err.status;
+      if (err.requestId !== void 0) errorPayload.requestId = err.requestId;
+    }
+    io.stdout(`${JSON.stringify(errorPayload, null, 2)}
+`);
+    throw new CliSilentError(err instanceof CliUsageError ? 2 : 1);
+  }
+}
+
+// src/cli/commands/organization-list.ts
+async function listOrganizationsCommand(options, env, io, clientFactory, deps) {
+  try {
+    const client = await resolveApiClient(options, env, io, clientFactory, deps);
+    const organizations = await client.listOrganizations();
+    if (options.json) {
+      io.stdout(`${JSON.stringify(organizations, null, 2)}
+`);
+      return;
+    }
+    io.stdout(formatOrganizationList(organizations));
+  } catch (err) {
+    if (options.json) {
+      const errorPayload = {
+        error: err instanceof Error ? err.message : String(err)
+      };
+      if (err instanceof DocmanaError) {
+        errorPayload.code = err.code;
+        if (err.status !== void 0) errorPayload.status = err.status;
+        if (err.requestId !== void 0) errorPayload.requestId = err.requestId;
       }
+      io.stdout(`${JSON.stringify(errorPayload, null, 2)}
+`);
+      throw new CliSilentError(err instanceof CliUsageError ? 2 : 1);
     }
-    const result = err.result;
-    if (result) {
-      if (result.documents && result.documents.mappings && result.documents.mappings.length > 0) {
-        lines.push("Document execution results:");
-        for (const mapping of result.documents.mappings) {
-          const docKey = mapping.reference;
-          const docName = mapping.name;
-          const docResult = result.documents[docKey];
-          if (docResult) {
-            const status = docResult.status || "Unknown";
-            const nodes = [];
-            if (docResult.classifications) nodes.push(...Object.values(docResult.classifications));
-            if (docResult.metadataExtraction) nodes.push(docResult.metadataExtraction);
-            if (docResult.extractions) nodes.push(...Object.values(docResult.extractions));
-            if (docResult.validations) nodes.push(...Object.values(docResult.validations));
-            const hasNodeFailures = nodes.some(
-              (n) => n.status === "Failed" || n.errors && n.errors.length > 0
-            );
-            if (docResult.status === "Failed" || hasNodeFailures) {
-              lines.push(`  - Document: ${docName} (Status: ${status})`);
-              if (docResult.classifications) {
-                for (const [nodeName, node] of Object.entries(docResult.classifications)) {
-                  if (node.errors && node.errors.length > 0) {
-                    lines.push(`    Classification: ${nodeName} (Status: ${node.status})`);
-                    for (const nodeErr of node.errors) {
-                      lines.push(`      - ${nodeErr}`);
-                    }
-                  }
-                }
-              }
-              if (docResult.metadataExtraction?.errors && docResult.metadataExtraction.errors.length > 0) {
-                lines.push(
-                  `    MetadataExtraction: (Status: ${docResult.metadataExtraction.status})`
-                );
-                for (const nodeErr of docResult.metadataExtraction.errors) {
-                  lines.push(`      - ${nodeErr}`);
-                }
-              }
-              if (docResult.extractions) {
-                for (const [nodeName, node] of Object.entries(docResult.extractions)) {
-                  if (node.status === "Failed" || node.errors && node.errors.length > 0) {
-                    lines.push(`    Extraction: ${nodeName} (Status: ${node.status})`);
-                    if (node.errors) {
-                      for (const nodeErr of node.errors) {
-                        lines.push(`      - ${nodeErr}`);
-                      }
-                    }
-                  }
-                }
-              }
-              if (docResult.validations) {
-                for (const [nodeName, node] of Object.entries(docResult.validations)) {
-                  if (node.status === "Failed" || node.errors && node.errors.length > 0) {
-                    lines.push(`    Validation: ${nodeName} (Status: ${node.status})`);
-                    if (node.errors) {
-                      for (const nodeErr of node.errors) {
-                        lines.push(`      - ${nodeErr}`);
-                      }
-                    }
-                  }
-                }
-              }
-            } else {
-              lines.push(`  - Document: ${docName} (Status: ${status})`);
-            }
-          } else {
-            lines.push(`  - Document: ${docName} (Status: Unknown)`);
-          }
+    throw err;
+  }
+}
+
+// src/cli/commands/flow-run.ts
+async function runFlowCommand(flowId, options, env, io, clientFactory, deps) {
+  try {
+    const files = parseFiles(options.files);
+    const client = await resolveApiClient(options, env, io, clientFactory, deps);
+    const result = await client.runFlow(
+      flowId,
+      {
+        files: files.map((path) => ({ path })),
+        language: options.language,
+        useDraftVersion: options.draft === true
+      },
+      {
+        onPoll: (event) => {
+          const nextPoll = event.nextPollAfterMs === void 0 ? "" : `, next poll in ${formatElapsedSeconds(event.nextPollAfterMs)}`;
+          io.stderr(
+            `Polling execution ${event.executionResultId}: ${event.status} (attempt ${event.attempt}, elapsed ${formatElapsedSeconds(event.elapsedMs)}${nextPoll})
+`
+          );
+        },
+        onRateLimit: (event) => {
+          io.stderr(
+            `Polling execution ${event.executionResultId}: rate limited (attempt ${event.attempt}, retrying in ${formatElapsedSeconds(event.retryAfterMs)})
+`
+          );
         }
       }
+    );
+    if (options.json) {
+      io.stdout(`${JSON.stringify(result, null, 2)}
+`);
+      return;
     }
-    return lines.join("\n");
-  }
-  if (err instanceof DocmanaError) {
-    return `Error: ${err.message} (Code: ${err.code})`;
+    io.stdout(formatHumanResult(result));
+  } catch (err) {
+    if (options.json) {
+      if (err instanceof DocmanaExecutionError && err.result) {
+        io.stdout(`${JSON.stringify(err.result, null, 2)}
+`);
+      } else {
+        const errorPayload = {
+          error: err instanceof Error ? err.message : String(err)
+        };
+        if (err instanceof DocmanaError) {
+          errorPayload.code = err.code;
+          if (err.status !== void 0) errorPayload.status = err.status;
+          if (err.requestId !== void 0) errorPayload.requestId = err.requestId;
+        }
+        io.stdout(`${JSON.stringify(errorPayload, null, 2)}
+`);
+      }
+      throw new CliSilentError(err instanceof CliUsageError ? 2 : 1);
+    }
+    throw err;
   }
-  if (err instanceof Error) {
-    return `Error: ${err.message}`;
+}
+
+// src/cli/commands/login.ts
+async function loginCommand(options, env, io, deps) {
+  const auth = await resolveAuthConfig(options, env, deps);
+  const tokenCachePath = resolveTokenCachePath(options.tokenCache, getCwd(deps));
+  const tokenCache = createFileTokenCache(tokenCachePath);
+  const hadFreshCachedToken = Boolean(await readFreshCachedToken(tokenCache));
+  const tokenManager = new TokenManager({
+    clientId: auth.clientId,
+    clientSecret: auth.clientSecret,
+    tokenEndpoint: auth.tokenEndpoint,
+    scope: auth.scope,
+    fetchImpl: deps.fetch ?? fetch,
+    tokenCache
+  });
+  await tokenManager.getToken();
+  const cached = await tokenCache.read();
+  if (!hadFreshCachedToken) {
+    io.stdout("Generated new access token and updated the token cache.\n");
   }
-  return `Error: ${String(err)}`;
+  io.stdout(`Logged in. Token cached at ${tokenCachePath}
+`);
+  if (cached) io.stdout(formatTokenExpiry(cached.expiresAt));
 }
-function formatSingleError(e) {
-  if (typeof e === "string") return e;
-  if (e && typeof e === "object") {
-    const obj = e;
-    if (typeof obj.msg === "string") return obj.msg;
-    if (typeof obj.message === "string") return obj.message;
-    if (typeof obj.error === "string") return obj.error;
-    try {
-      return JSON.stringify(e);
-    } catch {
-      return String(e);
+function formatTokenExpiry(expiresAt) {
+  const expiresAtDate = new Date(expiresAt);
+  return [
+    `Token expires at local time ${expiresAtDate.toLocaleString()}`,
+    `Token expires at UTC ${expiresAtDate.toISOString()}`
+  ].join("\n") + "\n";
+}
+
+// src/cli/cli.ts
+async function runCli(argv = process.argv.slice(2), env = process.env, io = {
+  stdout: (text) => process.stdout.write(text),
+  stderr: (text) => process.stderr.write(text)
+}, clientFactory = (config) => new Docmana(config), deps = {}) {
+  const program = buildProgram(env, io, clientFactory, deps);
+  if (argv.length === 0) {
+    io.stdout(program.helpInformation());
+    return 0;
+  }
+  try {
+    await program.parseAsync(argv, { from: "user" });
+    return 0;
+  } catch (err) {
+    if (err instanceof CliSilentError) {
+      return err.exitCode;
+    }
+    if (err instanceof CliUsageError) {
+      io.stderr(`Error: ${err.message}
+`);
+      return 2;
+    }
+    if (err instanceof CommanderError) {
+      return err.exitCode === 0 ? 0 : 2;
     }
+    io.stderr(`${formatRuntimeError(err)}
+`);
+    return 1;
   }
-  return String(e);
+}
+function buildProgram(env, io, clientFactory, deps) {
+  const program = new Command();
+  program.name("docmana").description(HELP.root).showHelpAfterError().configureOutput({
+    writeOut: io.stdout,
+    writeErr: io.stderr,
+    outputError: (str, write) => write(str)
+  }).exitOverride();
+  program.command("login").description(HELP.login).option("--client-id <id>", "OAuth2 client id; defaults to DOCMANA_CLIENT_ID").option("--client-secret <secret>", "OAuth2 client secret; defaults to DOCMANA_CLIENT_SECRET").option("--token-url <url>", "OAuth2 token endpoint; defaults to DOCMANA_TOKEN_URL").option("--scope <scope>", "OAuth2 scope; defaults to DOCMANA_SCOPE").option("--config <path>", `Config file path; defaults to ./${DEFAULT_CONFIG_FILE}`).option("--token-cache <path>", `Token cache path; defaults to ./${DEFAULT_TOKEN_CACHE_FILE}`).action(async (options) => {
+    await loginCommand(options, env, io, deps);
+  });
+  const flow = program.command("flow").description(HELP.flow).action(() => {
+    io.stdout(flow.helpInformation());
+  });
+  flow.command("list").description(HELP.list).option("--api-url <url>", "Consumer API base URL; defaults to DOCMANA_API_URL").option("--access-token <token>", "Bearer token; defaults to DOCMANA_ACCESS_TOKEN").option("--config <path>", `Config file path; defaults to ./${DEFAULT_CONFIG_FILE}`).option("--token-cache <path>", `Token cache path; defaults to ./${DEFAULT_TOKEN_CACHE_FILE}`).option("--json", "Print the raw JSON flow list").action(async (options) => {
+    await listFlowsCommand(options, env, io, clientFactory, deps);
+  });
+  flow.command("run").description(HELP.run).argument("<flow-id>", "Docmana flow id").requiredOption("--files <csv>", "Comma-separated file paths to upload").option("--api-url <url>", "Consumer API base URL; defaults to DOCMANA_API_URL").option("--access-token <token>", "Bearer token; defaults to DOCMANA_ACCESS_TOKEN").option("--config <path>", `Config file path; defaults to ./${DEFAULT_CONFIG_FILE}`).option("--token-cache <path>", `Token cache path; defaults to ./${DEFAULT_TOKEN_CACHE_FILE}`).option("--json", "Print the raw JSON result").option("--language <lang>", "Translate output to specified language").option("--draft", "Run the current draft flow version").action(async (flowId, options) => {
+    await runFlowCommand(flowId, options, env, io, clientFactory, deps);
+  });
+  flow.command("metadata").description(HELP.metadata).argument("<flow-id>", "Docmana flow id").option("--api-url <url>", "Consumer API base URL; defaults to DOCMANA_API_URL").option("--access-token <token>", "Bearer token; defaults to DOCMANA_ACCESS_TOKEN").option("--config <path>", `Config file path; defaults to ./${DEFAULT_CONFIG_FILE}`).option("--token-cache <path>", `Token cache path; defaults to ./${DEFAULT_TOKEN_CACHE_FILE}`).action(async (flowId, options) => {
+    await flowMetadataCommand(flowId, options, env, io, clientFactory, deps);
+  });
+  flow.command("definition").description(HELP.definition).argument("<flow-id>", "Docmana flow id").option("--api-url <url>", "Consumer API base URL; defaults to DOCMANA_API_URL").option("--access-token <token>", "Bearer token; defaults to DOCMANA_ACCESS_TOKEN").option("--config <path>", `Config file path; defaults to ./${DEFAULT_CONFIG_FILE}`).option("--token-cache <path>", `Token cache path; defaults to ./${DEFAULT_TOKEN_CACHE_FILE}`).action(async (flowId, options) => {
+    await flowDefinitionCommand(flowId, options, env, io, clientFactory, deps);
+  });
+  const organization = program.command("organization").description(HELP.organization).action(() => {
+    io.stdout(organization.helpInformation());
+  });
+  organization.command("list").description(HELP.organizationList).option("--api-url <url>", "Consumer API base URL; defaults to DOCMANA_API_URL").option("--access-token <token>", "Bearer token; defaults to DOCMANA_ACCESS_TOKEN").option("--config <path>", `Config file path; defaults to ./${DEFAULT_CONFIG_FILE}`).option("--token-cache <path>", `Token cache path; defaults to ./${DEFAULT_TOKEN_CACHE_FILE}`).option("--json", "Print the raw JSON organization list").action(async (options) => {
+    await listOrganizationsCommand(options, env, io, clientFactory, deps);
+  });
+  const organizationDocument = organization.command("document").description(HELP.organizationDocument).action(() => {
+    io.stdout(organizationDocument.helpInformation());
+  });
+  organizationDocument.command("list").description(HELP.organizationDocumentList).option("--api-url <url>", "Consumer API base URL; defaults to DOCMANA_API_URL").option("--access-token <token>", "Bearer token; defaults to DOCMANA_ACCESS_TOKEN").option("--config <path>", `Config file path; defaults to ./${DEFAULT_CONFIG_FILE}`).option("--token-cache <path>", `Token cache path; defaults to ./${DEFAULT_TOKEN_CACHE_FILE}`).option("--prefix <prefix>", "Filter documents by path prefix").option("--json", "Print the raw JSON organization document list").action(async (options) => {
+    await organizationDocumentListCommand(options, env, io, clientFactory, deps);
+  });
+  organizationDocument.command("download").description(HELP.organizationDocumentDownload).argument("<path>", "Organization document path").option("--output <file>", "Output file path; defaults to ./{path}").option("--api-url <url>", "Consumer API base URL; defaults to DOCMANA_API_URL").option("--access-token <token>", "Bearer token; defaults to DOCMANA_ACCESS_TOKEN").option("--config <path>", `Config file path; defaults to ./${DEFAULT_CONFIG_FILE}`).option("--token-cache <path>", `Token cache path; defaults to ./${DEFAULT_TOKEN_CACHE_FILE}`).action(async (path, options) => {
+    await organizationDocumentDownloadCommand(path, options, env, io, clientFactory, deps);
+  });
+  const config = program.command("config").description(HELP.config).action(() => {
+    io.stdout(config.helpInformation());
+  });
+  config.command("init").description(HELP.configInit).option("--config <path>", `Config file path; defaults to ./${DEFAULT_CONFIG_FILE}`).action(async (options) => {
+    await configInitCommand(options, io, deps);
+  });
+  return program;
 }
 function isDirectRun() {
   const entry = process.argv[1];
   if (!entry) return false;
   try {
-    return realpathSync(resolve(entry)) === realpathSync(fileURLToPath(import.meta.url));
+    return realpathSync(resolve2(entry)) === realpathSync(fileURLToPath(import.meta.url));
   } catch {
     return false;
   }