Gitmoji Commit CLI

Scriptable CLI for formatting, validating, suggesting, and creating gitmoji commits.

Install

npm install -g gitmoji-commit-cli

Commands

• gitmoji-commit format
• gitmoji-commit validate
• gitmoji-commit suggest
• gitmoji-commit commit
• gitmoji-commit install

Command Details

format

Build a commit message without touching git.

Usage: gitmoji-commit format [options]

Format a commit message without touching git.

Options:
  --type <type>                Commit type.
  --title <title>              Commit title.
  --scope <scope>              Optional commit scope.
  --description <description>  Optional commit body.
  --breaking                   Mark the commit as breaking.
  --breaking-note <note>       Optional BREAKING CHANGE footer text.
  --json                       Output machine-readable JSON.
  -h, --help                   display help for command

Example:

gitmoji-commit format --type feat --scope auth --title "add OAuth login" --description "Implement the first provider flow."

validate

Validate a commit message from a flag, a file, or stdin.

Usage: gitmoji-commit validate [options]

Validate a commit message from --message, --file, or stdin.

Options:
  --message <message>  Commit message to validate.
  --file <path>        Read the commit message from a file.
  --json               Output machine-readable JSON.
  -h, --help           display help for command

Examples:

gitmoji-commit validate --message "✨ feat(auth): add OAuth login"
gitmoji-commit validate --file .git/COMMIT_EDITMSG
cat <<'EOF' | gitmoji-commit validate
✨ feat(auth): add OAuth login
EOF

suggest

Suggest a commit type from staged changes.

Usage: gitmoji-commit suggest [options]

Suggest a commit type based on staged changes.

Options:
  --repo <path>  Path to the target git repository.
  --json         Output machine-readable JSON.
  -h, --help     display help for command

Example:

gitmoji-commit suggest --repo /path/to/repo

commit

Validate and create a git commit from staged changes. Use --dry-run to preview the exact message and checks without writing a commit.

Usage: gitmoji-commit commit [options]

Create a git commit using the gitmoji convention.

Options:
  --type <type>                Commit type.
  --title <title>              Commit title.
  --scope <scope>              Optional commit scope.
  --description <description>  Optional commit body.
  --breaking                   Mark the commit as breaking.
  --breaking-note <note>       Optional BREAKING CHANGE footer text.
  --repo <path>                Path to the target git repository.
  --dry-run                    Build and validate the commit message without
                               creating the commit.
  --json                       Output machine-readable JSON.
  -h, --help                   display help for command

Examples:

gitmoji-commit commit --type fix --title "handle empty state"
gitmoji-commit commit --type feat --title "rename public API" --breaking --breaking-note "Consumers must switch to the new endpoint names."
gitmoji-commit commit --type chore --title "tidy scripts" --dry-run

install

Install the shipped skill pack into Codex and/or Claude Code directories.

Usage: gitmoji-commit install [options]

Install shipped skill files for Codex and Claude Code.

Options:
  --skills           Optional compatibility flag. The install command already
                     installs the shipped skill pack.
  --target <target>  Install target. (choices: "codex", "claude", "all",
                     default: "all")
  --dir <path>       Install into an explicit directory instead of the default
                     target location.
  --json             Output machine-readable JSON.
  -h, --help         display help for command

Default targets:

• Codex: ~/.codex/skills/gitmoji-commit-cli
• Claude Code: ~/.claude/skills/gitmoji-commit-cli

Examples:

gitmoji-commit install
gitmoji-commit install --target codex
gitmoji-commit install --dir ./tmp/gitmoji-skill

Commit Types

Primary Types

| Type | Emoji | Description | |------|-------|-------------| | feat | ✨ | A new feature | | fix | 🐛 | A bug fix | | docs | 📝 | Documentation only changes | | style | 🎨 | Code formatting with no logic change | | refactor | ♻️ | Code restructuring without feature or fix changes | | perf | ⚡ | Performance improvements | | test | 🧪 | Adding or updating tests | | build | 📦 | Build tooling and packaging changes | | ci | 👷 | CI/CD configuration changes | | chore | 🔧 | Maintenance tasks and repo housekeeping | | revert | ⏪ | Revert a previous commit |

Extended Types

| Type | Emoji | Description | |------|-------|-------------| | security | 🔒 | Security fixes | | deprecate | ⚠️ | Deprecation work | | breaking | 💥 | Explicit breaking-change commit type | | i18n | 🌐 | Internationalization changes | | a11y | ♿ | Accessibility improvements | | deps | ⬆️ | Dependency updates |

Commit Message Format

<emoji> <type>(<scope>): <title>

<description>

BREAKING CHANGE: <note>

Rules:

• The title should be imperative, lowercase-first, and without a trailing period.
• The recommended title limit is 50 characters.
• Separate the title from the description with a blank line.
• Wrap description lines around 72 characters when possible.
• Use --breaking-note only when you want an explicit BREAKING CHANGE: footer.
• Do not combine type=breaking with --breaking; pick one style.

Repository Resolution

Git-aware commands resolve the target repository in this order:

1. --repo
2. Environment variables: GITMOJI_REPO_PATH, GITMOJI_COMMIT_REPO_PATH, PROJECT_ROOT, INIT_CWD, PWD
3. The current working directory

For wrappers or agent workflows that execute outside the repository, prefer passing --repo explicitly.

Quick Start

gitmoji-commit suggest
gitmoji-commit format --type feat --title "add OAuth login"
gitmoji-commit commit --type feat --title "add OAuth login"

Skills

gitmoji-commit install

Help

Usage: gitmoji-commit [options] [command]

Format, validate, suggest, and create gitmoji commits.

Options:
  -V, --version       output the version number
  -h, --help          display help for command

Commands:
  format [options]    Format a commit message without touching git.
  validate [options]  Validate a commit message from --message, --file, or
                      stdin.
  suggest [options]   Suggest a commit type based on staged changes.
  commit [options]    Create a git commit using the gitmoji convention.
  install [options]   Install shipped skill files for Codex and Claude Code.
  help [command]      display help for command