gitmoji-cli: An Interactive Emoji Commit Client for Node.js Projects

The commit message problem gitmoji-cli addresses

The gitmoji convention prefixes a commit subject with an emoji that classifies the change: a bug fix, a new feature, a documentation edit. The convention is easy to state and annoying to follow. You have to remember which emoji maps to which category, and you have to type it. Most people end up with a personal subset of four or five emojis and no consistency across a team.

gitmoji-cli is the command line client for that convention. The README describes it as "a gitmoji interactive client for using gitmojis on commit messages" and says it "solves the hassle of searching through the gitmoji list". The audience is developers who already accept the convention and want the selection step automated. It is not a linter, it does not rewrite history, and it does not enforce anything on a server. It builds one commit message at a time, either from an interactive prompt or from a git hook.

How the interactive prompt and the hook build a commit

The tool ships a single binary named gitmoji, declared in package.json as lib/cli.js, built by Babel from src/ into lib/. It is an ES module package with engines set to node >=18. The runtime dependencies tell you the shape of the mechanism: inquirer and inquirer-autocomplete-prompt drive the prompts, fuse.js powers fuzzy search over the emoji list, node-fetch and proxy-agent retrieve the list from an API, conf stores configuration, and ora renders the spinner.

The emoji data itself is not baked into the binary as the only source. The README states that the first time you run gitmoji the CLI creates a cache so the tool works without an internet connection, and gitmoji -u syncs the emoji list with the repository. The default gitmojisUrl in the documented config is https://gitmoji.dev/api/gitmojis, and you can point it at a custom URL. That is the data flow: fetch once, cache locally, search the cache with fuse.js, then compose the subject line.

Composition follows the Conventional Commits shape. The prompt asks for a title, optionally a scope and a message, and the config exposes scopePrompt and messagePrompt to turn those steps off, plus capitalizeTitle and emojiFormat, which switches between the emoji character and its shortcode. autoAdd controls whether git add . runs before the commit. The README warns that the hook mode should not be used together with gitmoji -c, which makes sense: both want to own the commit message, and running them together would nest one prompt inside another.

Installing gitmoji-cli and making a first commit

There are two documented install paths. The npm one is global:

npm i -g gitmoji-cli

The brew formula installs the same tool under the name gitmoji:

brew install gitmoji

After either, gitmoji --help prints the usage block. The version subcommand is the quickest way to confirm the binary is on your PATH:

gitmoji -v

For a first real commit, the client mode is the shorter path. Stage your work, then start the interactive prompt:

git add .
gitmoji -c

The prompts build the commit message and the commit is created for you. If you would rather skip the typing steps, the README shows default values passed as flags:

gitmoji -c --title="Commit" --message="Message" --scope="Scope"

The hook mode is the one the README recommends for project integration, because it works with other tools. Initialize it once per repository, then commit normally:

gitmoji -i
git add .
git commit

At this point git commit triggers the prompts instead of opening an editor. To undo it, the help output lists --remove, -r. If you want to browse before committing, gitmoji -l pretty-prints the cached list and gitmoji -s "criteria" searches it.

Configuration precedence and where it surprises people

The config system has five layers, and the README states the order of precedence explicitly: a gitmoji key in package.json, then .gitmojirc.json, then a gitmoji key in a package.json in a parent directory (recursively), then a .gitmojirc.json in a parent directory (recursively), then the global CLI configuration. If nothing is found, defaults apply.

The recursion is the part worth thinking about. A .gitmojirc.json sitting in a monorepo root will apply to every package beneath it unless a nearer file overrides it, which is convenient until someone adds a package-level file and silently changes the prompt behavior for that directory only. The documented keys are autoAdd, emojiFormat, scopePrompt, messagePrompt, capitalizeTitle and gitmojisUrl. A package.json entry looks like this:

{
  "gitmoji": {
    "autoAdd": false,
    "emojiFormat": "code | emoji",
    "scopePrompt": false,
    "messagePrompt": false,
    "capitalizeTitle": true,
    "gitmojisUrl": "https://gitmoji.dev/api/gitmojis"
  }
}

