@nemus-cli/nemus 0.2.10 → 0.2.11

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.11] - 2026-08-27
+
+### Added
+
+- **`--json` output** for the read-only reporting commands `list`, `status`, and
+  `doctor`. Emits exactly one JSON document to stdout (no table, no interactive
+  prompt), so `nemus list --json | jq …` and CI/scripts get stable,
+  machine-readable output. `status --json` / `doctor --json` require an explicit
+  workspace name (they never prompt).
+
+### Changed
+
+- **stdout/stderr hygiene.** Diagnostic logs (info/success/error/warning/step)
+  now go to **stderr**, leaving **stdout** for a command's actual data. This is
+  what makes `--json` pipe cleanly and lets non-TTY consumers separate data from
+  progress. Human-facing table/plain output is unchanged on stdout.
+
 ## [0.2.10] - 2026-08-27
 
 ### Security
@@ -59,6 +76,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   (P4) a vendor-neutral **notification seam** — `Notifier` with Slack (incoming
   webhook) + generic webhook sinks (`notifierFromEnv`), wired into the CI-loop as
   optional out-of-band report-back.
+  **Code-host breadth:** the `GitForge` seam gained a dependency-free **GitLab**
+  implementation (`GitLabForge` — merge requests, commit statuses, MR notes;
+  self-managed via `GITLAB_API_URL`) alongside GitHub, plus a **forge registry**
+  (`createForge`/`registerForge`/`registeredForges` + `NEMUS_FORGE_HOST`) so a
+  run targets GitHub or GitLab — or a custom "bring your own backend" host
+  (Gitea, Bitbucket, …) — with no code change. Docs in `packages/cloud/README.md`.
+  **CI-loop + notifier wired into the agent image:** a second container entry
+  mode `NEMUS_MODE=fix-pr` (`runFixPr`/`parseFixPrEnv`, CLI `nemus-cloud fix-pr
+  --repo --pr --branch`) drives an *existing* PR to green with the bounded
+  CI-loop (P3) + optional Slack/webhook notifications (P4) — clone, checkout PR
+  head, `runCiLoop`, then write the same versioned `result.json` with
+  `mode: 'fix-pr'` + a compact `ci` summary. So P3+P4 are usable end-to-end in a
+  container, on GitHub or GitLab.
   Design: `docs/plans/2026-08-26-cloud-iac.md`.
 
 ## [0.2.9] - 2026-08-26

package/README.md

@@ -223,6 +223,21 @@ web              feature/x    ⚠ 2 modified  ↑1             2 files
 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:
