🖥️ cli-tool-name

A fast, developer-friendly CLI for doing something useful.

$ cli-tool-name --help

📑 Table of Contents

• About
• How It Works
• Real-World Use Cases
• Features
• Installation
• Quick Start
• Usage
• Commands
• Flags & Options
• Configuration File
• Examples
• Shell Completion
• Contributing
• License

🧾 About

Tagline — One sentence describing the tool.

2–3 sentences: what this CLI does, what pain it eliminates, and who should install it.

Example:

cli-tool-name

is a zero-config code scaffolding tool for TypeScript monorepos. Instead of copying boilerplate between projects, you run one command and get a fully configured workspace — with linting, testing, and CI pre-wired — in under 10 seconds.

⚙️ How It Works

Describe what happens when a command is run:

$ cli-tool-name run
        │
        ▼
  Load config (.cli-tool.json or defaults)
        │
        ▼
  Validate inputs (args + flags)
        │
        ▼
  Execute pipeline (steps run in order)
        │
        ▼
  Write output / print result to stdout

💼 Real-World Use Cases

• Backend Developers: Scaffold a new microservice with one command instead of copying config from an existing service.
• DevOps Engineers: Automate repetitive environment setup scripts across multiple machines without maintaining bash scripts per OS.
• Open Source Maintainers: Run cross-repo tasks (version bumps, changelog generation) from a single familiar command.
• Teams with Standards: Enforce consistent project structure by distributing a shared config file as an npm package.

✨ Features

• ⚡ Blazing fast execution
• 🔧 Zero-config defaults with full customization
• 🌈 Rich terminal output with color support
• 📄 JSON and plain-text output modes
• 🔌 Plugin-friendly architecture
• 🔤 Shell completion for bash, zsh, and fish

📦 Installation

# npm
npm install -g cli-tool-name

# Homebrew
brew install username/tap/cli-tool-name

# Binary (all platforms)
curl -sSL https://install.example.com | sh

Requirements: Node.js ≥ 18

🚀 Quick Start

# 1. Initialize config in current project
cli-tool-name init

# 2. Run the primary action
cli-tool-name run

# 3. Check version
cli-tool-name --version

💡 Usage

Basic workflow

# Initialize once per project
cli-tool-name init

# Run against a target directory
cli-tool-name run ./src

# List available actions
cli-tool-name list

# Preview changes without applying them
cli-tool-name run --dry-run

Piping and scripting

# Output as JSON for scripting
cli-tool-name list --output json | jq '.targets[]'

# Use in a Makefile or CI step
cli-tool-name build --config .cli-tool.prod.json

📚 Commands

cli-tool-name init

cli-tool-name run [target]

cli-tool-name list

cli-tool-name config

cli-tool-name upgrade

🏳️ Flags & Options

--output

-o

string

json

text

text

--verbose

-v

boolean

false

--dry-run

-d

boolean

false

--config

-c

string

.cli-tool.json

⚙️ Configuration File

Create

.cli-tool.json

{
  "$schema": "https://cli-tool-name.dev/schema.json",
  "output": "json",
  "targets": ["src", "lib"],
  "ignore": ["node_modules", "dist"],
  "plugins": ["@cli-tool/plugin-example"]
}

💡 Examples

# Run verbosely on a specific path
cli-tool-name run ./src --verbose

# Dry-run a destructive operation
cli-tool-name clean --dry-run

# Output JSON and pipe to jq
cli-tool-name list --output json | jq '.targets'

🔤 Shell Completion

# Bash
cli-tool-name completion bash >> ~/.bashrc

# Zsh
cli-tool-name completion zsh >> ~/.zshrc

# Fish
cli-tool-name completion fish > ~/.config/fish/completions/cli-tool-name.fish

🤝 Contributing

git clone https://github.com/username/cli-tool.git
cd cli-tool
npm install
npm run dev -- --help

Please read CONTRIBUTING.md before opening a PR.

📝 License

Distributed under the MIT License. See LICENSE for more information.