@nemus-cli/nemus 0.2.10 → 0.2.12

package/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- **`--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 +89,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,26 @@ web              feature/x    ⚠ 2 modified  ↑1             2 files
 shared-lib       main         ✓ Clean       ↓3             -
 ```
 
+### Scripting: `--json`
+
+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'
+```
+
+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.
+
 ### Suites (reusable repo collections)
 
 ```bash

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/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/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/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/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/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.12",
   "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/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/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/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/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/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 });
+}