The .gitmojirc.json form drops the wrapping key and holds the same fields. Note that the README writes emojiFormat as the literal "code | emoji", which is documentation shorthand for the two accepted values rather than a value you should copy. For a one-off change, gitmoji -g opens the preferences prompt and writes the global configuration. Switching gitmojisUrl to an internal mirror is the supported way to run this in a network that cannot reach gitmoji.dev.

Where gitmoji-cli is the wrong tool

The obvious limitation is the runtime. package.json sets engines to node >=18 and the bin entry points at a Babel-compiled lib/cli.js, so the npm install path assumes Node.js on the machine doing the committing. The package script section does contain a pkg build that targets latest-linux-x64, latest-macos-x64 and latest-win-x64, but the README documents only npm and brew as install routes, so a standalone binary is not the advertised path. If your team commits from machines where you cannot install a Node toolchain, this is the wrong choice.

The second limitation is that the tool is a message builder, not a policy. It will happily produce a commit with an emoji you did not want, and nothing checks the result afterward. The README does not document any validation hook or CI check, so enforcement on a shared branch is your problem, not the tool's.

Third, the cache is a real dependency. The offline behavior is a feature, but it means a stale cache produces a stale emoji list until someone runs gitmoji -u. Treat -u as part of upgrading the CLI rather than a thing you remember occasionally.

Finally, the README is thin on failure modes. It does not document what happens when gitmojisUrl is unreachable on a cold start with no cache, nor does it describe rollback after gitmoji -i. The help output lists --remove, -r, which is the documented escape hatch, but the README itself does not explain it.

How gitmoji-cli differs from commitlint and commitizen

The nearest alternatives attack the same problem from different directions. commitizen replaces the commit prompt with its own adapter and is typically paired with cz-conventional-changelog; it targets the Conventional Commits text format and has no opinion about emojis. gitmoji-cli targets the emoji prefix and treats scope and message as optional prompts you can switch off with scopePrompt and messagePrompt.

commitlint sits on the other side of the boundary. It is a linter that reads a finished commit message and rejects it if it does not match a configured rule set. gitmoji-cli never inspects a message it did not write. A team that wants both consistency and enforcement usually runs a prompt tool to author the message and a linter in a git hook or CI to reject bad ones. gitmoji-cli covers only the first half.

The comparison that matters for adoption is the hook mode. gitmoji -i installs itself as a commit hook, so the prompt appears on plain git commit and the workflow stays inside git. That is a lighter integration than asking every developer to remember a separate commit command, and it is why the README recommends hook mode for project integration over client mode.

Licence, maintenance and upgrade cost

The repository is MIT licensed, which permits commercial use and modification provided the copyright notice and permission notice are retained. That is the standard permissive arrangement and it also means there is no warranty. Nothing here is legal advice; if you redistribute a modified build, read the LICENSE file at the repository root.

On maintenance, the last push to the default branch was on 2026-09-22, and the repository is not archived. The most recent release listed is v9.7.0 on 2025-05-16, following v9.6.0 on 2025-04-15 and v9.5.0 on 2024-10-09. The release cadence is irregular rather than steady, so pinning a version and upgrading deliberately is more realistic than tracking master.

The upgrade cost is mostly the emoji list, not the code. Because the CLI caches gitmojis and exposes gitmoji -u to resync, a version bump can change which emojis appear in the prompt without any change to your config. If your reviewers recognize a fixed set of prefixes, resync and check gitmoji -l before rolling the new version out to the team. The dependency set includes several major-version packages, so a major release of the CLI may require a newer Node.js than the current engines floor of 18.

Editorial conclusion

Adopt gitmoji-cli if your team already writes Conventional Commits and wants the emoji prefix chosen from a prompt instead of typed by hand. Skip it if you do not want a Node.js runtime on every machine that commits, or if you need a GUI. Before rolling it out, run gitmoji -l on one machine to confirm the cached emoji list matches the format your reviewers expect, and decide whether autoAdd should stay false.

Frequently asked questions

Official sources

1. carloscuesta/gitmoji-cli on GitHub
2. License: MIT
3. Project website
4. README
5. Releases