Node CLI Starter

A foundational boilerplate project for building interactive CLI applications using Node.js, TypeScript, Ink, and React. This package serves both as a demonstration of the technology stack and as a project generator for creating new CLI applications.

🚀 Quick Start

Generate a new CLI project

# Using npx (recommended)
npx ink-cli-starter init my-awesome-cli

# Or if installed globally
npm install -g ink-cli-starter
ink-cli-starter init my-awesome-cli

Run the demo application

# Clone this repository
git clone <repository-url>
cd node-cli-starter

# Install dependencies
npm install

# Run in development mode
npm run dev

# Or build and run
npm run build
npm start

📦 What You Get

When you generate a new project, you'll get a complete CLI application setup with:

• TypeScript configuration for type safety
• React + Ink for building terminal UIs
• ESLint + Prettier for code quality
• Jest for testing
• Complete build pipeline with npm scripts
• Cross-platform compatibility

Generated Project Structure

my-awesome-cli/
├── src/
│   ├── components/
│   │   └── Logo.tsx          # ASCII logo component
│   ├── hooks/
│   │   └── useQuitHandler.ts # Quit handling logic
│   ├── types/
│   │   └── index.ts          # TypeScript type definitions
│   └── index.tsx             # Main application component
├── bin/
│   ├── cli.js               # Production entry point
│   └── cli.ts               # Development entry point
├── dist/                    # Compiled TypeScript output
├── package.json             # Project configuration
├── tsconfig.json           # TypeScript configuration
└── README.md               # Project documentation

🛠️ Development Commands

Core Development

npm run dev          # Run CLI in development mode (uses tsx for TypeScript)
npm start           # Run built CLI application
npm run build       # Compile TypeScript to dist/
npm run typecheck    # Run TypeScript type checking without compilation

Code Quality

npm run lint        # Run ESLint on src/
npm run lint:fix    # Auto-fix ESLint issues
npm run format      # Format code with Prettier

Testing

npm test           # Run all tests with Jest
npm run test:watch # Run tests in watch mode

🏗️ Architecture

Technology Stack

• Runtime: Node.js (>=18.0.0)
• Language: TypeScript for static type checking
• UI Framework: React + Ink for terminal interfaces
• CLI Parsing: Meow for command-line argument parsing
• Build: TypeScript compiler (no bundling for transparency)
• State Management: React hooks + Context API

Key Features

• ASCII Logo: Prominent branding displayed at top
• Graceful Exit: Press 'q' to quit or Ctrl+C
• Type Safety: Full TypeScript support throughout
• Cross-platform: Works on Windows, macOS, and Linux
• Modern Tooling: ESLint, Prettier, Jest pre-configured

🎯 Use Cases

Perfect for building:

• Development tools (build tools, generators, utilities)
• System administration tools
• Interactive CLIs with forms and navigation
• Data processing utilities
• Git workflow tools
• CI/CD helpers

📖 Examples

Basic CLI Application

The generated project includes a working example with:

• ASCII logo display
• Bordered interface
• Keyboard input handling
• Graceful exit functionality

Extending Your CLI

After generation, you can easily extend your CLI by:

1. Adding new components to src/components/
2. Creating custom hooks in src/hooks/
3. Adding CLI argument parsing with meow
4. Building interactive forms with Ink components

🔧 Configuration

Package Name Validation

Project names must be valid npm package names:

• Lowercase letters, numbers, and hyphens only
• No spaces or special characters
• Must start with a letter or number

Author Information

The generator automatically detects your git configuration for the author field, or uses "Your Name" as fallback.

🚢 Publishing Your CLI

After generating and customizing your CLI:

1. Build the project:

   npm run build

2. Test locally:

   npm start

3. Publish to npm:

   npm publish

4. Install globally:

   npm install -g your-cli-name

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Run the test suite
6. Submit a pull request

📋 Requirements

• Node.js >= 18.0.0
• npm >= 8.0.0

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Built with:

• Ink - React for CLI
• React - Component framework
• TypeScript - Type safety
• Meow - CLI argument parsing

Happy CLI building! 🚀