π A production-ready CLI template for building AI-powered command-line tools
This template provides a solid foundation for creating professional CLI tools with AI capabilities, beautiful terminal UI, and enterprise-grade quality tooling.
-
π¨ Beautiful Terminal UI
- Gradient-styled help screens with
gradient-string - ASCII logo/banner with customizable branding
- Progress spinners with
ora - Styled output with
chalkandboxen - Interactive prompts with
inquirer
- Gradient-styled help screens with
-
π€ AI Integration
- GitHub Copilot CLI SDK integration
- AIService abstraction for easy AI operations
- Configurable model selection
- First-run setup wizard
-
βοΈ Configuration System
- Persistent settings with
confpackage - Model aliases for convenience
- Cross-platform config storage
- Environment-agnostic setup
- Persistent settings with
-
π Authentication
- GitHub CLI integration for auth
- Multi-account support
- Copilot access verification
- Comprehensive auth help system
-
π¦ Argument Parsing
- Commander.js with styled help
- Global and command-specific options
- Subcommands with clean organization
- Custom help formatting
-
β Pre-commit Hooks (Husky + lint-staged)
- Auto-lint on commit
- Auto-format on commit
- Type-check before commit
- Zero-config quality enforcement
-
π Linting & Formatting
- ESLint with TypeScript support
- Prettier for consistent formatting
- Strict TypeScript configuration
- Pre-configured rules for CLI development
-
ποΈ Build System
- TypeScript compilation
- Source maps for debugging
- Declaration files
- Modern ES2022 target
- π³ Dev Container Support
- Pre-configured Docker development environment
- Node.js 22 LTS with TypeScript tooling
- GitHub CLI pre-installed
- Zsh with Oh My Zsh
- All VS Code extensions included
- Optimized for GitHub Copilot Workspace
- Consistent development across all platforms
# Clone to your new project directory
git clone <this-repo> my-awesome-cli
cd my-awesome-cli
# Remove template's git history
rm -rf .git
# Initialize your own repo
git initUpdate package.json:
{
"name": "@yourorg/your-cli-name",
"description": "Your CLI description",
"bin": {
"your-cli": "dist/index.js"
}
}Update branding in src/lib/banner.ts:
- Change the ASCII logo (use patorjk.com/software/taag)
- Customize gradient colors
- Update branding text
- Modify version and taglines
Update src/lib/config.ts:
- Change
projectNamein the Conf constructor - Add any custom config fields you need
Update src/index.ts:
- Change
program.name()to your CLI name - Update description
- Add your custom commands
Update auth references:
Find and replace in src/commands/auth.ts and src/commands/config.ts:
"HS CLI"β Your CLI name"hs-cli"β Your CLI command name
npm installThis will:
- Install all dependencies
- Set up Husky pre-commit hooks automatically
- Configure git hooks for quality checks
# Build the project
npm run build
# Try the hello demo
npm run dev hello
# Check all quality tooling
npm run checkFor a consistent development environment across all platforms:
# Open in VS Code
code .
# Press F1 and select: Dev Containers: Reopen in ContainerThe dev container includes:
- Node.js 22 LTS with all dependencies
- GitHub CLI for authentication
- All VS Code extensions pre-installed
- Zsh shell with Oh My Zsh
- Automatic setup on container creation
See .devcontainer/README.md for more details.
# Run in dev mode with tsx (hot reload)
npm run dev [command]
# Build TypeScript
npm run build
# Run built version
npm start [command]# Lint TypeScript files
npm run lint
# Fix linting issues
npm run lint:fix
# Format code
npm run format
# Check formatting
npm run format:check
# Type check
npm run type-check
# Run all checks
npm run checkThe template includes automatic quality checks that run before every commit:
- β ESLint on staged files with auto-fix
- β Prettier formatting on staged files
- β TypeScript type checking
If any check fails, the commit is blocked until you fix the issues.
To skip hooks (not recommended):
git commit --no-verifyhs-cli-template/
βββ src/
β βββ index.ts # Main CLI entry point
β βββ commands/ # Command implementations
β β βββ auth.ts # GitHub authentication
β β βββ config.ts # Configuration management
β β βββ hello.ts # Demo command (customize/remove)
β βββ lib/ # Core services
β βββ ai.ts # AI service with Copilot SDK
β βββ banner.ts # Branded ASCII logo
β βββ config.ts # Configuration system
βββ .devcontainer/ # Dev container configuration
β βββ devcontainer.json # Container setup
β βββ README.md # Dev container docs
βββ dist/ # Compiled JavaScript (generated)
βββ .gitattributes # Line ending enforcement
βββ package.json # Dependencies and scripts
βββ tsconfig.json # TypeScript configuration
βββ eslint.config.js # ESLint rules
βββ .prettierrc # Prettier formatting
βββ .husky/ # Git hooks (generated by Husky)
Create src/commands/your-command.ts:
import chalk from 'chalk';
import ora from 'ora';
import boxen from 'boxen';
import logSymbols from 'log-symbols';
import { AIService } from '../lib/ai.js';
interface YourCommandOptions {
option1?: string;
model?: string;
}
export async function yourCommand(options: YourCommandOptions) {
const ai = new AIService(undefined, options.model);
const spinner = ora();
try {
spinner.start('Processing...');
// Your command logic here
const result = await ai.prompt('Your prompt here');
spinner.succeed('Complete!');
console.log(
boxen(chalk.cyan(result), {
padding: 1,
margin: 1,
borderStyle: 'round',
borderColor: 'cyan',
})
);
} catch (error) {
spinner.fail('Operation failed');
console.error(
chalk.red(logSymbols.error),
error instanceof Error ? error.message : 'Unknown error'
);
process.exit(1);
} finally {
await ai.close();
}
}import { yourCommand } from './commands/your-command.js';
program
.command('your-command')
.description('Your command description')
.option('-o, --option1 <value>', 'Option description')
.showHelpAfterError(true)
.action((options) => yourCommand({ ...options, model: globalModel }));Edit src/lib/banner.ts:
// Change ASCII art
const LOGO_LINES = [
' Your ASCII',
' Logo Here',
];
// Customize gradients
const myGradient = gradient(['#ff0000', '#00ff00']);
// Update showBanner() functionThe template includes custom help styling with:
- Lightning bolt for Usage
- Gradient-decorated section headers
- Italic gold descriptions with sparkles
- Custom symbols for Options/Commands
Modify styleHelpText() in src/index.ts to customize.
The AIService class provides a simple interface for AI operations:
import { AIService } from '../lib/ai.js';
const ai = new AIService('Your custom system message', 'claude');
// Send a prompt
const response = await ai.prompt('Your question here');
// Always close when done
await ai.close();Tips:
- Use different system messages for different use cases
- Model can be overridden per instance
- Always call
close()(use try/finally) - Session persists across multiple prompts
The template uses conf for persistent configuration:
import { config } from '../lib/config.js';
// Get values
const model = config.get('defaultModel');
// Set values
config.set('yourKey', 'yourValue');
// Add schema in src/lib/config.ts
export interface CLIConfig {
defaultModel: string;
yourKey: string; // Add your fields
}Config is stored at:
- Windows:
%APPDATA%/hs-cli/Config/config.json - macOS:
~/Library/Preferences/hs-cli/Config/config.json - Linux:
~/.config/hs-cli/Config/config.json
The template uses strict TypeScript settings:
strict: true- All strict checksnoUnusedLocals: true- No unused variablesnoImplicitReturns: true- Explicit returnsnoUncheckedIndexedAccess: true- Safe array accessexactOptionalPropertyTypes: true- Precise optionals
@github/copilot-sdk- AI capabilitiescommander- CLI frameworkchalk,boxen,ora- Terminal stylinggradient-string- Gradient textinquirer- Interactive promptsconf- Configuration storagecli-table3- Table formattinglog-symbols- Status symbols
typescript- Type systemtsx- TypeScript executioneslint- Lintingprettier- Formattinghusky- Git hookslint-staged- Pre-commit linting
β Do:
- Always close AIService in finally block
- Use spinners for long operations
- Provide helpful error messages
- Include progress feedback
- Handle errors gracefully
β Don't:
- Leave sessions open
- Use console.log for commands (use chalk/boxen)
- Forget to call
process.exit(1)on errors - Skip input validation
β Do:
- Write type-safe code
- Use Prettier formatting
- Follow ESLint rules
- Write descriptive comments
- Test before committing
β Don't:
- Use
anytypes - Skip type annotations
- Ignore linting errors
- Bypass pre-commit hooks (without good reason)
npm run check
npm run buildnpm version patch|minor|majornpm publish --access publicnpm install -g @yourorg/your-cli-nameThis template is designed to be customized for your specific CLI tool. Once you've created your CLI:
- Remove or replace the
hellodemo command - Update this README for your CLI's specific features
- Add your commands in
src/commands/ - Customize the banner and branding
- Update auth messages if needed
- Add any domain-specific services to
src/lib/
MIT Β© HemSoft Developments
Built with β€οΈ by HemSoft Developments
This template is based on the architecture of Smart Git CLI