Skip to content
CLINode.js

Node CLI Tool (run via npx)

Zero-dependency CLI using node:util parseArgs, wired through package.json "bin" and published to npm so anyone can run `npx <name>`.

Open in builder →

8 steps

Shell

Shown with defaults: npm, pip, Node LTS, Python 3.12 and the template's default add-ons.

  1. 1. Install and select Node.js with nvm

    runtime

    nvm lets you install several Node.js versions side by side and switch per project. `nvm use` activates it for this shell.

    bash
    nvm install --ltsnvm use --lts
    Expected result
    `node -v` prints the selected version.
    Verify
    node -v && npm -v
    OS notes
    macOS/Linux/WSL: install nvm with `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.8/install.sh | bash`, then reopen the terminal. Windows: use nvm-windows (github.com/coreybutler/nvm-windows) from an elevated terminal, or fnm.

  2. 2. Create the project folder

    template

    Create an empty folder for the project and move into it. All following commands run inside it.

    bash
    mkdir nvx-hello-clicd nvx-hello-cli
    Expected result
    You are inside ./nvx-hello-cli
    Verify
    pwd

  3. 3. Initialise package.json

    template

    Create a package.json with default values so you can add dependencies and scripts.

    bash
    npm init -y
    Expected result
    A package.json file exists.
    Verify
    node -e "console.log(require('./package.json').name)"

  4. 4. Declare the executable in package.json

    template

    "bin" maps the command name to a file; npx and global installs create the command from it. "files" limits what gets published.

    bash
    npm pkg set type=module 'bin.nvx-hello-cli=bin/cli.js' 'files[]=bin' 'engines.node=>=20'
    Expected result
    package.json has bin, files and engines.
    Verify
    npm pkg get bin files

  5. 5. Write the CLI entry file

    template

    The shebang line lets the OS run the file with Node.

    bash
    chmod +x bin/cli.js
    Files written by this step: bin/cli.js, README.md
    bin/cli.js
    #!/usr/bin/env node
import { parseArgs } from "node:util";

const { values } = parseArgs({
  options: {
    name: { type: "string", short: "n", default: "world" },
    help: { type: "boolean", short: "h", default: false },
  },
});

if (values.help) {
  console.log("Usage: nvx-hello-cli [--name <name>]");
  console.log("  -n, --name   who to greet (default: world)");
  console.log("  -h, --help   show this help");
  process.exit(0);
}

console.log("Hello, " + values.name + "! (from nvx-hello-cli)");
    README.md
    # nvx-hello-cli

Run without installing:

    npx nvx-hello-cli@latest --name NVX
    Expected result
    Running the file prints a greeting.
    Verify
    node bin/cli.js --name NVX
    OS notes
    chmod is not needed on Windows; npm creates a .cmd shim.

  6. 6. Preview the published package

    template

    --dry-run lists the tarball contents without creating or uploading anything.

    bash
    npm pack --dry-run
    Expected result
    Only package.json, README.md and bin/cli.js are listed.

  7. 7. Try it as a global command

    templatemanual / review

    npm link symlinks the package globally so you can type the command anywhere. Undo with npm unlink -g nvx-hello-cli.

    bash
    npm link
    Expected result
    `nvx-hello-cli --help` works in any folder.
    Verify
    nvx-hello-cli --help
    OS notes
    With nvm no sudo is needed. Never use sudo npm with nvm.

  8. 8. Publish to npm

    templatepublish · manual

    Log in once, then publish. Package names are global — check availability with `npm view nvx-hello-cli` first. Bump versions with `npm version patch`.

    bash
    npm loginnpm publish --access public
    Expected result
    https://www.npmjs.com/package/nvx-hello-cli is live.
    Verify
    npx nvx-hello-cli@latest --help