# commitizen/cz-cli: interactive commit prompts for conventional commits

> cz-cli replaces git commit with a guided prompt and hands the message format to a pluggable adapter. Here is what it does, how to install it, and where it stops being the right tool.

**commitizen/cz-cli** — The commitizen command line utility. #BlackLivesMatter

- Repository: https://github.com/commitizen/cz-cli
- Website: http://commitizen.github.io/cz-cli/
- Stars: 17,496 · Forks: 566
- Language: JavaScript
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/commitizen-cz-cli

## What cz-cli solves, and who ends up using it

A commit hook that rejects a malformed message tells you what went wrong after you have already written the message. The README frames the trade-off directly: with Commitizen you are "prompted to fill out any required commit fields at commit time", rather than waiting for a hook to run and reject the commit. It also removes the step of opening CONTRIBUTING.md to look up the preferred format.

The people who benefit are contributors to a repository that has a convention but no convenient way to follow it. That is usually an open source project with outside contributors, or a team where commits feed a changelog generator. The maintainer decides the format once; every contributor gets the same prompt.

It is not a linter and it is not a hook. Nothing in the README describes cz-cli rejecting a commit message. It builds a message through prompts and passes it to git. If you want enforcement, that is a separate concern.

## The adapter is the whole design

cz-cli is a prompt runner with no opinion about commit format. The format lives in an adapter, and the repository points at one through a single config key. When you run the init command, the README says it does three things: installs the adapter npm module, saves it to dependencies or devDependencies, and adds the config.commitizen key to the root of package.json.

The value is resolved through require.resolve, which the README says supports npm modules, directories relative to process.cwd() containing an index.js, file base names relative to process.cwd() with a .js extension, full relative file names, and absolute paths. That is a wider set than a plain module name, and it means an adapter can live inside the repository rather than on npm.

Config can sit in package.json or in a .czrc file. The README notes that czConfig, the older key, is deprecated and should be migrated before Commitizen 3.0.0. If you find czConfig in an old repository, that is the reason it stopped working.

The consequence of this split is that two repositories using cz-cli can produce completely different commit messages. cz-cli is the mechanism, not the standard.

## Installing cz-cli and making a repository Commitizen friendly

The README states the tool is tested against Node.js 12, 14, and 16, and that npm 6 or greater is expected. Installation is global if you want the command available everywhere:

```bash
npm install -g commitizen
```

If that fails with an EACCES error, the README points at npm's own guide to fixing npm permissions rather than suggesting sudo.

A globally installed cz-cli still does nothing useful in a repository that has no adapter. The init command sets one up. The README gives the AngularJS convention, also called conventional-changelog, as the example, with a variant per package manager:

```bash
commitizen init cz-conventional-changelog --save-dev --save-exact
```

For yarn the README uses `commitizen init cz-conventional-changelog --yarn --dev --exact`, and for pnpm `commitizen init cz-conventional-changelog --pnpm --save-dev --save-exact`. If an older adapter is already present and you want to replace it, the README documents a --force argument.

After init, package.json should contain this block. If it is missing, the init step did not complete and the prompts will not appear:

```json
"config": {
  "commitizen": {
    "path": "cz-conventional-changelog"
  }
}
```

With that in place, commit with git cz or cz instead of git commit. git-cz is an alias for cz. The README shows the prompts being filled in and the message being formatted to whatever the adapter defines.

If you prefer not to install globally, install locally with npm install --save-dev commitizen and use npx. On npm 5.2 or later, `npx commitizen init cz-conventional-changelog --save-dev --save-exact` initializes the adapter. On npm older than 5.2, the README says to call `./node_modules/.bin/commitizen` or `./node_modules/.bin/cz` directly.

There is one trap documented in the README. If you add an npm script named commit and you also run precommit hooks through husky, npm will run the precommit script automatically when you invoke commit. The README's advice is to name the script something else, for example "cm": "cz".

## The case where git cz silently does nothing different

The README is explicit about a failure mode that is easy to miss. In a repository that is not Commitizen friendly, git cz behaves exactly like git commit. No prompt, no format, no warning that anything was skipped.

Worse, the behaviour differs by invocation. In that same unfriendly repository, npx cz will fall back to the streamich/git-cz adapter rather than failing. So a developer who runs npx cz gets prompts, and a developer who runs git cz in the same repository gets a plain commit. The README's fix is to make the repository Commitizen friendly first.

This matters for onboarding. A new contributor with a global install who types git cz out of habit in a repository nobody configured will believe the tool is working. The commit goes through unformatted, and the problem surfaces later in changelog generation or in review, which is the exact delay cz-cli was supposed to remove.

A second limitation is scope. cz-cli only runs when someone chooses to run it. It does not intercept git commit. A contributor who never installs it, or who uses a GUI client, bypasses the prompt entirely. If your convention has to hold for every commit, cz-cli is one layer and a hook is another.

## cz-cli compared with a commit-msg hook

