@theholocron/cli-template

A modern CLI template with pre-configured tools, best practices, and CI/CD setup for rapid project development.

Getting Started

Use the Holocron CLI to scaffold a new CLI project from this template. It clones the repo, renames all placeholder references, and runs holocron setup in one step:

npx @theholocron/cli new cli my-cli \
  --description "My CLI description" \
  --homepage "https://my-cli.example.com"

This will:

1. Create theholocron/my-cli on GitHub from this template
2. Replace all CLI_TEMPLATE and cli-template references with your CLI name
3. Run pnpm install
4. Run holocron setup to configure branch protection, labels, workflows, and repo settings

Installation

npm install --global @theholocron/cli-template

Usage

cli-template --help

# Run a command
cli-template log

# Use with debug output
cli-template log --debug

# Use with verbose output
cli-template log --verbose

Environment Variables

Copy .env.example to .env and configure as needed. Variables follow a two-level namespace cascade: HOLOCRON_* sets org-wide defaults, CLI_TEMPLATE_* overrides them per-tool. Replace both prefixes with your own when building on this template.

Variable	Default	Description
CLI_TEMPLATE_DEBUG	false	Enable debug output
CLI_TEMPLATE_VERBOSE	false	Enable verbose logging
CLI_TEMPLATE_SENTRY_DSN	—	Sentry DSN — enables error telemetry when set
CLI_TEMPLATE_NO_TELEMETRY	—	Set to any value to opt out of error telemetry

Development

pnpm build         # compile src/ → dist/
pnpm dev         # run via tsx (no build needed)
pnpm test          # run tests
pnpm test:coverage # run tests with coverage
pnpm typecheck     # type-check without emitting
pnpm lint          # run super-linter locally (requires Docker)

What's Included

Category	Tool	Purpose
CLI framework	Yargs	Command routing, option parsing, env-var binding, auto-completion
Prompts	Inquirer	Interactive select, confirm, and search prompts
Config	Conf	Persistent user preferences with JSON-schema validation
Logging	Winston	Structured file logging; terminal output via style utilities
Terminal UI	Chalk + Ora	Colour output and spinners for long-running tasks
Environment	@theholocron/env-utils	Namespace-scoped env var parsing with cascade priority
Updates	update-notifier	Prompts users to upgrade when a new version is published
Telemetry	Sentry	Error tracking and command-level tracing; disabled until DSN is set
Build	tsdown	Compiles src/cli.ts → dist/cli.mjs with a Node.js shebang
CI/CD	GitHub Actions + semantic-release	Automated lint, test, typecheck, and publish on push to main

Releases

Releases are automated via semantic-release on push to main. See CHANGELOG.md for the release history.