@lumoai/cli 1.0.0

package/README.md

@@ -0,0 +1,90 @@
+# Lumo CLI
+
+Manage [Lumo](https://www.uselumo.ai) tasks, sessions, sprints, and documents from the terminal. Designed to pair with Claude Code so AI agents can bind to a task, load context, and update state without leaving the shell.
+
+## Install
+
+```bash
+npm install -g @lumoai/cli
+```
+
+Verify:
+
+```bash
+lumo --version
+```
+
+## Authentication
+
+```bash
+lumo auth login
+```
+
+The CLI opens your browser to create an API key, then reads it from stdin. Keys are stored in `~/.lumo/credentials.json`.
+
+Check who you're logged in as:
+
+```bash
+lumo whoami
+# Logged in as you@example.com
+#   Workspace: Acme (acme)
+#   Key: My laptop (lum_abc1...)
+#   API: https://www.uselumo.ai
+```
+
+## Quick Start
+
+```bash
+# What am I working on?
+lumo task list
+
+# Create a task
+lumo task create "Fix Slack OAuth redirect" --priority high
+
+# Mark it in progress
+lumo task update LUM-42 --status in_progress
+
+# Bind the current Claude Code session to the task
+lumo session attach LUM-42
+
+# Load full background (description, prior session summaries, memory)
+lumo task context LUM-42
+
+# When you're done
+lumo task update LUM-42 --status done
+```
+
+## Commands
+
+| Group           | Highlights                                                    |
+| --------------- | ------------------------------------------------------------- |
+| `auth`          | `login`, `logout`                                             |
+| `whoami`        | Show current identity + workspace                             |
+| `task`          | `create`, `update`, `list`, `show`, `comment`, `context`      |
+| `session`       | `attach`, `status`, `detach` (binds Claude Code sessions)     |
+| `project`       | `list`                                                        |
+| `milestone`     | `create`, `update`, `list`, `show`, `delete`                  |
+| `sprint`        | `create`, `start`, `close`, `list`, `show`, `add`, `remove`, `summary` |
+| `doc`           | `create`, `update`, `list`, `show`, `move`, `bind`, `share`   |
+
+Every command accepts `--help` for full flags and examples:
+
+```bash
+lumo task create --help
+lumo sprint close --help
+```
+
+## Environment Variables
+
+| Variable                  | Default                  | Purpose                                                       |
+| ------------------------- | ------------------------ | ------------------------------------------------------------- |
+| `LUMO_API_URL`            | `https://www.uselumo.ai` | Override the API endpoint (e.g. self-hosted Lumo instance).   |
+| `CLAUDE_CODE_SESSION_ID`  | _(set by Claude Code)_   | Required for `session attach` / `status` / `detach`.          |
+
+## Claude Code Integration
+
+Inside a Claude Code session, the agent skill auto-discovers the CLI and uses it to load task context, bind sessions, and update task state. See the [Lumo Claude Code skill](https://github.com/Lumo-Workspace/lumo/tree/main/.claude/skills/lumo) for the full agent contract.
+
+## License
+
+MIT

package/dist/cli/src/commands/auth-login.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.authLogin = authLogin;
+const prompt_1 = require("../lib/prompt");
+const browser_1 = require("../lib/browser");
+const api_1 = require("../lib/api");
+const config_1 = require("../lib/config");
+const KEY_PREFIX = 'lum_';
+async function authLogin() {
+    const apiUrl = (0, api_1.resolveApiUrl)();
+    const webUrl = (0, api_1.trimTrailingSlash)(apiUrl);
+    console.log('Log in to Lumo');
+    console.log('');
+    console.log(`  1. Open ${webUrl} and go to Settings → API Keys`);
+    console.log(`  2. Create a new key and copy it`);
+    console.log(`  3. Paste it below`);
+    console.log('');
+    console.log('Opening your browser…');
+    (0, browser_1.openBrowser)(webUrl);
+    console.log('');
+    const token = await (0, prompt_1.promptSecret)('API key (input hidden): ');
+    if (!token) {
+        console.log('Login cancelled.');
+        return 1;
+    }
+    if (!token.startsWith(KEY_PREFIX)) {
+        console.error(`Error: API key must start with "${KEY_PREFIX}"`);
+        return 1;
+    }
+    let resp;
+    try {
+        resp = await (0, api_1.verifyToken)(apiUrl, token);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error: ${msg}`);
+        return 1;
+    }
+    (0, config_1.writeCredentials)({
+        token,
+        apiUrl,
+        userId: resp.user.id,
+        email: resp.user.email,
+        workspaceId: resp.workspace.id,
+        workspaceSlug: resp.workspace.slug,
+        workspaceName: resp.workspace.name,
+        apiKeyId: resp.apiKey.id,
+        apiKeyName: resp.apiKey.name,
+        apiKeyPrefix: resp.apiKey.prefix,
+    });
+    console.log('');
+    console.log(`✓ Logged in as ${resp.user.email}`);
+    console.log(`  Workspace: ${resp.workspace.name}`);
+    console.log(`  Key: ${resp.apiKey.name} (${resp.apiKey.prefix})`);
+}

package/dist/cli/src/commands/auth-logout.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.authLogout = authLogout;
+const config_1 = require("../lib/config");
+async function authLogout() {
+    const creds = (0, config_1.readCredentials)();
+    if (!creds) {
+        console.log('Not logged in');
+        return 0;
+    }
+    const email = creds.email;
+    (0, config_1.deleteCredentials)();
+    console.log(`✓ Logged out (${email})`);
+}

package/dist/cli/src/commands/doc-bind.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatBindOutput = formatBindOutput;
+exports.docBind = docBind;
+const config_1 = require("../lib/config");
+const api_1 = require("../lib/api");
+const resolve_doc_id_1 = require("../lib/resolve-doc-id");
+function formatBindOutput(args) {
+    if (args.alreadyBound)
+        return `Already bound ${args.docId} ↔ ${args.identifier}`;
+    const upgrade = args.upgradedFromContent ? ' (upgraded from content)' : '';
+    return `Bound ${args.docId} ↔ ${args.identifier}${upgrade}`;
+}
+async function docBind(docRef, task) {
+    if (!docRef || !task) {
+        console.error('Error: usage: lumo doc bind <doc> <task>');
+        return 1;
+    }
+    const creds = (0, config_1.readCredentials)();
+    if (!creds) {
+        console.error('Error: not logged in. Run `lumo auth login` first.');
+        return 1;
+    }
+    const envUrl = process.env.LUMO_API_URL?.trim();
+    const apiUrl = envUrl && envUrl.length > 0 ? envUrl : creds.apiUrl;
+    const docId = await (0, resolve_doc_id_1.lookupDocId)(apiUrl, creds.token, docRef);
+    if (!docId) {
+        console.error(`Error: Document not found: ${docRef}`);
+        return 1;
+    }
+    const url = `${(0, api_1.trimTrailingSlash)(apiUrl)}/api/documents/${docId}/mentions`;
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${creds.token}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ taskIdentifier: task }),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        console.error(`Error: ${res.status} ${res.statusText}: ${text}`);
+        return 1;
+    }
+    const { mention } = (await res.json());
+    console.log(formatBindOutput({
+        docId,
+        identifier: mention.taskIdentifier,
+        alreadyBound: mention.alreadyBound,
+        upgradedFromContent: mention.upgradedFromContent,
+    }));
+}

package/dist/cli/src/commands/doc-create.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeScope = normalizeScope;
+exports.formatCreatedDocLine = formatCreatedDocLine;
+exports.docCreate = docCreate;
+const config_1 = require("../lib/config");
+const api_1 = require("../lib/api");
+const doc_input_1 = require("../lib/doc-input");
+const tag_resolver_1 = require("../lib/tag-resolver");
+const resolve_doc_id_1 = require("../lib/resolve-doc-id");
+/** personal → PRIVATE, workspace → WORKSPACE. Null on unknown. */
+function normalizeScope(value) {
+    const lower = (value ?? '').toLowerCase();
+    if (lower === 'personal')
+        return 'PRIVATE';
+    if (lower === 'workspace')
+        return 'WORKSPACE';
+    return null;
+}
+function formatCreatedDocLine(doc) {
+    const escaped = doc.title.replace(/"/g, '\\"');
+    const head = `Created ${doc.id} "${escaped}"  ${doc.url}`;
+    if (doc.tags && doc.tags.length > 0) {
+        return `${head}\nTags: ${doc.tags.join(', ')}`;
+    }
+    return head;
+}
+function docUrl(apiUrl, workspaceSlug, id) {
+    return `${(0, api_1.trimTrailingSlash)(apiUrl)}/workspace/${workspaceSlug}/documents/${id}`;
+}
+async function docCreate(title, opts) {
+    const creds = (0, config_1.readCredentials)();
+    if (!creds) {
+        console.error('Error: not logged in. Run `lumo auth login` first.');
+        return 1;
+    }
+    let visibility = 'PRIVATE';
+    if (opts.scope !== undefined) {
+        const normalized = normalizeScope(opts.scope);
+        if (!normalized) {
+            console.error(`Error: invalid scope "${opts.scope}". Allowed: personal, workspace`);
+            return 1;
+        }
+        visibility = normalized;
+    }
+    const content = await (0, doc_input_1.resolveDocContent)({
+        content: opts.content,
+        file: opts.file,
+        stdinIsTTY: Boolean(process.stdin.isTTY),
+        readStdin: doc_input_1.readStdinToString,
+        readFile: doc_input_1.readFileUtf8,
+    });
+    if (content.kind === 'error') {
+        console.error(`Error: ${content.message}`);
+        return 1;
+    }
+    const envUrl = process.env.LUMO_API_URL?.trim();
+    const apiUrl = envUrl && envUrl.length > 0 ? envUrl : creds.apiUrl;
+    const url = `${(0, api_1.trimTrailingSlash)(apiUrl)}/api/documents`;
+    let tagIds;
+    if ((opts.tag && opts.tag.length > 0) ||
+        (opts.tagId && opts.tagId.length > 0)) {
+        try {
+            tagIds = await (0, tag_resolver_1.resolveTagRefs)({ names: opts.tag ?? [], ids: opts.tagId ?? [] }, { apiUrl, token: creds.token });
+        }
+        catch (err) {
+            console.error(`Error: ${err.message}`);
+            return 1;
+        }
+    }
+    let resolvedParentId;
+    if (opts.parent !== undefined && opts.parent.length > 0) {
+        const id = await (0, resolve_doc_id_1.lookupDocId)(apiUrl, creds.token, opts.parent);
+        if (!id) {
+            console.error(`Error: --parent doc not found: ${opts.parent}`);
+            return 1;
+        }
+        resolvedParentId = id;
+    }
+    const body = {
+        title: title?.trim() ?? '',
+        visibility,
+    };
+    if (content.kind === 'ok')
+        body.contentMarkdown = content.markdown;
+    if (opts.project !== undefined)
+        body.projectRef = opts.project;
+    if (tagIds && tagIds.length > 0)
+        body.tagIds = tagIds;
+    if (resolvedParentId !== undefined)
+        body.parentId = resolvedParentId;
+    let res;
+    try {
+        res = await fetch(url, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${creds.token}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(body),
+        });
+    }
+    catch (err) {
+        console.error(`Error: network failure: ${err.message}`);
+        return 1;
+    }
+    if (!res.ok) {
+        const text = await res.text();
+        console.error(`Error: ${res.status} ${res.statusText}: ${text}`);
+        return 1;
+    }
+    const { document } = (await res.json());
+    const fullUrl = docUrl(apiUrl, creds.workspaceSlug ?? 'lumo', document.slug);
+    const responseTagNames = (document.docTags ?? []).map(t => t.name);
+    console.log(formatCreatedDocLine({
+        id: document.id,
+        title: document.title,
+        url: fullUrl,
+        tags: responseTagNames,
+    }));
+    if (opts.task) {
+        const bindUrl = `${(0, api_1.trimTrailingSlash)(apiUrl)}/api/documents/${document.id}/mentions`;
+        const bindRes = await fetch(bindUrl, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${creds.token}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ taskIdentifier: opts.task }),
+        });
+        if (!bindRes.ok) {
+            const text = await bindRes.text();
+            console.error(`Warning: doc created but bind to ${opts.task} failed: ${bindRes.status} ${text}`);
+            return 1;
+        }
+        console.log(`Bound ${document.id} ↔ ${opts.task}`);
+    }
+}

package/dist/cli/src/commands/doc-delete.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.docDelete = docDelete;
+const config_1 = require("../lib/config");
+const api_1 = require("../lib/api");
+const resolve_doc_1 = require("../lib/resolve-doc");
+const resolve_doc_id_1 = require("../lib/resolve-doc-id");
+async function docDelete(reference, opts) {
+    if (!reference) {
+        console.error('Error: missing <doc>. Usage: lumo doc delete <doc> --yes');
+        return 1;
+    }
+    if (!opts.yes) {
+        console.error('Error: Refusing to delete without --yes');
+        return 1;
+    }
+    const creds = (0, config_1.readCredentials)();
+    if (!creds) {
+        console.error('Error: not logged in. Run `lumo auth login` first.');
+        return 1;
+    }
+    const envUrl = process.env.LUMO_API_URL?.trim();
+    const apiUrl = envUrl && envUrl.length > 0 ? envUrl : creds.apiUrl;
+    // For a cuid reference we don't have the title; for a title we look up id+title at once.
+    let id;
+    let title = '';
+    if ((0, resolve_doc_1.isLikelyCuid)(reference)) {
+        id = reference;
+    }
+    else {
+        const fetched = await (0, resolve_doc_id_1.lookupDocId)(apiUrl, creds.token, reference);
+        if (!fetched) {
+            console.error(`Error: Document not found: ${reference}`);
+            return 1;
+        }
+        id = fetched;
+        // Pick up the title from the lookup payload by repeating the GET — small extra cost.
+        // (Alternative: change lookupDocId to return the full DocLike. For now keep it simple.)
+        title = reference;
+    }
+    const res = await fetch(`${(0, api_1.trimTrailingSlash)(apiUrl)}/api/documents/${id}`, {
+        method: 'DELETE',
+        headers: { Authorization: `Bearer ${creds.token}` },
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        console.error(`Error: ${res.status} ${res.statusText}: ${text}`);
+        return 1;
+    }
+    const escaped = title.replace(/"/g, '\\"');
+    console.log(`Deleted ${id}${title ? ` "${escaped}"` : ''}`);
+}

package/dist/cli/src/commands/doc-list.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatDocListRows = formatDocListRows;
+exports.formatDocListRowsAsTree = formatDocListRowsAsTree;
+exports.docList = docList;
+const config_1 = require("../lib/config");
+const api_1 = require("../lib/api");
+const doc_create_1 = require("./doc-create");
+const doc_tree_1 = require("../lib/doc-tree");
+function visibilityLabel(v) {
+    if (v === 'PRIVATE')
+        return 'PERSONAL';
+    return v;
+}
+function formatDocListRows(rows) {
+    if (rows.length === 0)
+        return [];
+    return rows.map(r => {
+        const label = visibilityLabel(r.visibility).padEnd(10, ' ');
+        const project = (r.project?.name ?? '-').padEnd(14, ' ');
+        return `${r.id}  ${label}  ${project}  ${r.title}`;
+    });
+}
+function formatDocListRowsAsTree(rows) {
+    if (rows.length === 0)
+        return [];
+    const tree = (0, doc_tree_1.buildTree)(rows);
+    const flat = (0, doc_tree_1.flattenWithDepth)(tree);
+    return flat.map(({ row, depth }) => {
+        const label = visibilityLabel(row.visibility).padEnd(10, ' ');
+        const project = (row.project?.name ?? '-').padEnd(14, ' ');
+        const indent = '  '.repeat(depth);
+        return `${row.id}  ${label}  ${project}  ${indent}${row.title}`;
+    });
+}
+async function docList(opts) {
+    const creds = (0, config_1.readCredentials)();
+    if (!creds) {
+        console.error('Error: not logged in. Run `lumo auth login` first.');
+        return 1;
+    }
+    const envUrl = process.env.LUMO_API_URL?.trim();
+    const apiUrl = envUrl && envUrl.length > 0 ? envUrl : creds.apiUrl;
+    let url;
+    if (opts.task) {
+        url = `${(0, api_1.trimTrailingSlash)(apiUrl)}/api/tasks/${opts.task}/documents`;
+    }
+    else {
+        const params = new URLSearchParams();
+        if (opts.scope && opts.scope !== 'all') {
+            const v = (0, doc_create_1.normalizeScope)(opts.scope);
+            if (!v) {
+                console.error(`Error: invalid scope "${opts.scope}". Allowed: personal, workspace, all`);
+                return 1;
+            }
+            params.set('visibility', v);
+        }
+        if (opts.project)
+            params.set('projectRef', opts.project);
+        const qs = params.toString();
+        url = `${(0, api_1.trimTrailingSlash)(apiUrl)}/api/documents${qs ? `?${qs}` : ''}`;
+    }
+    const res = await fetch(url, {
+        headers: { Authorization: `Bearer ${creds.token}` },
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        console.error(`Error: ${res.status} ${res.statusText}: ${text}`);
+        return 1;
+    }
+    const { documents } = (await res.json());
+    let rows = documents;
+    if (opts.task && opts.scope && opts.scope !== 'all') {
+        const v = (0, doc_create_1.normalizeScope)(opts.scope);
+        if (v)
+            rows = rows.filter(r => r.visibility === v);
+    }
+    if (opts.task && opts.project) {
+        rows = rows.filter(r => (r.project?.name ?? '').toLowerCase() === opts.project.toLowerCase());
+    }
+    if (opts.limit) {
+        const n = parseInt(opts.limit, 10);
+        if (!Number.isNaN(n))
+            rows = rows.slice(0, n);
+    }
+    const lines = opts.tree
+        ? formatDocListRowsAsTree(rows)
+        : formatDocListRows(rows);
+    for (const line of lines)
+        console.log(line);
+}

package/dist/cli/src/commands/doc-move.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.docMove = docMove;
+const config_1 = require("../lib/config");
+const api_1 = require("../lib/api");
+const resolve_doc_1 = require("../lib/resolve-doc");
+const doc_sort_order_1 = require("../lib/doc-sort-order");
+async function docMove(reference, opts) {
+    if (!reference) {
+        console.error('Error: usage: lumo doc move <doc> --parent <doc> | --root');
+        return 1;
+    }
+    const hasParent = typeof opts.parent === 'string' && opts.parent.length > 0;
+    const hasRoot = Boolean(opts.root);
+    if (hasParent && hasRoot) {
+        console.error('Error: --parent and --root are mutually exclusive');
+        return 1;
+    }
+    if (!hasParent && !hasRoot) {
+        console.error('Error: specify --parent <doc> or --root');
+        return 1;
+    }
+    const creds = (0, config_1.readCredentials)();
+    if (!creds) {
+        console.error('Error: not logged in. Run `lumo auth login` first.');
+        return 1;
+    }
+    const envUrl = process.env.LUMO_API_URL?.trim();
+    const apiUrl = envUrl && envUrl.length > 0 ? envUrl : creds.apiUrl;
+    const listUrl = `${(0, api_1.trimTrailingSlash)(apiUrl)}/api/documents`;
+    let listRes;
+    try {
+        listRes = await fetch(listUrl, {
+            headers: { Authorization: `Bearer ${creds.token}` },
+        });
+    }
+    catch (err) {
+        console.error(`Error: network failure: ${err.message}`);
+        return 1;
+    }
+    if (!listRes.ok) {
+        const text = await listRes.text();
+        console.error(`Error: ${listRes.status} ${listRes.statusText}: ${text}`);
+        return 1;
+    }
+    const { documents } = (await listRes.json());
+    const docMatch = (0, resolve_doc_1.resolveDoc)(reference, documents);
+    if (docMatch.kind === 'ambiguous') {
+        console.error(`Error: title "${reference}" matches ${docMatch.candidates.length} docs:`);
+        for (const c of docMatch.candidates) {
+            console.error(`  ${c.id}  ${c.title}`);
+        }
+        console.error('Re-run with the cuid.');
+        return 1;
+    }
+    if (docMatch.kind === 'not-found') {
+        console.error(`Error: Document not found: ${reference}`);
+        return 1;
+    }
+    const docRow = documents.find(d => d.id === docMatch.doc.id);
+    let newParentId = null;
+    let parentTitleForOutput = 'root';
+    if (hasParent) {
+        const parentMatch = (0, resolve_doc_1.resolveDoc)(opts.parent, documents);
+        if (parentMatch.kind === 'ambiguous') {
+            console.error(`Error: --parent "${opts.parent}" matches ${parentMatch.candidates.length} docs:`);
+            for (const c of parentMatch.candidates) {
+                console.error(`  ${c.id}  ${c.title}`);
+            }
+            console.error('Re-run with the cuid.');
+            return 1;
+        }
+        if (parentMatch.kind === 'not-found') {
+            console.error(`Error: Document not found: ${opts.parent}`);
+            return 1;
+        }
+        const parentRow = documents.find(d => d.id === parentMatch.doc.id);
+        newParentId = parentRow.id;
+        parentTitleForOutput = `"${parentRow.title.replace(/"/g, '\\"')}"`;
+    }
+    const siblings = documents.filter(d => d.parentId === newParentId && d.id !== docRow.id);
+    const sortOrder = (0, doc_sort_order_1.pickNextSortOrder)(siblings);
+    const moveUrl = `${(0, api_1.trimTrailingSlash)(apiUrl)}/api/documents/${docRow.id}/move`;
+    let moveRes;
+    try {
+        moveRes = await fetch(moveUrl, {
+            method: 'PATCH',
+            headers: {
+                Authorization: `Bearer ${creds.token}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ parentId: newParentId, sortOrder }),
+        });
+    }
+    catch (err) {
+        console.error(`Error: network failure: ${err.message}`);
+        return 1;
+    }
+    if (!moveRes.ok) {
+        const text = await moveRes.text();
+        let msg = text;
+        try {
+            const json = JSON.parse(text);
+            if (json.error)
+                msg = json.error;
+        }
+        catch { }
+        console.error(`Error: ${moveRes.status} ${moveRes.statusText}: ${msg}`);
+        return 1;
+    }
+    const escapedDocTitle = docRow.title.replace(/"/g, '\\"');
+    console.log(`Moved ${docRow.id} "${escapedDocTitle}" → ${parentTitleForOutput}`);
+}

package/dist/cli/src/commands/doc-share-list.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatShareListRows = formatShareListRows;
+exports.docShareList = docShareList;
+const config_1 = require("../lib/config");
+const api_1 = require("../lib/api");
+const resolve_doc_id_1 = require("../lib/resolve-doc-id");
+const resolve_member_1 = require("../lib/resolve-member");
+function formatShareListRows(rows) {
+    if (rows.length === 0)
+        return [];
+    const nameWidth = Math.max(...rows.map(r => r.displayName.length));
+    return rows.map(r => {
+        const name = r.displayName.padEnd(nameWidth, ' ');
+        return `${name}  ${r.role}`;
+    });
+}
+async function docShareList(docRef) {
+    if (!docRef) {
+        console.error('Error: usage: lumo doc share-list <doc>');
+        return 1;
+    }
+    const creds = (0, config_1.readCredentials)();
+    if (!creds) {
+        console.error('Error: not logged in. Run `lumo auth login` first.');
+        return 1;
+    }
+    const envUrl = process.env.LUMO_API_URL?.trim();
+    const apiUrl = envUrl && envUrl.length > 0 ? envUrl : creds.apiUrl;
+    const docId = await (0, resolve_doc_id_1.lookupDocId)(apiUrl, creds.token, docRef);
+    if (!docId) {
+        console.error(`Error: Document not found: ${docRef}`);
+        return 1;
+    }
+    // Shares endpoint returns memberId only; we cross-reference the workspace
+    // member directory to print a friendly display name. If the directory call
+    // fails (rare), we fall back to memberId so the user still sees something.
+    const [sharesRes, members] = await Promise.all([
+        fetch(`${(0, api_1.trimTrailingSlash)(apiUrl)}/api/documents/${docId}/shares`, {
+            headers: { Authorization: `Bearer ${creds.token}` },
+        }),
+        (0, resolve_member_1.fetchMembers)(apiUrl, creds.token).catch(() => null),
+    ]);
+    if (!sharesRes.ok) {
+        const text = await sharesRes.text();
+        console.error(`Error: ${sharesRes.status} ${sharesRes.statusText}: ${text}`);
+        return 1;
+    }
+    const { shares } = (await sharesRes.json());
+    const nameByMemberId = new Map();
+    if (members) {
+        for (const m of members)
+            nameByMemberId.set(m.memberId, m.displayName);
+    }
+    const rows = shares.map(s => ({
+        displayName: nameByMemberId.get(s.member.id) ?? s.member.id,
+        role: s.role,
+    }));
+    const lines = formatShareListRows(rows);
+    for (const line of lines)
+        console.log(line);
+}