CLI Interface

Command-line interface for creating GitHub releases from git metadata using conventional changelog conventions.

Capabilities

CLI Binary

Executable command-line tool for creating GitHub releases.

# Global installation
npm install -g conventional-github-releaser

# Usage
conventional-github-releaser [options]

Authentication Setup

You can supply your auth token via flag or environment variable:

# Using flag
conventional-github-releaser -t your-github-token -p angular

# Using environment variable (recommended)
export CONVENTIONAL_GITHUB_RELEASER_TOKEN=your-github-token
conventional-github-releaser -p angular

Token Requirements: Create a GitHub Personal Token with public_repo or repo scope (for private repos).

Command Options

# URL of your GitHub provider (default: https://api.github.com/)
-u, --url <url>

# Your GitHub auth token
-t, --token <token>

# Preset name (required for most usage)
-p, --preset <preset>

# Path to package.json file (default: closest package.json from cwd)
-k, --pkg <path>

# Number of releases to generate (default: 1, 0 for all)
-r, --release-count <number>

# Enable verbose output for debugging (default: false)
-v, --verbose

# Path to config script
-n, --config <path>

# Path to context javascript file
-c, --context <path>

# Publish as draft release (default: false)
-d, --draft

Preset Options

Supported conventional changelog presets:

• angular - Angular commit convention (most common)
• atom - Atom editor commit convention
• codemirror - CodeMirror commit convention
• ember - Ember.js commit convention
• eslint - ESLint commit convention
• express - Express.js commit convention
• jquery - jQuery commit convention
• jscs - JSCS commit convention
• jshint - JSHint commit convention

Usage Examples:

# Create release using Angular preset
conventional-github-releaser -p angular

# Generate all historical releases (first time use)
conventional-github-releaser -p angular -r 0

# Create draft release for review
conventional-github-releaser -p angular -d

# Verbose output for debugging
conventional-github-releaser -p angular -v

# Use custom GitHub enterprise URL
conventional-github-releaser -p angular -u https://github.company.com/api/v3/

Configuration Files

Custom Config Script

Create a custom configuration file to override default behavior:

// config.js
module.exports = {
  gitRawCommitsOpts: {
    // Custom git options
  },
  parserOpts: {
    // Custom parser options
  },
  writerOpts: {
    // Custom writer options
  }
};

Usage:

conventional-github-releaser -p angular -n ./config.js

Context File

Define template variables for release notes:

// context.js
module.exports = {
  owner: 'myorg',
  repository: 'myrepo',
  customVar: 'value'
};

Usage:

conventional-github-releaser -p angular -c ./context.js

Workflow Integration

Recommended Workflow:

1. Make changes
2. Commit changes using conventional format
3. Ensure CI tests pass
4. Bump version in package.json
5. Commit package.json changes
6. Create and push git tag
7. Run conventional-github-releaser

Package.json Integration:

{
  "scripts": {
    "github-release": "conventional-github-releaser -p angular",
    "github-release-all": "conventional-github-releaser -p angular -r 0"
  }
}

Environment Variables

The CLI respects these environment variables:

• CONVENTIONAL_GITHUB_RELEASER_TOKEN: GitHub authentication token
• CONVENTIONAL_GITHUB_URL: GitHub API URL (defaults to 'https://api.github.com/')
• DEBUG: Set to 'conventional-github-releaser' to enable debug logging

Error Handling

• Exit Code 0: Success
• Exit Code 1: Error occurred (details printed to stderr)
• No Semver Tags: Error if no semver tags found in repository
• Authentication Failures: Error if token is invalid or insufficient permissions
• Network Errors: Error if GitHub API is unreachable

Common Issues

"No semver tags found": Ensure your repository has at least one semver-formatted git tag (e.g., v1.0.0).

Authentication errors: Verify your token has correct permissions (public_repo or repo scope).

Empty releases: Check that your commits follow the conventional format expected by your chosen preset.