+
+```bash
+nemus list --json | jq -r '.workspaces[].name'
+nemus status my-workspace --json | jq '.clean'
+nemus doctor my-workspace --json | jq '.score'
+```
+
+`status`/`doctor` with `--json` need an explicit workspace name (they never
+prompt).
+
 ### Suites (reusable repo collections)
 
 ```bash

package/dist/commands/doctor.js

@@ -39,6 +39,7 @@ const config_1 = require("../utils/config");
 const workspace_meta_1 = require("../utils/workspace-meta");
 const health_checks_1 = require("../utils/health-checks");
 const logger_1 = require("../utils/logger");
+const output_1 = require("../utils/output");
 const colors_1 = require("../utils/colors");
 const command_helpers_1 = require("../utils/command-helpers");
 const displayHealthCheck = (result) => {
@@ -96,19 +97,42 @@ function registerDoctorCommand(parent) {
         .alias('doc')
         .description('Run comprehensive health checks')
         .argument('[workspace]', 'Workspace name')
-        .action(async (workspace) => {
-        await handleDoctor(workspace);
+        .option('--json', 'Output as JSON')
+        .action(async (workspace, opts) => {
+        await handleDoctor(workspace, opts);
     });
 }
-async function handleDoctor(workspaceArg) {
+async function handleDoctor(workspaceArg, opts = {}) {
+    // In --json mode, failures are parseable JSON on stdout + exit 1; otherwise a
+    // human log on stderr. `process.exit(1)` stays the last statement so TS still
+    // narrows `metadata` to non-null below.
     try {
+        // JSON mode is non-interactive: require an explicit workspace rather than prompt.
+        if (opts.json && !workspaceArg) {
+            (0, output_1.outputJsonError)('doctor --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);
         }
+        if (opts.json) {
+            const results = await (0, health_checks_1.runAllHealthChecks)(workspacePath, metadata);
+            const score = (0, health_checks_1.calculateHealthScore)(results);
+            const overall = results.some(r => r.status === 'error')
+                ? 'error'
+                : results.some(r => r.status === 'warning')
+                    ? 'warning'
+                    : 'healthy';
+            (0, output_1.outputJson)({ workspace: selectedWorkspace, score, status: overall, checks: results });
+            return;
+        }
         (0, logger_1.logStep)(`Running health checks for workspace: ${(0, colors_1.colorize)(selectedWorkspace, 'cyan')}`);
         (0, logger_1.logInfo)('This may take a moment...');
         const results = await (0, health_checks_1.runAllHealthChecks)(workspacePath, metadata);
@@ -132,9 +156,13 @@ async function handleDoctor(workspaceArg) {
         }
     }
     catch (error) {
-        (0, logger_1.logError)('Failed to run health checks');
-        if (error instanceof Error) {
-            (0, logger_1.logError)(error.message);
+        if (opts.json) {
+            (0, output_1.outputJsonError)(error instanceof Error ? error.message : 'Failed to run health checks');
+        }
+        else {
+            (0, logger_1.logError)('Failed to run health checks');
+            if (error instanceof Error)
+                (0, logger_1.logError)(error.message);
         }
         process.exit(1);
     }

package/dist/commands/list.js

@@ -44,6 +44,7 @@ const fsPromises = __importStar(require("fs/promises"));
 const workspace_meta_1 = require("../utils/workspace-meta");
 const claude_sessions_1 = require("../utils/claude-sessions");
 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"));
@@ -57,6 +58,7 @@ function registerListCommand(parent) {
         .alias('l')
         .description('List workspaces and navigate to one')
         .option('-a, --archived', 'Show archived workspaces')
+        .option('--json', 'Output as JSON (no interactive selection)')
         .action(async (opts) => {
         await handleList(opts);
     });
@@ -72,6 +74,10 @@ async function handleList(opts) {
             (0, claude_sessions_1.getWorkspaceSessions)(),
         ]);
         if (workspaces.length === 0) {
+            if (opts.json) {
+                (0, output_1.outputJson)({ archived: showArchived, count: 0, workspaces: [] });
+                return;
+            }
             console.log('\n' + '='.repeat(60));
             console.log((0, colors_1.colorize)(title, 'bright'));
             console.log('='.repeat(60) + '\n');
@@ -108,6 +114,22 @@ async function handleList(opts) {
                 return 1;
             return new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime();
         });
+        // JSON mode: one document to stdout, no table, no interactive selection.
+        if (opts.json) {
+            (0, output_1.outputJson)({
+                archived: showArchived,
+                count: items.length,
+                workspaces: items.map(i => ({
+                    name: i.name,
+                    path: i.wsPath,
+                    repoCount: i.repoCount,
+                    createdAt: i.createdAt || null,
+                    lastActive: i.lastActiveLabel,
+                    hasSession: i.hasSession,
+                })),
+            });
+            return;
+        }
         console.log('');
         console.log((0, colors_1.colorize)('  ' + title, 'bright') + (0, colors_1.colorize)('  (sorted by last active)', 'dim'));
         console.log((0, colors_1.colorize)('  ' + '─'.repeat(54), 'dim'));
@@ -187,5 +209,6 @@ async function handleList(opts) {
 async function main() {
     const args = process.argv.slice(2);
     const archived = args.includes('--archived') || args.includes('-a');
-    await handleList({ archived });
+    const json = args.includes('--json');
+    await handleList({ archived, json });
 }

package/dist/commands/status.js

@@ -39,6 +39,7 @@ const config_1 = require("../utils/config");
 const workspace_meta_1 = require("../utils/workspace-meta");
 const git_status_1 = require("../utils/git-status");
 const logger_1 = require("../utils/logger");
+const output_1 = require("../utils/output");
 const colors_1 = require("../utils/colors");
 const command_helpers_1 = require("../utils/command-helpers");
 const displayStatusTable = (statuses) => {
@@ -109,29 +110,57 @@ function registerStatusCommand(parent) {
         .alias('st')
         .description('Show git status across all repos')
         .argument('[workspace]', 'Workspace name')
-        .action(async (workspace) => {
-        await handleStatus(workspace);
+        .option('--json', 'Output as JSON')
+        .action(async (workspace, opts) => {
+        await handleStatus(workspace, opts);
     });
 }
-async function handleStatus(workspaceArg) {
+async function handleStatus(workspaceArg, opts = {}) {
+    // In --json mode, failures are parseable JSON on stdout + exit 1; otherwise a
+    // human log on stderr. `process.exit(1)` stays the last statement so TS still
+    // narrows `metadata` to non-null below.
     try {
+        // JSON mode is non-interactive: require an explicit workspace rather than prompt.
+        if (opts.json && !workspaceArg) {
+            (0, output_1.outputJsonError)('status --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 repoDirectoryNames = metadata.repositories.map(r => r.directoryName);
+        if (opts.json) {
+            const statuses = await (0, git_status_1.getAllReposStatus)(workspacePath, repoDirectoryNames, 3);
+            (0, output_1.outputJson)({
+                workspace: selectedWorkspace,
+                path: workspacePath,
+                repoCount: statuses.length,
+                clean: statuses.every(s => s.clean),
+                repositories: statuses,
+            });
+            return;
+        }
         (0, logger_1.logStep)(`Checking status for workspace: ${(0, colors_1.colorize)(selectedWorkspace, 'cyan')}`);
         (0, logger_1.logInfo)(`Found ${metadata.repositories.length} repositories`);
-        const repoDirectoryNames = metadata.repositories.map(r => r.directoryName);
         const statuses = await (0, git_status_1.getAllReposStatus)(workspacePath, repoDirectoryNames, 3);
         displayStatusTable(statuses);
     }
     catch (error) {
-        (0, logger_1.logError)('Failed to check workspace status');
-        if (error instanceof Error) {
-            (0, logger_1.logError)(error.message);
+        const msg = error instanceof Error ? error.message : 'Failed to check workspace status';
+        if (opts.json) {
+            (0, output_1.outputJsonError)(msg);
+        }
+        else {
+            (0, logger_1.logError)('Failed to check workspace status');
+            if (error instanceof Error)
+                (0, logger_1.logError)(error.message);
         }
         process.exit(1);
     }

package/dist/utils/logger.js

@@ -2,6 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.logStep = exports.logWarning = exports.logError = exports.logSuccess = exports.logInfo = void 0;
 const colors_1 = require("./colors");
+// Diagnostics (info/success/error/warn/step) go to STDERR so stdout carries only
+// a command's actual data — required for clean `--json` piping (nemus list
+// --json | jq …) and for non-TTY consumers. Use `outputJson`/stdout for data.
+const logStream = (line) => console.error(line);
 const getTimestamp = () => {
     const now = new Date();
     return now.toLocaleTimeString('en-US', {
@@ -12,29 +16,29 @@ const getTimestamp = () => {
     });
 };
 const logInfo = (message) => {
-    console.log(`${colors_1.colors.gray}[${getTimestamp()}]${colors_1.colors.reset} ${message}`);
+    logStream(`${colors_1.colors.gray}[${getTimestamp()}]${colors_1.colors.reset} ${message}`);
 };
 exports.logInfo = logInfo;
 const logSuccess = (message) => {
-    console.log(`${colors_1.colors.gray}[${getTimestamp()}]${colors_1.colors.reset} ${(0, colors_1.colorize)('✓', 'green')} ${message}`);
+    logStream(`${colors_1.colors.gray}[${getTimestamp()}]${colors_1.colors.reset} ${(0, colors_1.colorize)('✓', 'green')} ${message}`);
 };
 exports.logSuccess = logSuccess;
 const logError = (message) => {
-    console.log(`${colors_1.colors.gray}[${getTimestamp()}]${colors_1.colors.reset} ${(0, colors_1.colorize)('✗', 'red')} ${message}`);
+    logStream(`${colors_1.colors.gray}[${getTimestamp()}]${colors_1.colors.reset} ${(0, colors_1.colorize)('✗', 'red')} ${message}`);
 };
 exports.logError = logError;
 const logWarning = (message) => {
-    console.log(`${colors_1.colors.gray}[${getTimestamp()}]${colors_1.colors.reset} ${(0, colors_1.colorize)('⚠', 'yellow')} ${message}`);
+    logStream(`${colors_1.colors.gray}[${getTimestamp()}]${colors_1.colors.reset} ${(0, colors_1.colorize)('⚠', 'yellow')} ${message}`);
 };
 exports.logWarning = logWarning;
 const logStep = (stepOrMessage, total, message) => {
     if (typeof stepOrMessage === 'string') {
         // Single parameter version: just a message
-        console.log(`${colors_1.colors.gray}[${getTimestamp()}]${colors_1.colors.reset} ${(0, colors_1.colorize)('▸', 'cyan')} ${stepOrMessage}`);
+        logStream(`${colors_1.colors.gray}[${getTimestamp()}]${colors_1.colors.reset} ${(0, colors_1.colorize)('▸', 'cyan')} ${stepOrMessage}`);
     }
     else {
         // Three parameter version: step, total, message
-        console.log(`${colors_1.colors.gray}[${getTimestamp()}]${colors_1.colors.reset} ${(0, colors_1.colorize)(`[${stepOrMessage}/${total}]`, 'cyan')} ${message}`);
+        logStream(`${colors_1.colors.gray}[${getTimestamp()}]${colors_1.colors.reset} ${(0, colors_1.colorize)(`[${stepOrMessage}/${total}]`, 'cyan')} ${message}`);
     }
 };
 exports.logStep = logStep;

package/dist/utils/output.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Machine-readable output helpers. The one rule: a command's DATA goes to
+ * stdout, diagnostics go to stderr (see logger.ts). In `--json` mode a command
+ * writes exactly one JSON document to stdout and nothing else, so it pipes
+ * cleanly into `jq` and is safe for scripts/CI.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.outputJson = outputJson;
+exports.outputJsonError = outputJsonError;
+/** Write one pretty-printed JSON document to stdout (data channel). */
+function outputJson(data) {
+    process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+}
+/**
+ * Emit a structured error as JSON to stdout for `--json` callers, so a script
+ * parsing stdout always gets a parseable object (`{ ok: false, error }`) rather
+ * than empty stdout + a human log line on stderr. The caller still signals
+ * failure with a non-zero exit code.
+ */
+function outputJsonError(message) {
+    outputJson({ ok: false, error: message });
+}

package/package.json

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

package/src/commands/doctor.ts

@@ -4,6 +4,7 @@ import { WORKSPACES_DIR } from '../utils/config';
 import { loadMetadata } from '../utils/workspace-meta';
 import { runAllHealthChecks, calculateHealthScore } from '../utils/health-checks';
 import { logError, logInfo, logStep, logSuccess, logWarning } from '../utils/logger';
+import { outputJson, outputJsonError } from '../utils/output';
 import { colorize } from '../utils/colors';
 import { HealthCheckResult } from '../types';
 import { resolveWorkspace } from '../utils/command-helpers';
@@ -59,22 +60,44 @@ export function registerDoctorCommand(parent: Command) {
     .alias('doc')
     .description('Run comprehensive health checks')
     .argument('[workspace]', 'Workspace name')
-    .action(async (workspace) => {
-      await handleDoctor(workspace);
+    .option('--json', 'Output as JSON')
+    .action(async (workspace, opts) => {
+      await handleDoctor(workspace, opts);
     });
 }
 
-async function handleDoctor(workspaceArg?: string) {
+async function handleDoctor(workspaceArg?: string, opts: { json?: boolean } = {}) {
+  // In --json mode, failures are parseable JSON on stdout + exit 1; otherwise a
+  // human log on stderr. `process.exit(1)` stays the last statement so TS still
+  // narrows `metadata` to non-null below.
   try {
+    // JSON mode is non-interactive: require an explicit workspace rather than prompt.
+    if (opts.json && !workspaceArg) {
+      outputJsonError('doctor --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);
     }
 
+    if (opts.json) {
+      const results = await runAllHealthChecks(workspacePath, metadata);
+      const score = calculateHealthScore(results);
+      const overall = results.some(r => r.status === 'error')
+        ? 'error'
+        : results.some(r => r.status === 'warning')
+          ? 'warning'
+          : 'healthy';
+      outputJson({ workspace: selectedWorkspace, score, status: overall, checks: results });
+      return;
+    }
+
     logStep(`Running health checks for workspace: ${colorize(selectedWorkspace, 'cyan')}`);
     logInfo('This may take a moment...');
 
@@ -101,9 +124,11 @@ async function handleDoctor(workspaceArg?: string) {
       logSuccess('All health checks passed! Your workspace is in good shape.');
     }
   } catch (error) {
-    logError('Failed to run health checks');
-    if (error instanceof Error) {
-      logError(error.message);
+    if (opts.json) {
+      outputJsonError(error instanceof Error ? error.message : 'Failed to run health checks');
+    } else {
+      logError('Failed to run health checks');
+      if (error instanceof Error) logError(error.message);
     }
     process.exit(1);
   }

package/src/commands/list.test.ts

@@ -196,6 +196,36 @@ describe('list-workspaces main', () => {
     expect(messages).toContainEqual(expect.stringContaining('ws-a'));
   });
 
+  it('--json: writes one valid JSON document to stdout and does not prompt', async () => {
+    const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+    process.argv = ['node', 'list-workspaces.js', '--json'];
+    mockListWorkspaces.mockResolvedValueOnce(makeWorkspaceList('ws-a', 'ws-b'));
+
+    await main();
+
+    expect(mockPrompt).not.toHaveBeenCalled();
+    expect(writeSpy).toHaveBeenCalledTimes(1);
+    const payload = JSON.parse(writeSpy.mock.calls[0][0] as string);
+    expect(payload.count).toBe(2);
+    expect(payload.workspaces.map((w: any) => w.name).sort()).toEqual(['ws-a', 'ws-b']);
+    expect(payload.workspaces[0]).toMatchObject({ repoCount: 1, hasSession: false });
+    writeSpy.mockRestore();
+  });
+
+  it('--json: empty list emits count 0, no prompt, no log noise', async () => {
+    const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+    process.argv = ['node', 'list-workspaces.js', '--json'];
+    mockListWorkspaces.mockResolvedValueOnce([]);
+
+    await main();
+
+    expect(logInfo).not.toHaveBeenCalled();
+    expect(mockPrompt).not.toHaveBeenCalled();
+    const payload = JSON.parse(writeSpy.mock.calls[0][0] as string);
+    expect(payload).toEqual({ archived: false, count: 0, workspaces: [] });
+    writeSpy.mockRestore();
+  });
+
   it('sorts workspaces with sessions before those without', async () => {
     mockListWorkspaces.mockResolvedValueOnce(makeWorkspaceList('no-session', 'has-session'));
     mockGetWorkspaceSessions.mockResolvedValueOnce([{

package/src/commands/list.ts

@@ -5,6 +5,7 @@ import * as fsPromises from 'fs/promises';
 import { listWorkspaces } from '../utils/workspace-meta';
 import { getWorkspaceSessions } from '../utils/claude-sessions';
 import { logInfo, logError } from '../utils/logger';
+import { outputJson } from '../utils/output';
 import { colorize } from '../utils/colors';
 import inquirer from 'inquirer';
 import autocompletePrompt from 'inquirer-autocomplete-prompt';
@@ -31,12 +32,13 @@ export function registerListCommand(parent: Command) {
     .alias('l')
     .description('List workspaces and navigate to one')
     .option('-a, --archived', 'Show archived workspaces')
+    .option('--json', 'Output as JSON (no interactive selection)')
     .action(async (opts) => {
       await handleList(opts);
     });
 }
 
-async function handleList(opts: { archived?: boolean }) {
+async function handleList(opts: { archived?: boolean; json?: boolean }) {
   const showArchived = opts.archived ?? false;
   const title = showArchived ? 'Archived Workspaces' : 'Existing Workspaces';
 
@@ -49,6 +51,10 @@ async function handleList(opts: { archived?: boolean }) {
     ]);
 
     if (workspaces.length === 0) {
+      if (opts.json) {
+        outputJson({ archived: showArchived, count: 0, workspaces: [] });
+        return;
+      }
       console.log('\n' + '='.repeat(60));
       console.log(colorize(title, 'bright'));
       console.log('='.repeat(60) + '\n');
@@ -85,6 +91,23 @@ async function handleList(opts: { archived?: boolean }) {
       return new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime();
     });
 
+    // JSON mode: one document to stdout, no table, no interactive selection.
+    if (opts.json) {
+      outputJson({
+        archived: showArchived,
+        count: items.length,
+        workspaces: items.map(i => ({
+          name: i.name,
+          path: i.wsPath,
+          repoCount: i.repoCount,
+          createdAt: i.createdAt || null,
+          lastActive: i.lastActiveLabel,
+          hasSession: i.hasSession,
+        })),
+      });
+      return;
+    }
+
     console.log('');
     console.log(colorize('  ' + title, 'bright') + colorize('  (sorted by last active)', 'dim'));
     console.log(colorize('  ' + '─'.repeat(54), 'dim'));
@@ -172,5 +195,6 @@ async function handleList(opts: { archived?: boolean }) {
 export async function main() {
   const args = process.argv.slice(2);
   const archived = args.includes('--archived') || args.includes('-a');
-  await handleList({ archived });
+  const json = args.includes('--json');
+  await handleList({ archived, json });
 }

package/src/commands/status.ts

@@ -4,6 +4,7 @@ import { WORKSPACES_DIR } from '../utils/config';
 import { loadMetadata } from '../utils/workspace-meta';
 import { getAllReposStatus } from '../utils/git-status';
 import { logError, logInfo, logStep } from '../utils/logger';
+import { outputJson, outputJsonError } from '../utils/output';
 import { colorize } from '../utils/colors';
 import { resolveWorkspace } from '../utils/command-helpers';
 
@@ -78,33 +79,59 @@ export function registerStatusCommand(parent: Command) {
     .alias('st')
     .description('Show git status across all repos')
     .argument('[workspace]', 'Workspace name')
-    .action(async (workspace) => {
-      await handleStatus(workspace);
+    .option('--json', 'Output as JSON')
+    .action(async (workspace, opts) => {
+      await handleStatus(workspace, opts);
     });
 }
 
-async function handleStatus(workspaceArg?: string) {
+async function handleStatus(workspaceArg?: string, opts: { json?: boolean } = {}) {
+  // In --json mode, failures are parseable JSON on stdout + exit 1; otherwise a
+  // human log on stderr. `process.exit(1)` stays the last statement so TS still
+  // narrows `metadata` to non-null below.
   try {
+    // JSON mode is non-interactive: require an explicit workspace rather than prompt.
+    if (opts.json && !workspaceArg) {
+      outputJsonError('status --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 repoDirectoryNames = metadata.repositories.map(r => r.directoryName);
+
+    if (opts.json) {
+      const statuses = await getAllReposStatus(workspacePath, repoDirectoryNames, 3);
+      outputJson({
+        workspace: selectedWorkspace,
+        path: workspacePath,
+        repoCount: statuses.length,
+        clean: statuses.every(s => s.clean),
+        repositories: statuses,
+      });
+      return;
+    }
+
     logStep(`Checking status for workspace: ${colorize(selectedWorkspace, 'cyan')}`);
     logInfo(`Found ${metadata.repositories.length} repositories`);
 
-    const repoDirectoryNames = metadata.repositories.map(r => r.directoryName);
     const statuses = await getAllReposStatus(workspacePath, repoDirectoryNames, 3);
 
     displayStatusTable(statuses);
   } catch (error) {
-    logError('Failed to check workspace status');
-    if (error instanceof Error) {
-      logError(error.message);
+    const msg = error instanceof Error ? error.message : 'Failed to check workspace status';
+    if (opts.json) {
+      outputJsonError(msg);
+    } else {
+      logError('Failed to check workspace status');
+      if (error instanceof Error) logError(error.message);
     }
     process.exit(1);
   }

package/src/utils/logger.ts

@@ -1,5 +1,10 @@
 import { colors, colorize } from './colors';
 
+// Diagnostics (info/success/error/warn/step) go to STDERR so stdout carries only
+// a command's actual data — required for clean `--json` piping (nemus list
+// --json | jq …) and for non-TTY consumers. Use `outputJson`/stdout for data.
+const logStream = (line: string): void => console.error(line);
+
 const getTimestamp = (): string => {
   const now = new Date();
   return now.toLocaleTimeString('en-US', {
@@ -11,27 +16,27 @@ const getTimestamp = (): string => {
 };
 
 export const logInfo = (message: string): void => {
-  console.log(`${colors.gray}[${getTimestamp()}]${colors.reset} ${message}`);
+  logStream(`${colors.gray}[${getTimestamp()}]${colors.reset} ${message}`);
 };
 
 export const logSuccess = (message: string): void => {
-  console.log(`${colors.gray}[${getTimestamp()}]${colors.reset} ${colorize('✓', 'green')} ${message}`);
+  logStream(`${colors.gray}[${getTimestamp()}]${colors.reset} ${colorize('✓', 'green')} ${message}`);
 };
 
 export const logError = (message: string): void => {
-  console.log(`${colors.gray}[${getTimestamp()}]${colors.reset} ${colorize('✗', 'red')} ${message}`);
+  logStream(`${colors.gray}[${getTimestamp()}]${colors.reset} ${colorize('✗', 'red')} ${message}`);
 };
 
 export const logWarning = (message: string): void => {
-  console.log(`${colors.gray}[${getTimestamp()}]${colors.reset} ${colorize('⚠', 'yellow')} ${message}`);
+  logStream(`${colors.gray}[${getTimestamp()}]${colors.reset} ${colorize('⚠', 'yellow')} ${message}`);
 };
 
 export const logStep = (stepOrMessage: number | string, total?: number, message?: string): void => {
   if (typeof stepOrMessage === 'string') {
     // Single parameter version: just a message
-    console.log(`${colors.gray}[${getTimestamp()}]${colors.reset} ${colorize('▸', 'cyan')} ${stepOrMessage}`);
+    logStream(`${colors.gray}[${getTimestamp()}]${colors.reset} ${colorize('▸', 'cyan')} ${stepOrMessage}`);
   } else {
     // Three parameter version: step, total, message
-    console.log(`${colors.gray}[${getTimestamp()}]${colors.reset} ${colorize(`[${stepOrMessage}/${total}]`, 'cyan')} ${message}`);
+    logStream(`${colors.gray}[${getTimestamp()}]${colors.reset} ${colorize(`[${stepOrMessage}/${total}]`, 'cyan')} ${message}`);
   }
 };

package/src/utils/output.test.ts

@@ -0,0 +1,36 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { outputJson, outputJsonError } from './output';
+
+function captureStdout(): { calls: string[]; restore: () => void } {
+  const calls: string[] = [];
+  const spy = vi.spyOn(process.stdout, 'write').mockImplementation((chunk: any) => {
+    calls.push(String(chunk));
+    return true;
+  });
+  return { calls, restore: () => spy.mockRestore() };
+}
+
+describe('outputJson', () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it('writes exactly one pretty JSON document + trailing newline to stdout', () => {
+    const { calls, restore } = captureStdout();
+    outputJson({ a: 1, b: ['x', 'y'] });
+    restore();
+    expect(calls).toHaveLength(1);
+    expect(calls[0].endsWith('\n')).toBe(true);
+    expect(calls[0]).toBe(JSON.stringify({ a: 1, b: ['x', 'y'] }, null, 2) + '\n');
+    expect(JSON.parse(calls[0])).toEqual({ a: 1, b: ['x', 'y'] });
+  });
+});
+
+describe('outputJsonError', () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it('emits a parseable { ok:false, error } object to stdout', () => {
+    const { calls, restore } = captureStdout();
+    outputJsonError('boom');
+    restore();
+    expect(JSON.parse(calls[0])).toEqual({ ok: false, error: 'boom' });
+  });
+});

package/src/utils/output.ts

@@ -0,0 +1,21 @@
+/**
+ * Machine-readable output helpers. The one rule: a command's DATA goes to
+ * stdout, diagnostics go to stderr (see logger.ts). In `--json` mode a command
+ * writes exactly one JSON document to stdout and nothing else, so it pipes
+ * cleanly into `jq` and is safe for scripts/CI.
+ */
+
+/** Write one pretty-printed JSON document to stdout (data channel). */
+export function outputJson(data: unknown): void {
+  process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+}
+
+/**
+ * Emit a structured error as JSON to stdout for `--json` callers, so a script
+ * parsing stdout always gets a parseable object (`{ ok: false, error }`) rather
+ * than empty stdout + a human log line on stderr. The caller still signals
+ * failure with a non-zero exit code.
+ */
+export function outputJsonError(message: string): void {
+  outputJson({ ok: false, error: message });
+}