{"id":16979,"library":"czg","title":"Interactive Git Commit Message CLI","description":"czg is an interactive command-line interface (CLI) tool designed to streamline the process of generating standardized Git commit messages, primarily adhering to the Conventional Commits specification. Currently at version 1.12.0, the package maintains an active release cadence with frequent updates. It functions as a lightweight, zero-dependency wrapper for Commitizen, leveraging the core features and extensive customization options of `cz-git`. Key differentiators include its interactive prompts, support for AI-generated commit messages via OpenAI integration, and seamless compatibility with `commitlint` for message validation. It aims to simplify commit consistency across projects, making it a valuable tool for TypeScript and Node.js development environments.","status":"active","version":"1.12.0","language":"javascript","source_language":"en","source_url":"https://github.com/Zhengqbbb/cz-git","tags":["javascript","openai","commit","commit CLI","commit message","commitizen","commitizen-cli","cli","cz-git","typescript"],"install":[{"cmd":"npm install czg","lang":"bash","label":"npm"},{"cmd":"yarn add czg","lang":"bash","label":"yarn"},{"cmd":"pnpm add czg","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primarily used in CommonJS configuration files (e.g., .cz.js) to define the czg prompt configuration with type safety. This specific export is for CJS compatibility.","wrong":"import { definePrompt } from 'czg'","symbol":"definePrompt","correct":"const { definePrompt } = require('czg')"},{"note":"Type definition for czg (which re-exports cz-git's) user configuration. Essential for type-checking when defining configuration files in TypeScript projects.","wrong":"import { UserConfig } from 'czg'","symbol":"UserConfig","correct":"import type { UserConfig } from 'czg'"},{"note":"Helper function for defining czg configuration objects (often in .cz-git.cjs or commitlint.config.js files) to gain type inference and validation. Typically used in ESM contexts or with TypeScript.","wrong":"const defineConfig = require('czg').defineConfig","symbol":"defineConfig","correct":"import { defineConfig } from 'czg'"}],"quickstart":{"code":"{\n  \"scripts\": {\n    \"commit\": \"czg\"\n  },\n  \"config\": {\n    \"commitizen\": {\n      \"path\": \"cz-git\"\n    }\n  }\n}\n\n// To use it interactively:\nnpx czg\n\n// Or if configured in package.json:\nnpm run commit\n\n// Example with custom config file:\nnpx czg --config './.cz-config.js'\n\n// Example using AI to generate commit message (requires OPENAI_API_KEY environment variable)\nprocess.env.OPENAI_API_KEY ??= 'sk-your-openai-api-key'; // For local testing, ensure you set this\nnpx czg ai -M=\"gpt-4o-mini\"\n\n// Example .cz-config.js for programmatic configuration (using defineConfig from czg)\n// /** @type {import('czg').UserConfig} */\n// const config = defineConfig({\n//   rules: {\n//     'type-enum': [\n//       2,\n//       'always',\n//       [\n//         'feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore', 'revert', 'wip'\n//       ]\n//     ],\n//     'scope-enum': [\n//       2,\n//       'always',\n//       [\n//         'core', 'components', 'utils', 'config', 'deps', 'release'\n//       ]\n//     ]\n//   },\n//   prompt: {\n//     scopes: ['core', 'components', 'utils', 'config', 'deps', 'release']\n//   }\n// })\n// module.exports = config;","lang":"typescript","description":"This quickstart demonstrates how to install and run the `czg` CLI tool, including how to invoke it directly, through an npm script, with a custom configuration file, and utilize its OpenAI integration for AI-generated commit messages."},"warnings":[{"fix":"Review the changelogs for `cz-git` and `czg` before upgrading, particularly for major versions. Update configuration files (`.czrc`, `commitlint.config.js`, etc.) to match new specifications.","message":"`czg` wraps `cz-git`, and major version upgrades of `cz-git` (e.g., from v1 to v2) can introduce breaking changes in configuration schemas or CLI options. Always consult the `cz-git` changelog for potential impacts on your `czg` setup.","severity":"breaking","affected_versions":">=1.0.0 (indirectly via cz-git)"},{"fix":"Always validate your configuration files against the official documentation and consider using TypeScript with `defineConfig` or `UserConfig` types for compile-time checks, especially for complex setups. Utilize the `$schema` property in JSON configuration files for IDE validation.","message":"Incorrect or malformed configuration files (e.g., `.czrc`, `.cz-git.cjs`, `commitlint.config.js`) are a common source of errors. czg relies heavily on these for customization, and syntax issues or invalid options can prevent the CLI from starting or behaving as expected.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure `OPENAI_API_KEY` is set in your environment variables, passed as a CLI argument (`--api-key=sk-XXXXX`), or configured in your `.czrc` file.","message":"To use `czg`'s OpenAI features for AI-generated commit messages, an `OPENAI_API_KEY` must be provided either via an environment variable or through the `--api-key` CLI option. Without it, AI features will fail or not be available.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your configuration files use the appropriate module syntax (e.g., `module.exports` for CJS, `export default` for ESM/TypeScript) based on your project's `tsconfig.json` or `package.json` `type` field. Use `definePrompt` for CJS config files.","message":"Module resolution differences between CommonJS (CJS) and ES Modules (ESM) can cause issues when `czg` attempts to load configuration files. While `czg` explicitly supports `require('czg')` in `.js` config files, mixing module systems in your project's configuration can lead to 'module not found' errors.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Run `npm install -g czg` or `pnpm install -g czg` for global installation, or use `npx czg` to execute the local package without global installation. If using a package.json script, ensure `czg` is a local dependency.","cause":"`czg` is not installed globally or locally in a way that makes it available in the PATH, or `npx` is not being used to invoke it.","error":"czg: command not found"},{"fix":"Ensure `cz-git` is installed as a dependency (`npm install cz-git`) and that your configuration file's path is correct when specified with `--config`.","cause":"The configuration file for `czg` (often using `cz-git` internally) cannot resolve its dependencies or the path to `cz-git` itself. This can happen if `cz-git` is not installed or module resolution fails.","error":"Error: Failed to load config from './.cz-config.js': Cannot find module 'cz-git'"},{"fix":"Review your configuration files against the `cz-git` documentation. Pay close attention to rules, prompts, and options. Use TypeScript with `defineConfig` or `UserConfig` for validation during development.","cause":"The loaded `czg` or `cz-git` configuration contains invalid properties, types, or violates schema rules.","error":"Error: Configuration validation failed. Please check your .czrc or commitlint.config.js"},{"fix":"Set the `OPENAI_API_KEY` environment variable (e.g., `export OPENAI_API_KEY=sk-...`) or provide it directly via the `--api-key` option (e.g., `czg ai --api-key=sk-...`).","cause":"Attempted to use `czg ai` features without a valid OpenAI API key provided through environment variables or CLI options.","error":"API Key not found or invalid for OpenAI features. Please set OPENAI_API_KEY"}],"ecosystem":"npm","meta_description":null}