@nemus-cli/nemus 0.2.11 → 0.2.13

package/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.13] - 2026-08-27
+
+### Added
+
+- **Shell completions**: `nemus completion bash|zsh|fish` prints a completion
+  script for that shell. Completes subcommands (names + aliases) and, for a
+  workspace-scoped command, live **workspace names** — the script calls back
+  into `nemus completion --workspaces`, so completions stay fresh without
+  regenerating. Registered for both the `nemus` and `nem` binaries. Install e.g.
+  `nemus completion zsh > "${fpath[1]}/_nemus"` (see README).
+
+## [0.2.12] - 2026-08-27
+
+### Added
+
+- **`--json` for more read-only reporting commands**, extending 0.2.11's set
+  (`list`/`status`/`doctor`) to `suite list`, `sessions`, and `analyze-deps`.
+  Each emits exactly one JSON document to stdout (no tables, no interactive
+  prompt): `suite list --json` (saved suites + entries), `sessions --json`
+  (workspace sessions, list-only — no resume), `analyze-deps --json` (per-repo
+  dependencies/dependents/missing + circular deps + suggested missing repos;
+  requires an explicit workspace). `--json` errors are parseable
+  `{ ok:false, error }` on stdout + exit 1, consistent with 0.2.11.
+
 ## [0.2.11] - 2026-08-27
 
 ### Added

package/README.md

@@ -225,18 +225,41 @@ shared-lib       main         ✓ Clean       ↓3             -
 
 ### Scripting: `--json`
 
-`list`, `status`, and `doctor` accept `--json` for stable, machine-readable
-output. Diagnostics go to stderr, so stdout is a single JSON document you can
-pipe straight into `jq` or a CI step:
+The read-only reporting commands accept `--json` for stable, machine-readable
+output: `list`, `status`, `doctor`, `suite list`, `sessions`, and
+`analyze-deps`. Diagnostics go to stderr, so stdout is a single JSON document
+you can pipe straight into `jq` or a CI step:
 
 ```bash
 nemus list --json | jq -r '.workspaces[].name'
 nemus status my-workspace --json | jq '.clean'
 nemus doctor my-workspace --json | jq '.score'
+nemus suite list --json | jq -r '.suites[].name'
+nemus sessions --json | jq -r '.sessions[].workspaceName'
+nemus analyze-deps my-workspace --json | jq '.circularDependencies'
 ```
 
-`status`/`doctor` with `--json` need an explicit workspace name (they never
-prompt).
+The workspace-scoped ones (`status`/`doctor`/`analyze-deps`) need an explicit
+workspace name with `--json` (they never prompt). On failure, `--json` prints a
+parseable `{ "ok": false, "error": … }` to stdout and exits non-zero.
+
+### Shell completions
+
+Tab-complete subcommands and workspace names. `nemus completion <shell>` prints
+a script for `bash`, `zsh`, or `fish` (works for both the `nemus` and `nem`
+binaries):
+
+```bash
+# bash
+nemus completion bash > /etc/bash_completion.d/nemus     # or >> ~/.bashrc
+# zsh (a directory on your $fpath)
+nemus completion zsh > "${fpath[1]}/_nemus"
+# fish
+nemus completion fish > ~/.config/fish/completions/nemus.fish
+```
+
+Workspace names are resolved live (the script calls back into the CLI), so they
+stay current without regenerating.
 
 ### Suites (reusable repo collections)
 

package/dist/commands/analyze-deps.js

@@ -42,6 +42,7 @@ const config_1 = require("../utils/config");
 const workspace_meta_1 = require("../utils/workspace-meta");
 const dependency_analyzer_1 = require("../utils/dependency-analyzer");
 const logger_1 = require("../utils/logger");
+const output_1 = require("../utils/output");
 const colors_1 = require("../utils/colors");
 const inquirer_1 = __importDefault(require("inquirer"));
 const command_helpers_1 = require("../utils/command-helpers");
