Shell CLI Argument Parser and Router

Common errors

• TypeError: (0 , shell_1.shell) is not a function

  cause Incorrectly importing the `shell` module as a default import when it's a named export, common in TypeScript or Babel setups where transpilation might obscure the direct named import error.
  fix Change your import statement to `import { shell } from 'shell';` to correctly access the named export.

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use `require()` in a JavaScript file that is treated as an ES module (e.g., due to `"type": "module"` in `package.json` or `.mjs` extension) without proper CommonJS fallback or ESM compatibility.
  fix If working in an ES module environment, use `import { shell } from 'shell';`. If you must use CommonJS, ensure your file is `.cjs` or your `package.json` does not specify `"type": "module"` for that context.

• Error: Command 'unknown-command' not found.

  cause Attempting to execute a command that has not been defined in the `commands` object of the `shell()` configuration.
  fix Ensure that the command you are trying to run is explicitly defined within the `commands` object when you initialize your `shell` instance, or check for typos in the command name.

Warnings

• breaking Version 0.12.0 (latest) officially requires Node.js v20 or later. Older Node.js versions, particularly those indicated in outdated `package.json` snippets (like `node >= 0.10.x`), are not supported and will likely lead to runtime errors or unexpected behavior due to modern JavaScript features and API usage.
  Fix: Ensure your project runs on Node.js v20 or a newer compatible version. Update your runtime environment if necessary.
• gotcha The `shell` module exports a named function, not a default export. Attempting to `import shell from 'shell'` (default import) or `const shell = require('shell')` (CommonJS default require) will result in `undefined` or a `TypeError` when trying to invoke it as a function.
  Fix: Always use named imports for ESM (`import { shell } from 'shell';`) and destructuring for CommonJS (`const { shell } = require('shell');`).
• gotcha The `shell.js` API relies heavily on a declarative configuration object passed to the main `shell()` function. Attempting to directly call methods like `parse` or `stringify` without first defining your CLI structure via the configuration object and `route()` call is not the intended modern usage and may lead to errors or incomplete functionality.
  Fix: Structure your CLI definition using the configuration object and call `myCli.route()` to activate parsing and command execution. Refer to the official documentation for the complete declarative API pattern.

Install

• npm install shell npm
• yarn add shell yarn
• pnpm add shell pnpm

Imports

• shell
  wrong:

  import shell from 'shell';

  correct:

  import { shell } from 'shell';

  The 'shell' function is a named export, not a default export, since version 0.12.0 and later. Using a default import will result in 'undefined' or a runtime error.
• CLI Application Initialization
  wrong:

  const cli = require('shell');
  cli.parse(process.argv.slice(2)); // Old imperative API or partial usage

  correct:

  const cli = shell({
    name: 'my-app',
    description: 'My CLI application',
    options: { version: { shortcut: 'v', description: 'Show version' } },
    commands: { start: { description: 'Start the application' } }
  });
  cli.route();

  The modern API in 0.12.0+ emphasizes a declarative configuration object passed to the named 'shell' function, followed by '.route()' to process arguments and invoke commands. Direct access to 'parse' or other methods without prior configuration is generally not the intended pattern.
• CommonJS Require
  wrong:

  const shell = require('shell');

  correct:

  const { shell } = require('shell');

  While the project primarily promotes ESM, CommonJS usage requires destructuring the 'shell' named export. Attempting to import the entire module as a default export in CJS will not work as expected with the current API design.

Quickstart

This quickstart defines a CLI with global options, subcommands, and subcommand-specific options, demonstrating the declarative API for parsing and routing with `shell.js`.

import { shell } from 'shell';

const myCli = shell({
  name: 'complex-app',
  description: 'A robust command-line application demonstrating parsing and routing.',
  options: {
    verbose: { shortcut: 'v', description: 'Enable verbose logging', type: 'boolean' },
    config: { shortcut: 'c', description: 'Path to configuration file', type: 'string', default: './config.json' }
  },
  commands: {
    start: {
      description: 'Start a service or process.',
      options: {
        port: { shortcut: 'p', description: 'Port to listen on', type: 'integer', default: 3000 }
      },
      main: async ({ options }) => {
        console.log(`Starting service on port ${options.port} with config: ${options.config} (verbose: ${options.verbose})`);
        // Simulate async operation
        await new Promise(resolve => setTimeout(resolve, 1000));
        console.log('Service started successfully.');
      }
    },
    stop: {
      description: 'Stop a running service.',
      main: () => {
        console.log('Stopping service...');
        console.log('Service stopped.');
      }
    }
  }
});

myCli.route().catch(err => {
  console.error('CLI Error:', err.message);
  process.exit(1);
});

// To run this: save as `cli.js`, add `"type": "module"` to package.json.
// Then run: `node cli.js start -p 8080 --verbose` or `node cli.js stop -c my-dev-config.json`