Note

This is a template repository for command-line tools written in TypeScript and run with Bun. For libraries, see template-typescript-vite.

How to use

git clone https://github.com/templecon/template-typescript-cli
cd template-typescript-cli
bun install
bun start -- greet world

Requirements

Bun 1.4 or higher. The version is pinned in the packageManager field of package.json, and CI reads it from there.

Using This Template

After creating a project from this template:

1. Upgrade all dependencies and refresh the lockfile with bun update --latest, then run bun run check and bun run build and fix every error.
2. Set your CLI's identity in package.json: name, and the key of the single bin entry. The command name shown in --help follows the bin key, and the tests read the entry from package.json, so no other file has to change for the rename.
3. Replace the example greet command and the description in src/program.ts with your own commands.
4. Update the intro and clone URL in this README.

Toolchain

Job	Tool
Packages	bun install (bun.lock)
Bundling	Bun.build in scripts/build.ts
Tests	bun test, configured in bunfig.toml
Format / lint	oxfmt / oxlint (type-aware, replaces tsc)
Argument parsing	commander

bunfig.toml refuses package versions younger than a day. Unlike pnpm's trustPolicy: no-downgrade, Bun has no equivalent check for a weakened publishing trust level, so review upgrades of important dependencies yourself.

Running the built CLI

bun run build writes dist/cli.js. The first line is a shebang chosen by the TARGET constant in scripts/build.ts:

• "bun" (default): #!/usr/bin/env bun. bunx your-package works, npx your-package needs Bun on the PATH. Bun APIs are available.
• "node": #!/usr/bin/env node. Works with npx and bunx alike. Use it when the code does not need Bun APIs and Node users should be able to run it.

Change that one constant to switch. The shebang is added by the build; do not also write one in src/cli.ts, the output would then have two.

Publishing

This template is intentionally private so cloning it cannot accidentally publish the template itself. Before the first release, make sure the name and bin entry are unique (see Using This Template), then set a version, repository (npm checks it against the workflow's repository for provenance), and set private to false.

The Publish workflow uses npm Trusted Publishing (GitHub Actions OIDC) with provenance and holds no npm token. It builds and tests with Bun, then publishes with npm publish, because bun publish supports neither OIDC nor provenance yet.

1. Publish the package once, then in the package's npm settings add a trusted publisher: GitHub Actions, this repository, workflow file publish.yml.
2. The workflow runs on manual dispatch only. To publish on version tags instead, uncomment the push.tags trigger in .github/workflows/publish.yml.

Conventions and Rules

Project conventions are available from the conventions MCP server. The project agent guidance identifies the applicable TypeScript, schema, and test conventions.