@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.