@@ -71,22 +72,51 @@ function registerAnalyzeDepsCommand(parent) {
         .alias('ad')
         .description('Analyze inter-repo dependencies')
         .argument('[workspace]', 'Workspace name')
-        .action(async (workspace) => {
-        await handleAnalyzeDeps(workspace);
+        .option('--json', 'Output as JSON (no interactive save)')
+        .action(async (workspace, opts) => {
+        await handleAnalyzeDeps(workspace, opts);
     });
 }
-async function handleAnalyzeDeps(workspaceArg) {
+async function handleAnalyzeDeps(workspaceArg, opts = {}) {
     try {
+        // JSON mode is non-interactive: require an explicit workspace rather than prompt.
+        if (opts.json && !workspaceArg) {
+            (0, output_1.outputJsonError)('analyze-deps --json requires a workspace name');
+            process.exit(1);
+        }
         const selectedWorkspace = await (0, command_helpers_1.resolveWorkspace)(workspaceArg);
         const workspacePath = path.join(config_1.WORKSPACES_DIR, selectedWorkspace);
         const metadata = await (0, workspace_meta_1.loadMetadata)(workspacePath);
         if (!metadata) {
-            (0, logger_1.logError)(`Workspace metadata not found for: ${selectedWorkspace}`);
+            if (opts.json)
+                (0, output_1.outputJsonError)(`Workspace metadata not found for: ${selectedWorkspace}`);
+            else
+                (0, logger_1.logError)(`Workspace metadata not found for: ${selectedWorkspace}`);
             process.exit(1);
         }
+        const repoNames = metadata.repositories.map(r => r.name);
+        if (opts.json) {
+            const analyses = await (0, dependency_analyzer_1.analyzeDependencies)(workspacePath, repoNames);
+            const cycles = (0, dependency_analyzer_1.detectCircularDependencies)(analyses);
+            const missing = new Set();
+            for (const [, a] of analyses)
+                for (const dep of a.missingDependencies)
+                    missing.add(dep);
+            (0, output_1.outputJson)({
+                workspace: selectedWorkspace,
+                repositories: Array.from(analyses.entries()).map(([name, a]) => ({
+                    name,
+                    dependencies: a.dependencies,
+                    dependents: a.dependents,
+                    missingDependencies: a.missingDependencies,
+                })),
+                circularDependencies: cycles,
+                missingRepositories: Array.from(missing),
+            });
+            return;
+        }
         (0, logger_1.logStep)(`Analyzing dependencies for workspace: ${(0, colors_1.colorize)(selectedWorkspace, 'cyan')}`);
         (0, logger_1.logInfo)('Scanning package.json, Dockerfile, and docker-compose.yml files...');
-        const repoNames = metadata.repositories.map(r => r.name);
         const analyses = await (0, dependency_analyzer_1.analyzeDependencies)(workspacePath, repoNames);
         displayDependencyAnalysis(analyses);
         const cycles = (0, dependency_analyzer_1.detectCircularDependencies)(analyses);
@@ -129,9 +159,13 @@ async function handleAnalyzeDeps(workspaceArg) {
         }
     }
     catch (error) {
-        (0, logger_1.logError)('Failed to analyze dependencies');
-        if (error instanceof Error) {
-            (0, logger_1.logError)(error.message);
+        if (opts.json) {
+            (0, output_1.outputJsonError)(error instanceof Error ? error.message : 'Failed to analyze dependencies');
+        }
+        else {
+            (0, logger_1.logError)('Failed to analyze dependencies');
+            if (error instanceof Error)
+                (0, logger_1.logError)(error.message);
         }
         process.exit(1);
     }

package/dist/commands/completion.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMPLETION_BINS = void 0;
+exports.generateCompletion = generateCompletion;
+exports.specsFromProgram = specsFromProgram;
+exports.registerCompletionCommand = registerCompletionCommand;
+const workspace_meta_1 = require("../utils/workspace-meta");
+const logger_1 = require("../utils/logger");
+/** Binaries that get completion registered (the CLI's bins). */
+exports.COMPLETION_BINS = ['nemus', 'nem'];
+/** Every token (name + aliases) that should complete as a subcommand. */
+function allTokens(cmds) {
+    return cmds.flatMap((c) => [c.name, ...c.aliases]);
+}
+/** Tokens (names + aliases) of the commands that take a workspace argument. */
+function workspaceTokens(cmds) {
+    return cmds.filter((c) => c.takesWorkspace).flatMap((c) => [c.name, ...c.aliases]);
+}
+/** Escape a description for a fish single-quoted string. */
+function fishDesc(s) {
+    return s.replace(/\n/g, ' ').replace(/'/g, "'\\''");
+}
+/**
+ * Generate a shell completion script. Pure (no I/O) so it's unit-tested. The
+ * generated script completes subcommands at position 1, and for a subcommand
+ * that takes a workspace it completes workspace names by calling back into the
+ * CLI: `<bin> completion --workspaces`. Dynamic values stay fresh without
+ * regenerating the script.
+ */
+function generateCompletion(shell, cmds, bins = exports.COMPLETION_BINS) {
+    const commands = allTokens(cmds).join(' ');
+    const wsCommands = workspaceTokens(cmds).join(' ');
+    if (shell === 'bash') {
+        return `# nemus bash completion. Install: nemus completion bash > /etc/bash_completion.d/nemus
+#   (or: nemus completion bash >> ~/.bashrc)
+_nemus_complete() {
+  local cur bin sub
+  # bash does not clear COMPREPLY between completions; reset so a stale result
+  # from a previous TAB can't leak when we return without setting it.
+  COMPREPLY=()
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  bin="\${COMP_WORDS[0]}"
+  local commands="${commands}"
+  local ws_commands="${wsCommands}"
+  if [ "\$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=( \$(compgen -W "\$commands" -- "\$cur") )
+    return 0
+  fi
+  if [ "\$COMP_CWORD" -eq 2 ]; then
+    sub="\${COMP_WORDS[1]}"
+    if [[ " \$ws_commands " == *" \$sub "* ]]; then
+      local names
+      names="\$("\$bin" completion --workspaces 2>/dev/null)"
+      COMPREPLY=( \$(compgen -W "\$names" -- "\$cur") )
+      return 0
+    fi
+  fi
+  return 0
+}
+${bins.map((b) => `complete -F _nemus_complete ${b}`).join('\n')}
+`;
+    }
+    if (shell === 'zsh') {
+        // Autoloaded form: save as a file named `_nemus` on your $fpath.
+        return `#compdef ${bins.join(' ')}
+# nemus zsh completion. Install: nemus completion zsh > "\${fpath[1]}/_nemus"
+local -a _nemus_commands
+_nemus_commands=(${allTokens(cmds).map((t) => `'${t}'`).join(' ')})
+local _nemus_ws_commands="${wsCommands}"
+if (( CURRENT == 2 )); then
+  compadd -- $_nemus_commands
+  return
+fi
+if (( CURRENT == 3 )); then
+  local sub=\${words[2]}
+  if [[ " $_nemus_ws_commands " == *" $sub "* ]]; then
+    local -a _nemus_names
+    _nemus_names=(\${(f)"$(\${words[1]} completion --workspaces 2>/dev/null)"})
+    compadd -- $_nemus_names
+  fi
+fi
+`;
+    }
+    // fish
+    const lines = ['# nemus fish completion. Install: nemus completion fish > ~/.config/fish/completions/nemus.fish'];
+    for (const bin of bins) {
+        lines.push(`complete -c ${bin} -f`);
+        for (const c of cmds) {
+            for (const tok of [c.name, ...c.aliases]) {
+                lines.push(`complete -c ${bin} -n __fish_use_subcommand -a '${tok}' -d '${fishDesc(c.description)}'`);
+            }
+        }
+        const wsToks = workspaceTokens(cmds).join(' ');
+        if (wsToks) {
+            lines.push(`complete -c ${bin} -n '__fish_seen_subcommand_from ${wsToks}' -a '(${bin} completion --workspaces)'`);
+        }
+    }
+    return lines.join('\n') + '\n';
+}
+/** Distill the program's top-level commands into CommandSpecs. */
+function specsFromProgram(program) {
+    return program.commands
+        .map((c) => {
+        const args = c.registeredArguments ?? [];
+        const firstArg = args[0]?.name?.();
+        return {
+            name: c.name(),
+            aliases: c.aliases(),
+            takesWorkspace: typeof firstArg === 'string' && firstArg.toLowerCase().includes('workspace'),
+            description: c.description() ?? '',
+        };
+    })
+        // The completion command itself and any hidden helper needn't clutter, but
+        // keeping them is harmless; only drop entries with no name.
+        .filter((s) => s.name);
+}
+function registerCompletionCommand(program) {
+    program
+        .command('completion [shell]')
+        .description('Output a shell completion script (bash|zsh|fish)')
+        .option('--workspaces', 'Print workspace names (used internally by completion scripts)')
+        .action(async (shell, opts) => {
+        // Data helper the generated scripts call back into.
+        if (opts.workspaces) {
+            try {
+                const workspaces = await (0, workspace_meta_1.listWorkspaces)(false);
+                for (const ws of workspaces)
+                    process.stdout.write(ws.name + '\n');
+            }
+            catch {
+                // Silent: completion must never error out the user's shell.
+            }
+            return;
+        }
+        const shells = ['bash', 'zsh', 'fish'];
+        if (!shell || !shells.includes(shell)) {
+            (0, logger_1.logError)(`completion: specify a shell — one of ${shells.join(', ')}`);
+            (0, logger_1.logError)('e.g. nemus completion bash');
+            process.exit(1);
+        }
+        process.stdout.write(generateCompletion(shell, specsFromProgram(program)));
+    });
+}

package/dist/commands/sessions.js

@@ -43,6 +43,7 @@ const fs = __importStar(require("fs/promises"));
 const claude_sessions_1 = require("../utils/claude-sessions");
 const workspace_meta_1 = require("../utils/workspace-meta");
 const logger_1 = require("../utils/logger");
+const output_1 = require("../utils/output");
 const colors_1 = require("../utils/colors");
 const inquirer_1 = __importDefault(require("inquirer"));
 const inquirer_autocomplete_prompt_1 = __importDefault(require("inquirer-autocomplete-prompt"));
@@ -55,14 +56,19 @@ function registerSessionsCommand(parent) {
         .command('sessions')
         .alias('ses')
         .description('Resume a Claude session in a workspace')
-        .action(async () => {
-        await handleSessions();
+        .option('--json', 'List sessions as JSON (no interactive resume)')
+        .action(async (opts) => {
+        await handleSessions(opts);
     });
 }
-async function handleSessions() {
+async function handleSessions(opts = {}) {
     try {
         const sessions = await (0, claude_sessions_1.getWorkspaceSessions)();
         if (sessions.length === 0) {
+            if (opts.json) {
+                (0, output_1.outputJson)({ count: 0, sessions: [] });
+                return;
+            }
             (0, logger_1.logInfo)('No workspace sessions found.');
             console.log('\nYou can create a workspace with: nemus create');
             console.log('Or navigate to one with: w go');
@@ -76,6 +82,22 @@ async function handleSessions() {
             const repoLabel = repoCount > 0 ? `${repoCount} repos` : 'no repos';
             return { session, repoLabel };
         });
+        // JSON mode: list sessions to stdout, no resume prompt / temp-file writes.
+        if (opts.json) {
+            (0, output_1.outputJson)({
+                count: items.length,
+                sessions: items.map(i => ({
+                    workspaceName: i.session.workspaceName,
+                    workspacePath: i.session.workspacePath,
+                    sessionId: i.session.sessionId,
+                    agentType: i.session.agentType ?? null,
+                    lastActive: i.session.lastActiveLabel,
+                    lastActiveAt: i.session.lastActiveAt.toISOString(),
+                    repoCount: workspaceMap.get(i.session.workspaceName)?.metadata?.repositories?.length ?? 0,
+                })),
+            });
+            return;
+        }
         const maxNameLen = Math.max(...items.map(i => i.session.workspaceName.length));
         console.log('');
         console.log((0, colors_1.colorize)('  Workspace Sessions', 'bright') + (0, colors_1.colorize)('  (sorted by last active)', 'dim'));
@@ -120,9 +142,14 @@ async function handleSessions() {
     catch (error) {
         if (error?.name === 'ExitPromptError')
             return;
-        (0, logger_1.logError)('Failed to list sessions');
-        if (error instanceof Error) {
-            (0, logger_1.logError)(error.message);
+        if (opts.json) {
+            (0, output_1.outputJsonError)(error instanceof Error ? error.message : 'Failed to list sessions');
+        }
+        else {
+            (0, logger_1.logError)('Failed to list sessions');
+            if (error instanceof Error) {
+                (0, logger_1.logError)(error.message);
+            }
         }
         process.exit(1);
     }

package/dist/commands/suite/index.js

@@ -49,9 +49,10 @@ function registerSuiteCommands(parent) {
     suite
         .command('list')
         .description('List all saved suites')
-        .action(async () => {
+        .option('--json', 'Output as JSON')
+        .action(async (opts) => {
         const { main } = await Promise.resolve().then(() => __importStar(require('./list')));
-        await main();
+        await main(opts);
     });
     suite
         .command('delete')

package/dist/commands/suite/list.js

@@ -4,13 +4,28 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.main = main;
 const suite_1 = require("../../utils/suite");
 const logger_1 = require("../../utils/logger");
+const output_1 = require("../../utils/output");
 const colors_1 = require("../../utils/colors");
-async function main() {
-    console.log('\n' + '='.repeat(60));
-    console.log((0, colors_1.colorize)('Saved Suites', 'bright'));
-    console.log('='.repeat(60) + '\n');
+async function main(opts = {}) {
     try {
         const suites = await (0, suite_1.listSuites)();
+        if (opts.json) {
+            (0, output_1.outputJson)({
+                count: suites.length,
+                suites: suites.map(s => ({
+                    name: s.name,
+                    description: s.description ?? null,
+                    repoCount: s.entries.length,
+                    entries: s.entries.map(e => ({ directoryName: e.directoryName, repoName: e.repoName })),
+                    createdAt: s.createdAt,
+                    updatedAt: s.updatedAt,
+                })),
+            });
+            return;
+        }
+        console.log('\n' + '='.repeat(60));
+        console.log((0, colors_1.colorize)('Saved Suites', 'bright'));
+        console.log('='.repeat(60) + '\n');
         if (suites.length === 0) {
             (0, logger_1.logInfo)('No suites found');
             console.log('\nCreate a new suite with:');
@@ -38,9 +53,13 @@ async function main() {
         console.log('='.repeat(60) + '\n');
     }
     catch (error) {
-        (0, logger_1.logError)('Failed to list suites');
-        if (error instanceof Error) {
-            (0, logger_1.logError)(error.message);
+        if (opts.json) {
+            (0, output_1.outputJsonError)(error instanceof Error ? error.message : 'Failed to list suites');
+        }
+        else {
+            (0, logger_1.logError)('Failed to list suites');
+            if (error instanceof Error)
+                (0, logger_1.logError)(error.message);
         }
         process.exit(1);
     }

package/dist/program.js

@@ -88,6 +88,7 @@ const ghq_status_1 = require("./commands/ghq-status");
 const save_context_1 = require("./commands/save-context");
 const migrate_1 = require("./commands/migrate");
 const report_bug_1 = require("./commands/report-bug");
+const completion_1 = require("./commands/completion");
 (0, create_1.registerCreateCommand)(exports.program);
 (0, list_1.registerListCommand)(exports.program);
 (0, update_1.registerUpdateCommand)(exports.program);
@@ -111,6 +112,7 @@ const report_bug_1 = require("./commands/report-bug");
 (0, save_context_1.registerSaveContextCommand)(exports.program);
 (0, migrate_1.registerMigrateCommand)(exports.program);
 (0, report_bug_1.registerReportBugCommand)(exports.program);
+(0, completion_1.registerCompletionCommand)(exports.program);
 // Register TUI (delegates to existing Ink/React implementation)
 exports.program
     .command('tui')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nemus-cli/nemus",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "workspaces": [
     "packages/*"
   ],

package/src/commands/analyze-deps.ts

@@ -9,6 +9,7 @@ import {
   updateWorkspaceMetadata,
 } from '../utils/dependency-analyzer';
 import { logError, logInfo, logStep, logSuccess } from '../utils/logger';
+import { outputJson, outputJsonError } from '../utils/output';
 import { colorize } from '../utils/colors';
 import inquirer from 'inquirer';
 import { resolveWorkspace } from '../utils/command-helpers';
@@ -42,26 +43,53 @@ export function registerAnalyzeDepsCommand(parent: Command) {
     .alias('ad')
     .description('Analyze inter-repo dependencies')
     .argument('[workspace]', 'Workspace name')
-    .action(async (workspace) => {
-      await handleAnalyzeDeps(workspace);
+    .option('--json', 'Output as JSON (no interactive save)')
+    .action(async (workspace, opts) => {
+      await handleAnalyzeDeps(workspace, opts);
     });
 }
 
-async function handleAnalyzeDeps(workspaceArg?: string) {
+async function handleAnalyzeDeps(workspaceArg?: string, opts: { json?: boolean } = {}) {
   try {
+    // JSON mode is non-interactive: require an explicit workspace rather than prompt.
+    if (opts.json && !workspaceArg) {
+      outputJsonError('analyze-deps --json requires a workspace name');
+      process.exit(1);
+    }
     const selectedWorkspace = await resolveWorkspace(workspaceArg);
     const workspacePath = path.join(WORKSPACES_DIR, selectedWorkspace);
     const metadata = await loadMetadata(workspacePath);
 
     if (!metadata) {
-      logError(`Workspace metadata not found for: ${selectedWorkspace}`);
+      if (opts.json) outputJsonError(`Workspace metadata not found for: ${selectedWorkspace}`);
+      else logError(`Workspace metadata not found for: ${selectedWorkspace}`);
       process.exit(1);
     }
 
+    const repoNames = metadata.repositories.map(r => r.name);
+
+    if (opts.json) {
+      const analyses = await analyzeDependencies(workspacePath, repoNames);
+      const cycles = detectCircularDependencies(analyses);
+      const missing = new Set<string>();
+      for (const [, a] of analyses) for (const dep of a.missingDependencies) missing.add(dep);
+      outputJson({
+        workspace: selectedWorkspace,
+        repositories: Array.from(analyses.entries()).map(([name, a]) => ({
+          name,
+          dependencies: a.dependencies,
+          dependents: a.dependents,
+          missingDependencies: a.missingDependencies,
+        })),
+        circularDependencies: cycles,
+        missingRepositories: Array.from(missing),
+      });
+      return;
+    }
+
     logStep(`Analyzing dependencies for workspace: ${colorize(selectedWorkspace, 'cyan')}`);
     logInfo('Scanning package.json, Dockerfile, and docker-compose.yml files...');
 
-    const repoNames = metadata.repositories.map(r => r.name);
     const analyses = await analyzeDependencies(workspacePath, repoNames);
 
     displayDependencyAnalysis(analyses);
@@ -110,9 +138,11 @@ async function handleAnalyzeDeps(workspaceArg?: string) {
       }
     }
   } catch (error) {
-    logError('Failed to analyze dependencies');
-    if (error instanceof Error) {
-      logError(error.message);
+    if (opts.json) {
+      outputJsonError(error instanceof Error ? error.message : 'Failed to analyze dependencies');
+    } else {
+      logError('Failed to analyze dependencies');
+      if (error instanceof Error) logError(error.message);
     }
     process.exit(1);
   }

package/src/commands/completion.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect } from 'vitest';
+import { Command } from 'commander';
+import { generateCompletion, specsFromProgram, CommandSpec } from './completion';
+
+const specs: CommandSpec[] = [
+  { name: 'list', aliases: ['l'], takesWorkspace: false, description: 'List workspaces' },
+  { name: 'status', aliases: ['st'], takesWorkspace: true, description: "Show a repo's git status" },
+  { name: 'doctor', aliases: ['doc'], takesWorkspace: true, description: 'Health checks' },
+];
+
+describe('generateCompletion — bash', () => {
+  const s = generateCompletion('bash', specs);
+  it('resets COMPREPLY, lists tokens, and registers both bins', () => {
+    expect(s).toContain('COMPREPLY=()'); // guards the stale-completion leak
+    expect(s).toContain('local commands="list l status st doctor doc"');
+    expect(s).toContain('local ws_commands="status st doctor doc"');
+    expect(s).toContain('complete -F _nemus_complete nemus');
+    expect(s).toContain('complete -F _nemus_complete nem');
+  });
+  it('calls back into the invoked bin for workspace names', () => {
+    expect(s).toContain('"$bin" completion --workspaces');
+  });
+});
+
+describe('generateCompletion — zsh', () => {
+  const s = generateCompletion('zsh', specs);
+  it('is an autoloadable #compdef script with the tokens + callback', () => {
+    expect(s.startsWith('#compdef nemus nem')).toBe(true);
+    expect(s).toContain("_nemus_commands=('list' 'l' 'status' 'st' 'doctor' 'doc')");
+    expect(s).toContain('_nemus_ws_commands="status st doctor doc"');
+    expect(s).toContain('completion --workspaces');
+  });
+});
+
+describe('generateCompletion — fish', () => {
+  const s = generateCompletion('fish', specs);
+  it('emits subcommand + workspace completions for both bins with escaped descriptions', () => {
+    expect(s).toContain("complete -c nemus -n __fish_use_subcommand -a 'list' -d 'List workspaces'");
+    expect(s).toContain("complete -c nem -n __fish_use_subcommand -a 'status'");
+    // apostrophe in the description is escaped for fish's single-quoted string
+    expect(s).toContain("Show a repo'\\''s git status");
+    expect(s).toContain("-n '__fish_seen_subcommand_from status st doctor doc' -a '(nemus completion --workspaces)'");
+  });
+});
+
+describe('specsFromProgram', () => {
+  it('detects workspace args + aliases from a commander program', () => {
+    const program = new Command();
+    program.command('list').alias('l').description('list');
+    program.command('status [workspace]').alias('st').description('status');
+    program.command('create').description('create');
+
+    const out = specsFromProgram(program);
+    const byName = Object.fromEntries(out.map((s) => [s.name, s]));
+    expect(byName.status.takesWorkspace).toBe(true);
+    expect(byName.status.aliases).toEqual(['st']);
+    expect(byName.list.takesWorkspace).toBe(false);
+    expect(byName.create.takesWorkspace).toBe(false);
+  });
+});

package/src/commands/completion.ts

@@ -0,0 +1,160 @@
+import { Command } from 'commander';
+import { listWorkspaces } from '../utils/workspace-meta';
+import { logError } from '../utils/logger';
+
+/** Binaries that get completion registered (the CLI's bins). */
+export const COMPLETION_BINS = ['nemus', 'nem'];
+
+export type Shell = 'bash' | 'zsh' | 'fish';
+
+/** One top-level command, distilled to what a completion script needs. */
+export interface CommandSpec {
+  name: string;
+  aliases: string[];
+  /** True if its first positional argument is a workspace name. */
+  takesWorkspace: boolean;
+  description: string;
+}
+
+/** Every token (name + aliases) that should complete as a subcommand. */
+function allTokens(cmds: CommandSpec[]): string[] {
+  return cmds.flatMap((c) => [c.name, ...c.aliases]);
+}
+
+/** Tokens (names + aliases) of the commands that take a workspace argument. */
+function workspaceTokens(cmds: CommandSpec[]): string[] {
+  return cmds.filter((c) => c.takesWorkspace).flatMap((c) => [c.name, ...c.aliases]);
+}
+
+/** Escape a description for a fish single-quoted string. */
+function fishDesc(s: string): string {
+  return s.replace(/\n/g, ' ').replace(/'/g, "'\\''");
+}
+
+/**
+ * Generate a shell completion script. Pure (no I/O) so it's unit-tested. The
+ * generated script completes subcommands at position 1, and for a subcommand
+ * that takes a workspace it completes workspace names by calling back into the
+ * CLI: `<bin> completion --workspaces`. Dynamic values stay fresh without
+ * regenerating the script.
+ */
+export function generateCompletion(shell: Shell, cmds: CommandSpec[], bins: string[] = COMPLETION_BINS): string {
+  const commands = allTokens(cmds).join(' ');
+  const wsCommands = workspaceTokens(cmds).join(' ');
+
+  if (shell === 'bash') {
+    return `# nemus bash completion. Install: nemus completion bash > /etc/bash_completion.d/nemus
+#   (or: nemus completion bash >> ~/.bashrc)
+_nemus_complete() {
+  local cur bin sub
+  # bash does not clear COMPREPLY between completions; reset so a stale result
+  # from a previous TAB can't leak when we return without setting it.
+  COMPREPLY=()
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  bin="\${COMP_WORDS[0]}"
+  local commands="${commands}"
+  local ws_commands="${wsCommands}"
+  if [ "\$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=( \$(compgen -W "\$commands" -- "\$cur") )
+    return 0
+  fi
+  if [ "\$COMP_CWORD" -eq 2 ]; then
+    sub="\${COMP_WORDS[1]}"
+    if [[ " \$ws_commands " == *" \$sub "* ]]; then
+      local names
+      names="\$("\$bin" completion --workspaces 2>/dev/null)"
+      COMPREPLY=( \$(compgen -W "\$names" -- "\$cur") )
+      return 0
+    fi
+  fi
+  return 0
+}
+${bins.map((b) => `complete -F _nemus_complete ${b}`).join('\n')}
+`;
+  }
+
+  if (shell === 'zsh') {
+    // Autoloaded form: save as a file named `_nemus` on your $fpath.
+    return `#compdef ${bins.join(' ')}
+# nemus zsh completion. Install: nemus completion zsh > "\${fpath[1]}/_nemus"
+local -a _nemus_commands
+_nemus_commands=(${allTokens(cmds).map((t) => `'${t}'`).join(' ')})
+local _nemus_ws_commands="${wsCommands}"
+if (( CURRENT == 2 )); then
+  compadd -- $_nemus_commands
+  return
+fi
+if (( CURRENT == 3 )); then
+  local sub=\${words[2]}
+  if [[ " $_nemus_ws_commands " == *" $sub "* ]]; then
+    local -a _nemus_names
+    _nemus_names=(\${(f)"$(\${words[1]} completion --workspaces 2>/dev/null)"})
+    compadd -- $_nemus_names
+  fi
+fi
+`;
+  }
+
+  // fish
+  const lines: string[] = ['# nemus fish completion. Install: nemus completion fish > ~/.config/fish/completions/nemus.fish'];
+  for (const bin of bins) {
+    lines.push(`complete -c ${bin} -f`);
+    for (const c of cmds) {
+      for (const tok of [c.name, ...c.aliases]) {
+        lines.push(`complete -c ${bin} -n __fish_use_subcommand -a '${tok}' -d '${fishDesc(c.description)}'`);
+      }
+    }
+    const wsToks = workspaceTokens(cmds).join(' ');
+    if (wsToks) {
+      lines.push(
+        `complete -c ${bin} -n '__fish_seen_subcommand_from ${wsToks}' -a '(${bin} completion --workspaces)'`,
+      );
+    }
+  }
+  return lines.join('\n') + '\n';
+}
+
+/** Distill the program's top-level commands into CommandSpecs. */
+export function specsFromProgram(program: Command): CommandSpec[] {
+  return program.commands
+    .map((c) => {
+      const args = (c as any).registeredArguments ?? [];
+      const firstArg: string | undefined = args[0]?.name?.();
+      return {
+        name: c.name(),
+        aliases: c.aliases(),
+        takesWorkspace: typeof firstArg === 'string' && firstArg.toLowerCase().includes('workspace'),
+        description: c.description() ?? '',
+      };
+    })
+    // The completion command itself and any hidden helper needn't clutter, but
+    // keeping them is harmless; only drop entries with no name.
+    .filter((s) => s.name);
+}
+
+export function registerCompletionCommand(program: Command) {
+  program
+    .command('completion [shell]')
+    .description('Output a shell completion script (bash|zsh|fish)')
+    .option('--workspaces', 'Print workspace names (used internally by completion scripts)')
+    .action(async (shell: string | undefined, opts: { workspaces?: boolean }) => {
+      // Data helper the generated scripts call back into.
+      if (opts.workspaces) {
+        try {
+          const workspaces = await listWorkspaces(false);
+          for (const ws of workspaces) process.stdout.write(ws.name + '\n');
+        } catch {
+          // Silent: completion must never error out the user's shell.
+        }
+        return;
+      }
+
+      const shells: Shell[] = ['bash', 'zsh', 'fish'];
+      if (!shell || !shells.includes(shell as Shell)) {
+        logError(`completion: specify a shell — one of ${shells.join(', ')}`);
+        logError('e.g. nemus completion bash');
+        process.exit(1);
+      }
+      process.stdout.write(generateCompletion(shell as Shell, specsFromProgram(program)));
+    });
+}

package/src/commands/sessions.ts

@@ -5,6 +5,7 @@ import * as fs from 'fs/promises';
 import { getWorkspaceSessions, WorkspaceSession } from '../utils/claude-sessions';
 import { listWorkspaces } from '../utils/workspace-meta';
 import { logError, logInfo } from '../utils/logger';
+import { outputJson, outputJsonError } from '../utils/output';
 import { colorize } from '../utils/colors';
 import inquirer from 'inquirer';
 import autocompletePrompt from 'inquirer-autocomplete-prompt';
@@ -20,16 +21,21 @@ export function registerSessionsCommand(parent: Command) {
     .command('sessions')
     .alias('ses')
     .description('Resume a Claude session in a workspace')
-    .action(async () => {
-      await handleSessions();
+    .option('--json', 'List sessions as JSON (no interactive resume)')
+    .action(async (opts) => {
+      await handleSessions(opts);
     });
 }
 
-async function handleSessions() {
+async function handleSessions(opts: { json?: boolean } = {}) {
   try {
     const sessions = await getWorkspaceSessions();
 
     if (sessions.length === 0) {
+      if (opts.json) {
+        outputJson({ count: 0, sessions: [] });
+        return;
+      }
       logInfo('No workspace sessions found.');
       console.log('\nYou can create a workspace with: nemus create');
       console.log('Or navigate to one with: w go');
@@ -46,6 +52,23 @@ async function handleSessions() {
       return { session, repoLabel };
     });
 
+    // JSON mode: list sessions to stdout, no resume prompt / temp-file writes.
+    if (opts.json) {
+      outputJson({
+        count: items.length,
+        sessions: items.map(i => ({
+          workspaceName: i.session.workspaceName,
+          workspacePath: i.session.workspacePath,
+          sessionId: i.session.sessionId,
+          agentType: i.session.agentType ?? null,
+          lastActive: i.session.lastActiveLabel,
+          lastActiveAt: i.session.lastActiveAt.toISOString(),
+          repoCount: workspaceMap.get(i.session.workspaceName)?.metadata?.repositories?.length ?? 0,
+        })),
+      });
+      return;
+    }
+
     const maxNameLen = Math.max(...items.map(i => i.session.workspaceName.length));
 
     console.log('');
@@ -92,8 +115,12 @@ async function handleSessions() {
     console.log(`\n${colorize('Resuming:', 'green')} ${session.workspaceName} (last active ${session.lastActiveLabel})`);
   } catch (error) {
     if ((error as any)?.name === 'ExitPromptError') return;
-    logError('Failed to list sessions');
-    if (error instanceof Error) { logError(error.message); }
+    if (opts.json) {
+      outputJsonError(error instanceof Error ? error.message : 'Failed to list sessions');
+    } else {
+      logError('Failed to list sessions');
+      if (error instanceof Error) { logError(error.message); }
+    }
     process.exit(1);
   }
 }

package/src/commands/suite/index.ts

@@ -17,9 +17,10 @@ export function registerSuiteCommands(parent: Command) {
   suite
     .command('list')
     .description('List all saved suites')
-    .action(async () => {
+    .option('--json', 'Output as JSON')
+    .action(async (opts) => {
       const { main } = await import('./list');
-      await main();
+      await main(opts);
     });
 
   suite

package/src/commands/suite/list.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+const { mockListSuites } = vi.hoisted(() => ({ mockListSuites: vi.fn() }));
+
+vi.mock('../../utils/suite', () => ({ listSuites: mockListSuites }));
+vi.mock('../../utils/logger', () => ({ logInfo: vi.fn(), logError: vi.fn() }));
+vi.mock('../../utils/colors', () => ({ colorize: (t: string) => t }));
+
+import { main } from './list';
+
+function makeSuite(name: string, entries = 1) {
+  return {
+    name,
+    description: `${name} desc`,
+    entries: Array.from({ length: entries }, (_, i) => ({ directoryName: `repo-${i}`, repoName: `repo-${i}` })),
+    createdAt: '2026-01-01T00:00:00.000Z',
+    updatedAt: '2026-01-02T00:00:00.000Z',
+  };
+}
+
+describe('suite list --json', () => {
+  let writeSpy: ReturnType<typeof vi.spyOn>;
+  beforeEach(() => {
+    vi.clearAllMocks();
+    writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+  });
+  afterEach(() => vi.restoreAllMocks());
+
+  it('emits one valid JSON document with normalized suites', async () => {
+    mockListSuites.mockResolvedValueOnce([makeSuite('fees', 2), makeSuite('platform', 1)]);
+    await main({ json: true });
+    expect(writeSpy).toHaveBeenCalledTimes(1);
+    const payload = JSON.parse(writeSpy.mock.calls[0][0] as string);
+    expect(payload.count).toBe(2);
+    expect(payload.suites[0]).toEqual({
+      name: 'fees',
+      description: 'fees desc',
+      repoCount: 2,
+      entries: [
+        { directoryName: 'repo-0', repoName: 'repo-0' },
+        { directoryName: 'repo-1', repoName: 'repo-1' },
+      ],
+      createdAt: '2026-01-01T00:00:00.000Z',
+      updatedAt: '2026-01-02T00:00:00.000Z',
+    });
+  });
+
+  it('empty list emits count 0 (no header/log noise)', async () => {
+    mockListSuites.mockResolvedValueOnce([]);
+    await main({ json: true });
+    const payload = JSON.parse(writeSpy.mock.calls[0][0] as string);
+    expect(payload).toEqual({ count: 0, suites: [] });
+  });
+
+  it('non-json mode does not write to the stdout data channel', async () => {
+    mockListSuites.mockResolvedValueOnce([makeSuite('fees')]);
+    await main();
+    // human output goes through console.log (mocked), not process.stdout.write
+    expect(writeSpy).not.toHaveBeenCalled();
+  });
+});

package/src/commands/suite/list.ts

@@ -2,16 +2,32 @@
 
 import { listSuites } from '../../utils/suite';
 import { logInfo, logError } from '../../utils/logger';
+import { outputJson, outputJsonError } from '../../utils/output';
 import { colorize } from '../../utils/colors';
 
-export async function main() {
-  console.log('\n' + '='.repeat(60));
-  console.log(colorize('Saved Suites', 'bright'));
-  console.log('='.repeat(60) + '\n');
-
+export async function main(opts: { json?: boolean } = {}) {
   try {
     const suites = await listSuites();
 
+    if (opts.json) {
+      outputJson({
+        count: suites.length,
+        suites: suites.map(s => ({
+          name: s.name,
+          description: s.description ?? null,
+          repoCount: s.entries.length,
+          entries: s.entries.map(e => ({ directoryName: e.directoryName, repoName: e.repoName })),
+          createdAt: s.createdAt,
+          updatedAt: s.updatedAt,
+        })),
+      });
+      return;
+    }
+
+    console.log('\n' + '='.repeat(60));
+    console.log(colorize('Saved Suites', 'bright'));
+    console.log('='.repeat(60) + '\n');
+
     if (suites.length === 0) {
       logInfo('No suites found');
       console.log('\nCreate a new suite with:');
@@ -43,9 +59,11 @@ export async function main() {
 
     console.log('='.repeat(60) + '\n');
   } catch (error) {
-    logError('Failed to list suites');
-    if (error instanceof Error) {
-      logError(error.message);
+    if (opts.json) {
+      outputJsonError(error instanceof Error ? error.message : 'Failed to list suites');
+    } else {
+      logError('Failed to list suites');
+      if (error instanceof Error) logError(error.message);
     }
     process.exit(1);
   }

package/src/program.ts

@@ -58,6 +58,7 @@ import { registerGhqStatusCommand } from './commands/ghq-status';
 import { registerSaveContextCommand } from './commands/save-context';
 import { registerMigrateCommand } from './commands/migrate';
 import { registerReportBugCommand } from './commands/report-bug';
+import { registerCompletionCommand } from './commands/completion';
 
 registerCreateCommand(program);
 registerListCommand(program);
@@ -82,6 +83,7 @@ registerGhqStatusCommand(program);
 registerSaveContextCommand(program);
 registerMigrateCommand(program);
 registerReportBugCommand(program);
+registerCompletionCommand(program);
 
 // Register TUI (delegates to existing Ink/React implementation)
 program