@nemus-cli/nemus 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-09-02
+
+### Added
+
+- **Shell completions now cover second-level subcommands and value arguments.**
+  `nemus config <TAB>` completes `get/set/unset/list/path/edit`, `nemus config
+  set <TAB>` completes the config **keys**, and `nemus reflect <TAB>` completes
+  `history/show` — across bash, zsh, and fish. Subcommands are auto-derived from
+  the command tree (so `suite`/`branch`/`cache`/`mcp` are covered too). (#73)
+- **`nemus completion` infers the shell from `$SHELL`** when no argument is
+  given (`nemus completion` → emits your shell's script). An explicit
+  `bash|zsh|fish` still wins; an unknown/invalid value errors as before. (#75)
+
+## [0.12.0] - 2026-09-02
+
+### Added
+
+- **`nemus version` subcommand** — a companion to the `-V/--version` flag for
+  people who type `nemus version`. `--json` additionally reports the Node.js
+  version, platform, and arch (handy for bug reports), as a single JSON document
+  to stdout. (#74)
+- **`NEMUS_NO_UPDATE_CHECK`** — opt out of the background "update available"
+  check entirely (no cache read, no network). Also honors the de-facto
+  `NO_UPDATE_NOTIFIER`. An explicit falsey value (`0`/`false`/empty) does not
+  disable it. Documented in the README env-var table. (#76)
+
 ## [0.11.0] - 2026-09-02
 
 ### Added

package/README.md

@@ -288,6 +288,7 @@ Everything Nemus reads from the environment (all optional):
 | `NEMUS_JUDGE_TIMEOUT_MS` | Timeout for the `reflect` judge call. |
 | `NEMUS_BUG_REPORT_REPO` | Repo that `report-bug` files issues against. |
 | `NEMUS_SKIP_CONFIGURE` | Skip the one-time post-install `configure` prompt. |
+| `NEMUS_NO_UPDATE_CHECK` | Disable the background "update available" check (also honors `NO_UPDATE_NOTIFIER`). |
 | `WORKSPACE_CLONE_TIMEOUT_MS` | Git clone timeout (default 15 min). |
 | `NO_COLOR` / `FORCE_COLOR` | Disable / force ANSI color (see [Global flags](#global-flags)). |
 | `VISUAL` / `EDITOR` | Editor launched by `nemus config edit`. |

package/dist/commands/completion.js

@@ -1,13 +1,28 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.COMPLETION_BINS = void 0;
+exports.SHELLS = exports.COMPLETION_BINS = void 0;
+exports.detectShell = detectShell;
 exports.generateCompletion = generateCompletion;
 exports.specsFromProgram = specsFromProgram;
 exports.registerCompletionCommand = registerCompletionCommand;
 const workspace_meta_1 = require("../utils/workspace-meta");
 const logger_1 = require("../utils/logger");
+const config_schema_1 = require("../utils/config-schema");
 /** Binaries that get completion registered (the CLI's bins). */
 exports.COMPLETION_BINS = ['nemus', 'nem'];
+exports.SHELLS = ['bash', 'zsh', 'fish'];
+/** Commands whose subcommands are positional args (not nested commander commands). */
+const POSITIONAL_SUBCOMMANDS = { reflect: ['history', 'show'] };
+/**
+ * Infer a shell from a `$SHELL`-style path (e.g. `/bin/zsh` -> `zsh`). Returns
+ * null for an unknown/empty value. Pure + exported for testing.
+ */
+function detectShell(shellPath) {
+    if (!shellPath)
+        return null;
+    const base = shellPath.trim().split('/').pop()?.toLowerCase() ?? '';
+    return exports.SHELLS.find((s) => s === base) ?? null;
+}
 /** Every token (name + aliases) that should complete as a subcommand. */
 function allTokens(cmds) {
     return cmds.flatMap((c) => [c.name, ...c.aliases]);
@@ -16,23 +31,46 @@ function allTokens(cmds) {
 function workspaceTokens(cmds) {
     return cmds.filter((c) => c.takesWorkspace).flatMap((c) => [c.name, ...c.aliases]);
 }
+/** All tokens (name + aliases) that route to a given command spec. */
+function cmdTokens(c) {
+    return [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.
+ * generated script completes, in order: top-level commands (position 1); then
+ * either workspace names (for workspace-scoped commands) or a command's own
+ * subcommands (position 2); then value completions like `config` keys
+ * (position 3). Workspace names stay dynamic via a callback into
+ * `<bin> completion --workspaces`.
  */
 function generateCompletion(shell, cmds, bins = exports.COMPLETION_BINS) {
     const commands = allTokens(cmds).join(' ');
     const wsCommands = workspaceTokens(cmds).join(' ');
+    const withSubs = cmds.filter((c) => c.subcommands && c.subcommands.length);
+    const withArgVals = cmds.filter((c) => c.argValues && c.argValues.values.length);
     if (shell === 'bash') {
+        const subArms = withSubs
+            .map((c) => `    ${cmdTokens(c).join('|')}) echo "${c.subcommands.join(' ')}" ;;`)
+            .join('\n');
+        const argArms = withArgVals
+            .map((c) => `    ${cmdTokens(c).join('|')}) case "$2" in ${c.argValues.after.join('|')}) echo "${c.argValues.values.join(' ')}" ;; esac ;;`)
+            .join('\n');
         return `# nemus bash completion. Install: nemus completion bash > /etc/bash_completion.d/nemus
 #   (or: nemus completion bash >> ~/.bashrc)
+_nemus_subcmds() {
+  case "$1" in
+${subArms}
+  esac
+}
+_nemus_argvals() {
+  case "$1" in
+${argArms}
+  esac
+}
 _nemus_complete() {
   local cur bin sub
   # bash does not clear COMPREPLY between completions; reset so a stale result
@@ -54,6 +92,20 @@ _nemus_complete() {
       COMPREPLY=( \$(compgen -W "\$names" -- "\$cur") )
       return 0
     fi
+    local subs
+    subs="\$(_nemus_subcmds "\$sub")"
+    if [ -n "\$subs" ]; then
+      COMPREPLY=( \$(compgen -W "\$subs" -- "\$cur") )
+    fi
+    return 0
+  fi
+  if [ "\$COMP_CWORD" -eq 3 ]; then
+    local vals
+    vals="\$(_nemus_argvals "\${COMP_WORDS[1]}" "\${COMP_WORDS[2]}")"
+    if [ -n "\$vals" ]; then
+      COMPREPLY=( \$(compgen -W "\$vals" -- "\$cur") )
+    fi
+    return 0
   fi
   return 0
 }
@@ -61,6 +113,12 @@ ${bins.map((b) => `complete -F _nemus_complete ${b}`).join('\n')}
 `;
     }
     if (shell === 'zsh') {
+        const subArms = withSubs
+            .map((c) => `      ${cmdTokens(c).join('|')}) compadd -- ${c.subcommands.join(' ')} ;;`)
+            .join('\n');
+        const argArms = withArgVals
+            .map((c) => `      ${cmdTokens(c).join('|')}) case \${words[3]} in ${c.argValues.after.join('|')}) compadd -- ${c.argValues.values.join(' ')} ;; esac ;;`)
+            .join('\n');
         // 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"
@@ -77,7 +135,17 @@ if (( CURRENT == 3 )); then
     local -a _nemus_names
     _nemus_names=(\${(f)"$(\${words[1]} completion --workspaces 2>/dev/null)"})
     compadd -- $_nemus_names
+    return
   fi
+  case $sub in
+${subArms}
+  esac
+  return
+fi
+if (( CURRENT == 4 )); then
+  case \${words[2]} in
+${argArms}
+  esac
 fi
 `;
     }
@@ -86,7 +154,7 @@ fi
     for (const bin of bins) {
         lines.push(`complete -c ${bin} -f`);
         for (const c of cmds) {
-            for (const tok of [c.name, ...c.aliases]) {
+            for (const tok of cmdTokens(c)) {
                 lines.push(`complete -c ${bin} -n __fish_use_subcommand -a '${tok}' -d '${fishDesc(c.description)}'`);
             }
         }
@@ -94,6 +162,14 @@ fi
         if (wsToks) {
             lines.push(`complete -c ${bin} -n '__fish_seen_subcommand_from ${wsToks}' -a '(${bin} completion --workspaces)'`);
         }
+        // Second-level subcommands.
+        for (const c of withSubs) {
+            lines.push(`complete -c ${bin} -n '__fish_seen_subcommand_from ${cmdTokens(c).join(' ')}' -a '${c.subcommands.join(' ')}'`);
+        }
+        // Third-level value completions (e.g. config keys after get/set/unset).
+        for (const c of withArgVals) {
+            lines.push(`complete -c ${bin} -n '__fish_seen_subcommand_from ${cmdTokens(c).join(' ')}; and __fish_seen_subcommand_from ${c.argValues.after.join(' ')}' -a '${c.argValues.values.join(' ')}'`);
+        }
     }
     return lines.join('\n') + '\n';
 }
@@ -103,11 +179,19 @@ function specsFromProgram(program) {
         .map((c) => {
         const args = c.registeredArguments ?? [];
         const firstArg = args[0]?.name?.();
+        const name = c.name();
+        // Nested commander subcommands (config/suite/branch/cache/mcp), else a
+        // manual override for commands whose subcommands are positional (reflect).
+        const nested = c.commands.flatMap((s) => [s.name(), ...s.aliases()]).filter(Boolean);
+        const subcommands = nested.length ? nested : POSITIONAL_SUBCOMMANDS[name];
+        const argValues = name === 'config' ? { after: ['get', 'set', 'unset'], values: [...config_schema_1.CONFIG_KEYS] } : undefined;
         return {
-            name: c.name(),
+            name,
             aliases: c.aliases(),
             takesWorkspace: typeof firstArg === 'string' && firstArg.toLowerCase().includes('workspace'),
             description: c.description() ?? '',
+            ...(subcommands ? { subcommands } : {}),
+            ...(argValues ? { argValues } : {}),
         };
     })
         // The completion command itself and any hidden helper needn't clutter, but
@@ -117,7 +201,7 @@ function specsFromProgram(program) {
 function registerCompletionCommand(program) {
     program
         .command('completion [shell]')
-        .description('Output a shell completion script (bash|zsh|fish)')
+        .description('Output a shell completion script (bash|zsh|fish; inferred from $SHELL if omitted)')
         .option('--workspaces', 'Print workspace names (used internally by completion scripts)')
         .action(async (shell, opts) => {
         // Data helper the generated scripts call back into.
@@ -132,12 +216,22 @@ function registerCompletionCommand(program) {
             }
             return;
         }
-        const shells = ['bash', 'zsh', 'fish'];
-        if (!shell || !shells.includes(shell)) {
-            (0, logger_1.logError)(`completion: specify a shell — one of ${shells.join(', ')}`);
+        // An explicit argument wins; only fall back to $SHELL when none is given
+        // (an invalid explicit arg is an error, not a reason to guess).
+        let target = null;
+        if (shell) {
+            target = exports.SHELLS.includes(shell) ? shell : null;
+        }
+        else {
+            target = detectShell(process.env.SHELL);
+            if (target)
+                (0, logger_1.logInfo)(`completion: no shell given — using ${target} (from $SHELL)`);
+        }
+        if (!target) {
+            (0, logger_1.logError)(`completion: specify a shell — one of ${exports.SHELLS.join(', ')}`);
             (0, logger_1.logError)('e.g. nemus completion bash');
             process.exit(1);
         }
-        process.stdout.write(generateCompletion(shell, specsFromProgram(program)));
+        process.stdout.write(generateCompletion(target, specsFromProgram(program)));
     });
 }

package/dist/commands/version.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildVersionInfo = buildVersionInfo;
+exports.registerVersionCommand = registerVersionCommand;
+const output_1 = require("../utils/output");
+/**
+ * Build the version payload. Pure and process-injectable so the JSON shape is
+ * unit-testable without reading the real runtime.
+ */
+function buildVersionInfo(version, proc = process) {
+    return {
+        version,
+        node: proc.versions.node,
+        platform: proc.platform,
+        arch: proc.arch,
+    };
+}
+/**
+ * `nemus version` — a subcommand companion to the `-V/--version` flag, for
+ * people who type `nemus version`. `--json` also reports the Node/OS runtime
+ * (handy for bug reports), emitting a single JSON document to stdout.
+ */
+function registerVersionCommand(program, version) {
+    program
+        .command('version')
+        .description('Print the Nemus version (with --json for version + runtime info)')
+        .option('--json', 'Output version + runtime info as JSON')
+        .action((opts) => {
+        const info = buildVersionInfo(version);
+        if (opts.json) {
+            (0, output_1.outputJson)(info);
+        }
+        else {
+            process.stdout.write(`nemus ${info.version}\n`);
+        }
+    });
+}

package/dist/program.js

@@ -40,6 +40,7 @@ const fs = __importStar(require("fs"));
 const colors_1 = require("./utils/colors");
 const banner_1 = require("./utils/banner");
 const global_flags_1 = require("./utils/global-flags");
+const version_1 = require("./commands/version");
 // Read version from package.json
 const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
 // --no-color must be applied BEFORE commander parses so it reaches the help
@@ -66,6 +67,7 @@ exports.program
 // also pre-scanned above.
 exports.program.hook('preAction', () => (0, global_flags_1.applyGlobalFlags)(exports.program.opts()));
 // Register top-level commands
+(0, version_1.registerVersionCommand)(exports.program, pkg.version);
 const create_1 = require("./commands/create");
 const list_1 = require("./commands/list");
 const update_1 = require("./commands/update");

package/dist/utils/version-check.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.checkForUpdate = checkForUpdate;
+exports.updateCheckDisabled = updateCheckDisabled;
 const fs = __importStar(require("fs/promises"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
@@ -89,6 +90,11 @@ async function fetchLatestVersion() {
  * This is designed to be non-blocking and best-effort — failures are silent.
  */
 async function checkForUpdate() {
+    // Opt-out: skip the check entirely (no cache read, no network) when the user
+    // asks for it. NEMUS_NO_UPDATE_CHECK is ours; NO_UPDATE_NOTIFIER is the
+    // de-facto convention several Node CLIs honor.
+    if (updateCheckDisabled(process.env))
+        return null;
     try {
         const currentVersion = (0, config_1.getPackageVersion)();
         const cache = await loadCache();
@@ -116,6 +122,15 @@ async function checkForUpdate() {
         return null;
     }
 }
+/**
+ * Whether the update check is opted out via env. A value is "set" unless it is
+ * empty or an explicit falsey token (`0`/`false`), so `NEMUS_NO_UPDATE_CHECK=0`
+ * does NOT disable the check. Pure + exported for testing.
+ */
+function updateCheckDisabled(env) {
+    const isSet = (v) => v !== undefined && v !== '' && v !== '0' && v.toLowerCase() !== 'false';
+    return isSet(env.NEMUS_NO_UPDATE_CHECK) || isSet(env.NO_UPDATE_NOTIFIER);
+}
 function formatUpdateMessage(current, latest) {
     return `\x1b[33m[nemus] Update available: ${current} -> ${latest}. Run: npm install -g @nemus-cli/nemus@latest\x1b[0m`;
 }

package/package.json

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

package/skills/nemus/references/completion.md

@@ -18,5 +18,10 @@ nemus completion zsh > "${fpath[1]}/_nemus"
 nemus completion fish > ~/.config/fish/completions/nemus.fish
 ```
 
-Then restart the shell (or `source` the file). Requires a shell argument —
-one of `bash|zsh|fish`.
+Then restart the shell (or `source` the file). The shell argument is inferred
+from `$SHELL` when omitted (`nemus completion`), so you usually don't need to
+pass it; an explicit `bash|zsh|fish` always wins.
+
+Completions cover second-level subcommands too — e.g. `nemus config <TAB>`
+(get/set/…), `nemus config set <TAB>` (config keys), and `nemus reflect <TAB>`
+(history/show).

package/src/commands/completion.test.ts

@@ -1,6 +1,6 @@
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, vi } from 'vitest';
 import { Command } from 'commander';
-import { generateCompletion, specsFromProgram, CommandSpec } from './completion';
+import { generateCompletion, specsFromProgram, detectShell, registerCompletionCommand, CommandSpec } from './completion';
 
 const specs: CommandSpec[] = [
   { name: 'list', aliases: ['l'], takesWorkspace: false, description: 'List workspaces' },
@@ -8,6 +8,49 @@ const specs: CommandSpec[] = [
   { name: 'doctor', aliases: ['doc'], takesWorkspace: true, description: 'Health checks' },
 ];
 
+// A spec set exercising second-level subcommands and third-level value completion.
+const subSpecs: CommandSpec[] = [
+  {
+    name: 'config', aliases: [], takesWorkspace: false, description: 'Configure',
+    subcommands: ['get', 'set', 'list', 'ls'],
+    argValues: { after: ['get', 'set'], values: ['githubOrg', 'cloneProtocol'] },
+  },
+  { name: 'reflect', aliases: ['retro'], takesWorkspace: false, description: 'Retrospective', subcommands: ['history', 'show'] },
+];
+
+describe('detectShell', () => {
+  it('infers the shell from a $SHELL-style path', () => {
+    expect(detectShell('/bin/zsh')).toBe('zsh');
+    expect(detectShell('/usr/bin/fish')).toBe('fish');
+    expect(detectShell('/bin/bash')).toBe('bash');
+  });
+  it('returns null for unknown/empty values', () => {
+    expect(detectShell('/bin/tcsh')).toBeNull();
+    expect(detectShell('')).toBeNull();
+    expect(detectShell(undefined)).toBeNull();
+  });
+});
+
+describe('generateCompletion — second/third level', () => {
+  it('bash completes subcommands and config-key values, and stays valid', () => {
+    const s = generateCompletion('bash', subSpecs);
+    expect(s).toContain('config) echo "get set list ls" ;;');
+    expect(s).toContain('reflect|retro) echo "history show" ;;');
+    expect(s).toContain('case "$2" in get|set) echo "githubOrg cloneProtocol"');
+  });
+  it('zsh completes subcommands and values at CURRENT 3/4', () => {
+    const s = generateCompletion('zsh', subSpecs);
+    expect(s).toContain('config) compadd -- get set list ls ;;');
+    expect(s).toContain('reflect|retro) compadd -- history show ;;');
+    expect(s).toContain('case ${words[3]} in get|set) compadd -- githubOrg cloneProtocol');
+  });
+  it('fish emits seen-subcommand conditions for subcommands and values', () => {
+    const s = generateCompletion('fish', subSpecs);
+    expect(s).toContain("-n '__fish_seen_subcommand_from config' -a 'get set list ls'");
+    expect(s).toContain("__fish_seen_subcommand_from config; and __fish_seen_subcommand_from get set");
+  });
+});
+
 describe('generateCompletion — bash', () => {
   const s = generateCompletion('bash', specs);
   it('resets COMPREPLY, lists tokens, and registers both bins', () => {
@@ -43,6 +86,42 @@ describe('generateCompletion — fish', () => {
   });
 });
 
+describe('registerCompletionCommand — stdout hygiene on inferred shell', () => {
+  it('writes ONLY the script to stdout; the $SHELL inference note goes to stderr', async () => {
+    // The documented install path is `nemus completion zsh > _nemus`, so if the
+    // inference note leaked to stdout it would corrupt the generated script.
+    const program = new Command();
+    program.exitOverride();
+    program.command('list').description('list');
+    registerCompletionCommand(program);
+
+    const stdoutChunks: string[] = [];
+    const stdoutSpy = vi.spyOn(process.stdout, 'write').mockImplementation(((c: unknown) => {
+      stdoutChunks.push(String(c));
+      return true;
+    }) as typeof process.stdout.write);
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const prevShell = process.env.SHELL;
+    process.env.SHELL = '/bin/zsh';
+
+    let errCalls: string[] = [];
+    try {
+      await program.parseAsync(['node', 'nemus', 'completion']);
+      errCalls = errSpy.mock.calls.map((c) => c.map(String).join(' '));
+    } finally {
+      if (prevShell === undefined) delete process.env.SHELL;
+      else process.env.SHELL = prevShell;
+      stdoutSpy.mockRestore();
+      errSpy.mockRestore();
+    }
+
+    const stdout = stdoutChunks.join('');
+    expect(stdout.startsWith('#compdef')).toBe(true); // the zsh script, nothing prepended
+    expect(stdout).not.toContain('no shell given'); // the note never reached stdout
+    expect(errCalls.some((l) => l.includes('no shell given'))).toBe(true); // it went to stderr
+  });
+});
+
 describe('specsFromProgram', () => {
   it('detects workspace args + aliases from a commander program', () => {
     const program = new Command();
@@ -57,4 +136,26 @@ describe('specsFromProgram', () => {
     expect(byName.list.takesWorkspace).toBe(false);
     expect(byName.create.takesWorkspace).toBe(false);
   });
+
+  it('derives nested subcommands, the reflect override, and config keys', () => {
+    const program = new Command();
+    const cfg = program.command('config').description('config');
+    cfg.command('get').description('get');
+    cfg.command('set').description('set');
+    program.command('reflect').description('reflect'); // positional subcommands
+    program.command('list').description('list');
+
+    const byName = Object.fromEntries(specsFromProgram(program).map((s) => [s.name, s]));
+    // nested commander subcommands are auto-derived
+    expect(byName.config.subcommands).toContain('get');
+    expect(byName.config.subcommands).toContain('set');
+    // reflect's positional subcommands come from the override
+    expect(byName.reflect.subcommands).toEqual(['history', 'show']);
+    // config gets key-value completion from the authoritative CONFIG_KEYS
+    expect(byName.config.argValues?.after).toEqual(['get', 'set', 'unset']);
+    expect(byName.config.argValues?.values).toContain('githubOrg');
+    // a plain command has neither
+    expect(byName.list.subcommands).toBeUndefined();
+    expect(byName.list.argValues).toBeUndefined();
+  });
 });

package/src/commands/completion.ts

@@ -1,11 +1,16 @@
 import { Command } from 'commander';
 import { listWorkspaces } from '../utils/workspace-meta';
-import { logError } from '../utils/logger';
+import { logError, logInfo } from '../utils/logger';
+import { CONFIG_KEYS } from '../utils/config-schema';
 
 /** Binaries that get completion registered (the CLI's bins). */
 export const COMPLETION_BINS = ['nemus', 'nem'];
 
 export type Shell = 'bash' | 'zsh' | 'fish';
+export const SHELLS: Shell[] = ['bash', 'zsh', 'fish'];
+
+/** Commands whose subcommands are positional args (not nested commander commands). */
+const POSITIONAL_SUBCOMMANDS: Record<string, string[]> = { reflect: ['history', 'show'] };
 
 /** One top-level command, distilled to what a completion script needs. */
 export interface CommandSpec {
@@ -14,6 +19,20 @@ export interface CommandSpec {
   /** True if its first positional argument is a workspace name. */
   takesWorkspace: boolean;
   description: string;
+  /** Second-level tokens (e.g. `config get`, `reflect history`), if any. */
+  subcommands?: string[];
+  /** Third-level value completion: for these subcommands, complete `values`. */
+  argValues?: { after: string[]; values: string[] };
+}
+
+/**
+ * Infer a shell from a `$SHELL`-style path (e.g. `/bin/zsh` -> `zsh`). Returns
+ * null for an unknown/empty value. Pure + exported for testing.
+ */
+export function detectShell(shellPath: string | undefined): Shell | null {
+  if (!shellPath) return null;
+  const base = shellPath.trim().split('/').pop()?.toLowerCase() ?? '';
+  return SHELLS.find((s) => s === base) ?? null;
 }
 
 /** Every token (name + aliases) that should complete as a subcommand. */
@@ -26,6 +45,11 @@ function workspaceTokens(cmds: CommandSpec[]): string[] {
   return cmds.filter((c) => c.takesWorkspace).flatMap((c) => [c.name, ...c.aliases]);
 }
 
+/** All tokens (name + aliases) that route to a given command spec. */
+function cmdTokens(c: CommandSpec): string[] {
+  return [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, "'\\''");
@@ -33,18 +57,40 @@ function fishDesc(s: string): string {
 
 /**
  * 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.
+ * generated script completes, in order: top-level commands (position 1); then
+ * either workspace names (for workspace-scoped commands) or a command's own
+ * subcommands (position 2); then value completions like `config` keys
+ * (position 3). Workspace names stay dynamic via a callback into
+ * `<bin> completion --workspaces`.
  */
 export function generateCompletion(shell: Shell, cmds: CommandSpec[], bins: string[] = COMPLETION_BINS): string {
   const commands = allTokens(cmds).join(' ');
   const wsCommands = workspaceTokens(cmds).join(' ');
+  const withSubs = cmds.filter((c) => c.subcommands && c.subcommands.length);
+  const withArgVals = cmds.filter((c) => c.argValues && c.argValues.values.length);
 
   if (shell === 'bash') {
+    const subArms = withSubs
+      .map((c) => `    ${cmdTokens(c).join('|')}) echo "${c.subcommands!.join(' ')}" ;;`)
+      .join('\n');
+    const argArms = withArgVals
+      .map(
+        (c) =>
+          `    ${cmdTokens(c).join('|')}) case "$2" in ${c.argValues!.after.join('|')}) echo "${c.argValues!.values.join(' ')}" ;; esac ;;`,
+      )
+      .join('\n');
     return `# nemus bash completion. Install: nemus completion bash > /etc/bash_completion.d/nemus
 #   (or: nemus completion bash >> ~/.bashrc)
+_nemus_subcmds() {
+  case "$1" in
+${subArms}
+  esac
+}
+_nemus_argvals() {
+  case "$1" in
+${argArms}
+  esac
+}
 _nemus_complete() {
   local cur bin sub
   # bash does not clear COMPREPLY between completions; reset so a stale result
@@ -66,6 +112,20 @@ _nemus_complete() {
       COMPREPLY=( \$(compgen -W "\$names" -- "\$cur") )
       return 0
     fi
+    local subs
+    subs="\$(_nemus_subcmds "\$sub")"
+    if [ -n "\$subs" ]; then
+      COMPREPLY=( \$(compgen -W "\$subs" -- "\$cur") )
+    fi
+    return 0
+  fi
+  if [ "\$COMP_CWORD" -eq 3 ]; then
+    local vals
+    vals="\$(_nemus_argvals "\${COMP_WORDS[1]}" "\${COMP_WORDS[2]}")"
+    if [ -n "\$vals" ]; then
+      COMPREPLY=( \$(compgen -W "\$vals" -- "\$cur") )
+    fi
+    return 0
   fi
   return 0
 }
@@ -74,6 +134,15 @@ ${bins.map((b) => `complete -F _nemus_complete ${b}`).join('\n')}
   }
 
   if (shell === 'zsh') {
+    const subArms = withSubs
+      .map((c) => `      ${cmdTokens(c).join('|')}) compadd -- ${c.subcommands!.join(' ')} ;;`)
+      .join('\n');
+    const argArms = withArgVals
+      .map(
+        (c) =>
+          `      ${cmdTokens(c).join('|')}) case \${words[3]} in ${c.argValues!.after.join('|')}) compadd -- ${c.argValues!.values.join(' ')} ;; esac ;;`,
+      )
+      .join('\n');
     // 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"
@@ -90,7 +159,17 @@ if (( CURRENT == 3 )); then
     local -a _nemus_names
     _nemus_names=(\${(f)"$(\${words[1]} completion --workspaces 2>/dev/null)"})
     compadd -- $_nemus_names
+    return
   fi
+  case $sub in
+${subArms}
+  esac
+  return
+fi
+if (( CURRENT == 4 )); then
+  case \${words[2]} in
+${argArms}
+  esac
 fi
 `;
   }
@@ -100,7 +179,7 @@ fi
   for (const bin of bins) {
     lines.push(`complete -c ${bin} -f`);
     for (const c of cmds) {
-      for (const tok of [c.name, ...c.aliases]) {
+      for (const tok of cmdTokens(c)) {
         lines.push(`complete -c ${bin} -n __fish_use_subcommand -a '${tok}' -d '${fishDesc(c.description)}'`);
       }
     }
@@ -110,6 +189,18 @@ fi
         `complete -c ${bin} -n '__fish_seen_subcommand_from ${wsToks}' -a '(${bin} completion --workspaces)'`,
       );
     }
+    // Second-level subcommands.
+    for (const c of withSubs) {
+      lines.push(
+        `complete -c ${bin} -n '__fish_seen_subcommand_from ${cmdTokens(c).join(' ')}' -a '${c.subcommands!.join(' ')}'`,
+      );
+    }
+    // Third-level value completions (e.g. config keys after get/set/unset).
+    for (const c of withArgVals) {
+      lines.push(
+        `complete -c ${bin} -n '__fish_seen_subcommand_from ${cmdTokens(c).join(' ')}; and __fish_seen_subcommand_from ${c.argValues!.after.join(' ')}' -a '${c.argValues!.values.join(' ')}'`,
+      );
+    }
   }
   return lines.join('\n') + '\n';
 }
@@ -120,11 +211,20 @@ export function specsFromProgram(program: Command): CommandSpec[] {
     .map((c) => {
       const args = (c as any).registeredArguments ?? [];
       const firstArg: string | undefined = args[0]?.name?.();
+      const name = c.name();
+      // Nested commander subcommands (config/suite/branch/cache/mcp), else a
+      // manual override for commands whose subcommands are positional (reflect).
+      const nested = c.commands.flatMap((s) => [s.name(), ...s.aliases()]).filter(Boolean);
+      const subcommands = nested.length ? nested : POSITIONAL_SUBCOMMANDS[name];
+      const argValues =
+        name === 'config' ? { after: ['get', 'set', 'unset'], values: [...CONFIG_KEYS] } : undefined;
       return {
-        name: c.name(),
+        name,
         aliases: c.aliases(),
         takesWorkspace: typeof firstArg === 'string' && firstArg.toLowerCase().includes('workspace'),
         description: c.description() ?? '',
+        ...(subcommands ? { subcommands } : {}),
+        ...(argValues ? { argValues } : {}),
       };
     })
     // The completion command itself and any hidden helper needn't clutter, but
@@ -135,7 +235,7 @@ export function specsFromProgram(program: Command): CommandSpec[] {
 export function registerCompletionCommand(program: Command) {
   program
     .command('completion [shell]')
-    .description('Output a shell completion script (bash|zsh|fish)')
+    .description('Output a shell completion script (bash|zsh|fish; inferred from $SHELL if omitted)')
     .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.
@@ -149,12 +249,21 @@ export function registerCompletionCommand(program: Command) {
         return;
       }
 
-      const shells: Shell[] = ['bash', 'zsh', 'fish'];
-      if (!shell || !shells.includes(shell as Shell)) {
-        logError(`completion: specify a shell — one of ${shells.join(', ')}`);
+      // An explicit argument wins; only fall back to $SHELL when none is given
+      // (an invalid explicit arg is an error, not a reason to guess).
+      let target: Shell | null = null;
+      if (shell) {
+        target = SHELLS.includes(shell as Shell) ? (shell as Shell) : null;
+      } else {
+        target = detectShell(process.env.SHELL);
+        if (target) logInfo(`completion: no shell given — using ${target} (from $SHELL)`);
+      }
+
+      if (!target) {
+        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)));
+      process.stdout.write(generateCompletion(target, specsFromProgram(program)));
     });
 }

package/src/commands/version.test.ts

@@ -0,0 +1,21 @@
+import { describe, it, expect } from 'vitest';
+import { buildVersionInfo } from './version';
+
+describe('buildVersionInfo', () => {
+  it('combines the given version with the injected runtime fields', () => {
+    const info = buildVersionInfo('1.2.3', {
+      versions: { node: '22.13.0' } as NodeJS.ProcessVersions,
+      platform: 'linux',
+      arch: 'x64',
+    });
+    expect(info).toEqual({ version: '1.2.3', node: '22.13.0', platform: 'linux', arch: 'x64' });
+  });
+
+  it('defaults to the real process runtime', () => {
+    const info = buildVersionInfo('9.9.9');
+    expect(info.version).toBe('9.9.9');
+    expect(info.node).toBe(process.versions.node);
+    expect(info.platform).toBe(process.platform);
+    expect(info.arch).toBe(process.arch);
+  });
+});

package/src/commands/version.ts

@@ -0,0 +1,45 @@
+import { Command } from 'commander';
+import { outputJson } from '../utils/output';
+
+export interface VersionInfo {
+  version: string;
+  node: string;
+  platform: string;
+  arch: string;
+}
+
+/**
+ * Build the version payload. Pure and process-injectable so the JSON shape is
+ * unit-testable without reading the real runtime.
+ */
+export function buildVersionInfo(
+  version: string,
+  proc: Pick<NodeJS.Process, 'versions' | 'platform' | 'arch'> = process,
+): VersionInfo {
+  return {
+    version,
+    node: proc.versions.node,
+    platform: proc.platform,
+    arch: proc.arch,
+  };
+}
+
+/**
+ * `nemus version` — a subcommand companion to the `-V/--version` flag, for
+ * people who type `nemus version`. `--json` also reports the Node/OS runtime
+ * (handy for bug reports), emitting a single JSON document to stdout.
+ */
+export function registerVersionCommand(program: Command, version: string) {
+  program
+    .command('version')
+    .description('Print the Nemus version (with --json for version + runtime info)')
+    .option('--json', 'Output version + runtime info as JSON')
+    .action((opts: { json?: boolean }) => {
+      const info = buildVersionInfo(version);
+      if (opts.json) {
+        outputJson(info);
+      } else {
+        process.stdout.write(`nemus ${info.version}\n`);
+      }
+    });
+}

package/src/program.ts

@@ -4,6 +4,7 @@ import * as fs from 'fs';
 import { setColorEnabled } from './utils/colors';
 import { renderHelpBanner } from './utils/banner';
 import { applyGlobalFlags } from './utils/global-flags';
+import { registerVersionCommand } from './commands/version';
 
 // Read version from package.json
 const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
@@ -35,6 +36,7 @@ program
 program.hook('preAction', () => applyGlobalFlags(program.opts()));
 
 // Register top-level commands
+registerVersionCommand(program, pkg.version);
 import { registerCreateCommand } from './commands/create';
 import { registerListCommand } from './commands/list';
 import { registerUpdateCommand } from './commands/update';

package/src/utils/version-check.test.ts

@@ -24,14 +24,41 @@ vi.mock('./config', () => ({
   getPackageVersion: () => '2.20.0',
 }));
 
-import { checkForUpdate } from './version-check';
+import { checkForUpdate, updateCheckDisabled } from './version-check';
 import * as fs from 'fs/promises';
 
+describe('updateCheckDisabled', () => {
+  it('is true when NEMUS_NO_UPDATE_CHECK is set to a truthy value', () => {
+    expect(updateCheckDisabled({ NEMUS_NO_UPDATE_CHECK: '1' })).toBe(true);
+    expect(updateCheckDisabled({ NEMUS_NO_UPDATE_CHECK: 'yes' })).toBe(true);
+  });
+  it('honors the de-facto NO_UPDATE_NOTIFIER', () => {
+    expect(updateCheckDisabled({ NO_UPDATE_NOTIFIER: 'true' })).toBe(true);
+  });
+  it('is false when unset, empty, or an explicit falsey token', () => {
+    expect(updateCheckDisabled({})).toBe(false);
+    expect(updateCheckDisabled({ NEMUS_NO_UPDATE_CHECK: '' })).toBe(false);
+    expect(updateCheckDisabled({ NEMUS_NO_UPDATE_CHECK: '0' })).toBe(false);
+    expect(updateCheckDisabled({ NEMUS_NO_UPDATE_CHECK: 'false' })).toBe(false);
+  });
+});
+
 describe('checkForUpdate', () => {
   beforeEach(() => {
     vi.clearAllMocks();
   });
 
+  it('returns null immediately when opted out via env (no fetch)', async () => {
+    process.env.NEMUS_NO_UPDATE_CHECK = '1';
+    try {
+      const result = await checkForUpdate();
+      expect(result).toBeNull();
+      expect(mockExecFile).not.toHaveBeenCalled();
+    } finally {
+      delete process.env.NEMUS_NO_UPDATE_CHECK;
+    }
+  });
+
   it('returns null when current version matches latest', async () => {
     // No cached check
     vi.mocked(fs.readFile).mockRejectedValueOnce(new Error('ENOENT'));

package/src/utils/version-check.ts

@@ -60,6 +60,10 @@ async function fetchLatestVersion(): Promise<string | null> {
  * This is designed to be non-blocking and best-effort — failures are silent.
  */
 export async function checkForUpdate(): Promise<string | null> {
+  // Opt-out: skip the check entirely (no cache read, no network) when the user
+  // asks for it. NEMUS_NO_UPDATE_CHECK is ours; NO_UPDATE_NOTIFIER is the
+  // de-facto convention several Node CLIs honor.
+  if (updateCheckDisabled(process.env)) return null;
   try {
     const currentVersion = getPackageVersion();
     const cache = await loadCache();
@@ -91,6 +95,17 @@ export async function checkForUpdate(): Promise<string | null> {
   }
 }
 
+/**
+ * Whether the update check is opted out via env. A value is "set" unless it is
+ * empty or an explicit falsey token (`0`/`false`), so `NEMUS_NO_UPDATE_CHECK=0`
+ * does NOT disable the check. Pure + exported for testing.
+ */
+export function updateCheckDisabled(env: NodeJS.ProcessEnv): boolean {
+  const isSet = (v: string | undefined) =>
+    v !== undefined && v !== '' && v !== '0' && v.toLowerCase() !== 'false';
+  return isSet(env.NEMUS_NO_UPDATE_CHECK) || isSet(env.NO_UPDATE_NOTIFIER);
+}
+
 function formatUpdateMessage(current: string, latest: string): string {
   return `\x1b[33m[nemus] Update available: ${current} -> ${latest}. Run: npm install -g @nemus-cli/nemus@latest\x1b[0m`;
 }