Guide · Open source
How to use cz-cli: install Commitizen and write commit messages
Updated · written with AI from the project's own documentation and checked against our catalogue data
cz-cli is the command line tool for Commitizen, an MIT-licensed JavaScript utility that replaces git commit with an interactive prompt. Instead of writing a commit message from scratch, you answer questions and the tool formats the message to match your project's convention. This guide covers installing it, committing with it, and setting up a repository so it knows which format to use.
Commitizencommitizen/cz-cli · ★ 17.5k · MIT Install options & downloads Quick start
- 1Install cz-cli. Run npm install -g commitizen with Node.js and npm 6 or greater installed.
- 2Initialize the adapter. In your project, run commitizen init cz-conventional-changelog with the flags for your package manager.
- 3Check package.json. Confirm that config.commitizen.path is set, or that a .czrc file contains the same path.
- 4Commit with cz. Run git cz, cz, or npx cz and answer the prompts instead of using git commit.
- 5Add a script (optional). Add "commit": "cz" to the scripts section of package.json so contributors can run npm run commit.
Check prerequisites and install cz-cli
Commitizen is tested against Node.js 12, 14, and 16, and may work on older versions of Node.js. You should also have npm 6 or greater.
Install it globally with npm. If you see an EACCES error, the README points to npm's guide on fixing npm permissions.
npm install -g commitizenCommit with cz instead of git commit
In a Commitizen-friendly repository, run cz or git cz instead of git commit. You can also use git-cz, which is an alias for cz. You will be prompted to fill in any required fields, and the message will follow the standard the project maintainers defined.
If you have npm 5.2 or later and do not want a global install, you can run npx cz. You can also add a script to package.json so contributors can run it through npm.
git cz
# or
cz
# or without a global install (npm 5.2+)
npx czSet up your repo to be Commitizen friendly
A repo becomes Commitizen friendly when it has an adapter configured. The README's example uses the AngularJS commit message convention, through the cz-conventional-changelog adapter. Run the init command for your package manager; the README lists npm, yarn, and pnpm variants.
The init command installs the adapter, saves it to package.json dependencies or devDependencies, and adds a config.commitizen key to package.json. You can instead put the same setting in a .czrc file. The path setting tells Commitizen which adapter contributors should use.
If you need to replace an older adapter, the README mentions the --force argument. Run commitizen help for more information.
- Installs the cz-conventional-changelog adapter npm module
- Saves it to package.json's dependencies or devDependencies
- Adds the config.commitizen key to package.json
# npm
commitizen init cz-conventional-changelog --save-dev --save-exact
# yarn
commitizen init cz-conventional-changelog --yarn --dev --exact
# pnpm
commitizen init cz-conventional-changelog --pnpm --save-dev --save-exactInstall Commitizen locally and add an npm script
Installing Commitizen as a dev dependency makes sure every developer runs the same version. Contributors can then run npm run commit to get the prompts. Note the README's warning: if you use husky precommit hooks, do not name the script commit, because npm runs prexxx scripts automatically. Use a name such as cm instead.
npm install --save-dev commitizen
"scripts": {
"commit": "cz"
}Run Commitizen when contributors type git commit (optional)
Maintainers who want to enforce the format on contributors unfamiliar with Commitizen can hook it into git commit. The README shows two options: a traditional prepare-commit-msg hook, or husky configuration in package.json. Git hooks are not interactive by default, so the hook uses exec < /dev/tty to read from the terminal.
- Traditional: update .git/hooks/prepare-commit-msg
- Husky: add a prepare-commit-msg entry under the husky hooks key in package.json
#!/bin/bash
exec < /dev/tty && node_modules/.bin/cz --hook || trueWhat people use it for
- Enforcing one commit message format across a team's repository
- Helping new contributors follow a project's commit rules without reading CONTRIBUTING.md first
- Producing commit messages that a semantic-release or changelog tool can read, as the README's use of the AngularJS convention shows
- Keeping a shared Commitizen version for every developer by installing it locally
Frequently asked questions
Is cz-cli free to use?
Yes. The repository is licensed under MIT. The source does not list any paid tier.
What do I need to install cz-cli?
The README says Commitizen is tested against Node.js 12, 14, and 16, and you should have npm 6 or greater. Install it with npm install -g commitizen.
What is the difference between cz and git cz?
The README says you can use git cz or just cz instead of git commit. git-cz is an alias for cz, so all three start the same prompt in a Commitizen-friendly repo.
Why does cz say my repo is not Commitizen friendly?
A repo needs an adapter configured before the prompts follow its rules. Run commitizen init with an adapter such as cz-conventional-changelog, which adds a config.commitizen key to package.json or a .czrc file. Without that, the README says the npx cz path uses the streamich/git-cz adapter instead.
What is an adapter in Commitizen?
An adapter is the module that defines the commit message format. The README's example uses cz-conventional-changelog, which follows the AngularJS commit message convention. The path setting can point to an npm module, a directory with index.js, a .js file, or an absolute path.
Can I use cz-cli with husky?
Yes. The README shows a husky configuration that runs npx cz --hook on the prepare-commit-msg hook, using exec < /dev/tty so the prompts work. Also avoid naming the npm script commit when you use precommit hooks.
What are the alternatives to cz-cli?
The source lists git-cz, husky, and commitlint as comparable projects. Note that the README describes husky as a way to run hooks, and the commitizen README says a git hook that rejects commits can still help alongside it.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use cz-cli if your team wants every commit message to follow one format, or if new contributors need prompts instead of rules to memorise, and your project already uses a commit convention. Skip it if you are a solo developer happy writing your own messages, or if your project has no commit format for an adapter to enforce.
Install options & downloads