kitbash
Menu
Docs Quickstart CLI reference Adapters Trust & review Benchmark Skills Changelog GitHub Support

kitbash / docs / install

Installation

Two routes — npm or Homebrew. Both put a single global kitbash binary on your PATH. Nothing else on your machine changes.

Requirements

Kitbash is a zero-dependency CLI: the published package pulls in no runtime dependencies, only a TypeScript toolchain for building it. That means the requirements are short.

RouteNeeds
npmNode >=20 — the package declares "engines": { "node": ">=20" }, so older Node is refused or warned about at install time
HomebrewHomebrew. The formula brings its own Node, so no system Node is required

Your coding agents need nothing at all. There is no Kitbash runtime — agents read their own native files and never know Kitbash produced them.

Install

npm

npm install -g kitbash

Homebrew

The formula lives in a personal tap. Installing by its full name taps it and installs in one step:

brew install singhharsh1708/tap/kitbash

Verify

kitbash --version

It prints the bare version string and exits:

0.6.0

-v is accepted as a short form. Running kitbash with no arguments (or help, --help, -h) prints the command list instead.

What gets installed where

Two different things live in two different places, and the distinction matters when you uninstall.

ThingLocationCommitted?
The CLI binaryGlobal — your npm prefix or Homebrew prefixNo. It is a tool, like git
kitbash.tomlRepo root, written by kitbash initYes
.kitbash/skills/Repo root, where installed skills landYes
kitbash.lockRepo root, one content hash per skillYes
Compiled output.claude/skills/, .cursor/rules/, AGENTS.md, and so onYes

Everything in the repo is plain text you own. Your team gets the same skills the same way they get the same dependencies — by checking out the repo.

Updating

# npm
npm install -g kitbash@latest

# Homebrew
brew update && brew upgrade kitbash

Confirm with kitbash --version. The KSF core is frozen and evolves additive-only within a major version, so upgrading the CLI does not invalidate skills you already installed.

Uninstalling

# npm
npm uninstall -g kitbash

# Homebrew
brew uninstall kitbash
brew untap singhharsh1708/tap   # optional — removes the tap too

Uninstalling never touches your repo. The compiled output is plain files you own, so your agents keep reading exactly what they read yesterday. Deleting kitbash.toml changes nothing either.

If you want a skill's generated files gone before you remove the CLI, do that first while you still have it:

kitbash remove prereview && kitbash compile

remove deletes .kitbash/skills/<skill> and drops its lockfile entry; the following compile prunes the outputs it had written into each agent's directory. The CLI tells you this itself:

removed prereview
next: kitbash compile (prunes this skill's generated outputs)

Troubleshooting

command not found after npm -g

The package installed, but your npm global bin directory is not on your PATH. Find out where npm puts it:

npm prefix -g

The binary is at <prefix>/bin/kitbash. Add that bin directory to PATH in your shell profile, then open a new shell.

Permission errors on install

An EACCES during npm install -g means npm's global prefix is somewhere your user cannot write. Do not fix it with sudo — that leaves root-owned files in your npm tree and turns every later install into the same fight.

Use a version manager instead. A Node version manager puts the global prefix inside your home directory, so npm install -g needs no elevation at all. Setting an npm prefix you own (npm config set prefix) works too. Either way, the Homebrew route sidesteps the problem entirely.

Which binary is winning

If you have installed both ways, or upgraded and still see the old version, ask the shell which one it resolves:

which kitbash
kitbash --version

A Homebrew path and an npm path can both be present; whichever directory comes first in PATH wins. Remove the one you do not want with the matching uninstall command above, and run hash -r if your shell has cached the old location.

Next

  • Quickstart — init a repo, install a skill, compile it, in about two minutes.
  • CLI reference — every command, flag, and exit code.
  • Project config — what kitbash init writes and how to tune it.