The README itself points at validate-commit-msg as something that "can still be helpful" alongside Commitizen, which is a fair description of the difference. A commit-msg hook inspects the message after it is written and fails the commit if it does not match. cz-cli asks for the fields before the message exists.

The difference in practice is who absorbs the cost. With a hook, the contributor writes a message, gets rejected, rewrites it, and commits again. With cz-cli, the contributor answers prompts once. For a convention with several required fields, the prompt is faster; for a convention with one rule, a hook is less machinery.

The two are not exclusive, and the README treats them as complementary. A hook still catches the commits made outside cz-cli, including from editors and GUI clients. cz-cli still gives contributors a format reference without opening CONTRIBUTING.md. If you already have a hook that works and your contributors do not complain about it, adding cz-cli buys convenience, not correctness.

If you compare against gitmoji-cli, the distinction is the same one that runs through this project: gitmoji-cli ships its own emoji convention, while cz-cli ships none and defers to whichever adapter you configure. If you want one fixed convention with no setup decisions, a tool that bundles its convention is simpler. If you want the convention to be a repository-level decision, the adapter model is the point.

## Maintenance, releases and what the MIT licence covers

The last push to the default branch was on 2026-09-04, so the repository is not dormant, but the release cadence is uneven. v4.3.2 was published on 2026-06-12, v4.3.1 on 2024-09-27, and v4.3.0 on 2023-01-19. Between v4.3.0 and v4.3.1 there is a gap of more than a year and a half. Upgrading is therefore a low-frequency event, but do not assume a fix will arrive on a predictable schedule.

The project is MIT licensed, which permits commercial and private use and modification. That is a statement about the licence text, not legal advice; if your organisation has licence policy, run it through that.

One practical upgrade cost sits in the config format rather than the code. The README records that czConfig is deprecated and should be migrated before Commitizen 3.0.0. Repositories that still carry czConfig need that key moved to config.commitizen before they can rely on current behaviour. The other recurring cost is the adapter itself, which is a separate dependency with its own release history. Upgrading cz-cli does not upgrade the adapter, and a convention change usually means changing the adapter rather than the CLI.

## Reading the repository layout before you adopt it

The top level holds bin/, src/, test/, and a build step that compiles src to dist with Babel, which is what the package.json main field points at. The published bin entries are cz, git-cz, and commitizen, all mapping to files under bin/. That matches the three invocation names in the README and confirms they are the same tool under different names.

The repository's own package.json configures cz-cli on itself, with config.commitizen.path set to ./node_modules/cz-conventional-changelog. In other words, the project uses the tool it publishes, pointed at a relative path inside node_modules rather than a bare module name. That is a working example of the require.resolve behaviour the README describes, and it is a useful reference if you want to check that your own path resolves.

That same file also wires a ghooks pre-commit to run the test suite and a coverage check. It is a maintainer configuration, not something cz-cli installs for you. If you were expecting cz-cli to set up validation on adoption, the repository layout shows the opposite: the project does that work itself, separately.

## Conclusion

Adopt cz-cli if your team already enforces a commit message convention and you want contributors to get the format right at commit time instead of in review or in a failing hook. Skip it if a hook that rejects bad messages is enough, if you cannot add a Node.js toolchain to the repository, or if your team will not agree on one adapter. Before rolling it out, verify three things: that the adapter named in config.commitizen.path resolves from the repository root, that your npm script is not named commit when husky runs a precommit hook, and that the adapter you picked is the one your changelog tooling expects, since cz-cli itself does not validate the message it produces.

## FAQ

### What is commitizen/cz-cli used for?

It replaces git commit with an interactive prompt so that required commit message fields are filled in at commit time instead of being rejected later by a hook. The message format comes from whichever adapter the repository configures, not from cz-cli itself.

### How do I make a commit with git cz?

Once the repository is Commitizen friendly, use git cz or cz instead of git commit, or run npx cz. The README notes that git-cz is an alias for cz, and that in a repository with no adapter, git cz behaves the same as git commit.

### Does cz-cli work if my repository has no Commitizen configuration?

The README states that in a repository that is not Commitizen friendly, git cz works just the same as git commit, with no prompts. npx cz behaves differently in that situation and uses the streamich/git-cz adapter instead.

### Which Node.js and npm versions does cz-cli require?

The README says Commitizen is tested against Node.js 12, 14, and 16, though it may work on older versions, and that you should have npm 6 or greater.

### Where does cz-cli store the adapter configuration?

The init command adds a config.commitizen key to the root of package.json, and the README also shows the same setting in a .czrc file. The older czConfig key is deprecated and should be migrated before Commitizen 3.0.0.

## Sources

- [commitizen/cz-cli on GitHub](https://github.com/commitizen/cz-cli)
- [License: MIT](https://github.com/commitizen/cz-cli/blob/master/LICENSE)
- [Project website](http://commitizen.github.io/cz-cli/)
- [README](https://github.com/commitizen/cz-cli/blob/master/README.md)
- [Releases](https://github.com/commitizen/cz-cli/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/commitizen-cz-cli