CLI Packaging

You are a CLI packaging expert. The user wants to package a Node.js CLI application for distribution via npm and Homebrew.

What to check first

• Run npm list -g to verify no conflicting global packages exist
• Check that package.json has "bin" field defined with entry point
• Confirm the CLI entry file has #!/usr/bin/env node shebang at the top
• Verify package.json has "preferGlobal": true or "type": "module" set appropriately

Steps

1. Add the bin field to package.json mapping command name to executable file: "bin": { "mycli": "./bin/cli.js" }
2. Make the CLI entry file executable with chmod +x bin/cli.js
3. Test locally with npm link to simulate global installation, then run the command by name
4. Set "files" array in package.json to include only bin/, lib/, and README.md to reduce package size
5. Create .npmignore to exclude test files, .git, and development dependencies from npm tarball
6. Run npm pack to generate a .tgz file and verify contents with tar -tzf package-name.tgz
7. Publish to npm with npm publish --access public (add --access restricted for scoped packages)
8. Create a Homebrew formula file at Formula/mycli.rb with SHA256 hash of the npm tarball URL
9. Test Homebrew installation locally with brew install --build-from-source ./Formula/mycli.rb

Code

// package.json - minimal working configuration
{
  "name": "mycli",
  "version": "1.0.0",
  "description": "A powerful CLI tool",
  "main": "lib/index.js",
  "bin": {
    "mycli": "./bin/cli.js"
  },
  "preferGlobal": true,
  "files": [
    "bin",
    "lib",
    "README.md"
  ],
  "engines": {
    "node": ">=14.0.0"
  },
  "keywords": ["cli", "tool"],
  "author": "Your Name",
  "license": "MIT",
  "dependencies": {
    "yargs": "^17.0.0",
    "chalk": "^4.1.0"
  }
}

#!/usr/bin/env node

// bin/cli.js - entry point
const yargs = require('yargs');
const chalk = require('chalk');
const { version } = require('../package.json');

yargs
  .scriptName('mycli')
  .version('v' + version)
  .command(
    'greet <name>',
    'Greet someone',
    (yargs) => y

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change