CLI Commands Reference

Complete command-line interface reference for GitFlow Analytics.

🚀 Basic Usage

Default Command (Analyze)

# Simplified syntax (analyze is the default command)
gitflow-analytics [OPTIONS]

# Explicit analyze command (backward compatible)  
gitflow-analytics analyze [OPTIONS]

Examples:

# Basic analysis with configuration file
gitflow-analytics -c config.yaml

# Analyze last 8 weeks
gitflow-analytics -c config.yaml --weeks 8

# Clear cache and re-analyze
gitflow-analytics -c config.yaml --clear-cache

📋 Global Options

Required Options

-c, --config PATH - Path to YAML configuration file

Analysis Options

--weeks INTEGER - Number of weeks to analyze (default: from config)
--clear-cache - Clear analysis cache before running
--skip-identity-analysis - Skip automatic identity resolution
--validate-only - Validate configuration without running analysis

Output Options

--format [csv,json,markdown,all] - Output format(s) to generate
--output-dir PATH - Override output directory from config
--quiet - Suppress progress output
--verbose - Enable verbose logging

Utility Options

--version - Show version information
--help - Show help message and exit

🔧 Subcommands

analyze (default)

Run comprehensive repository analysis and generate reports.

gitflow-analytics analyze -c config.yaml [OPTIONS]

Options:

All global options apply
--repositories TEXT - Comma-separated list of repositories to analyze (overrides config)

Examples:

# Analyze specific repositories only
gitflow-analytics analyze -c config.yaml --repositories "repo1,repo2"

# Quick 2-week analysis with JSON output
gitflow-analytics analyze -c config.yaml --weeks 2 --format json

identities

Manage developer identity resolution and consolidation.

gitflow-analytics identities -c config.yaml [OPTIONS]

Options:

--interactive - Interactive identity resolution mode
--auto-approve - Automatically approve suggested identity mappings
--export PATH - Export identity mappings to YAML file
--import PATH - Import identity mappings from YAML file

Examples:

# Run interactive identity analysis
gitflow-analytics identities -c config.yaml --interactive

# Export current identity mappings
gitflow-analytics identities -c config.yaml --export identity-mappings.yaml

validate

Validate configuration files and system setup.

gitflow-analytics validate -c config.yaml [OPTIONS]

Options:

--check-tokens - Validate GitHub API tokens and permissions
--check-repos - Verify repository access and cloning
--check-ml - Validate ML model availability and setup

Examples:

# Comprehensive validation
gitflow-analytics validate -c config.yaml --check-tokens --check-repos --check-ml

# Quick config validation only
gitflow-analytics validate -c config.yaml

cache

Manage analysis cache and performance optimization.

gitflow-analytics cache [SUBCOMMAND] [OPTIONS]

Subcommands:

clear - Clear all cache databases
status - Show cache statistics and disk usage
optimize - Optimize cache databases (VACUUM)

Examples:

# Clear all caches
gitflow-analytics cache clear

# Show cache status
gitflow-analytics cache status

# Optimize cache performance
gitflow-analytics cache optimize

alias-rename

Rename a developer's canonical display name in manual mappings.

gitflow-analytics alias-rename -c config.yaml \
  --old-name "Current Name" \
  --new-name "New Name" \
  [OPTIONS]

Required Options:

--old-name TEXT - Current canonical name to rename (must exist in manual_mappings)
--new-name TEXT - New canonical display name to use in reports

Optional Flags:

--update-cache - Update cached database records with the new name
--dry-run - Show what would be changed without applying changes

Examples:

# Preview changes with dry-run
gitflow-analytics alias-rename -c config.yaml \
  --old-name "bianco-zaelot" \
  --new-name "Emiliozzo Bianco" \
  --dry-run

# Apply rename to config file only
gitflow-analytics alias-rename -c config.yaml \
  --old-name "bianco-zaelot" \
  --new-name "Emiliozzo Bianco"

# Update both config and database cache
gitflow-analytics alias-rename -c config.yaml \
  --old-name "bianco-zaelot" \
  --new-name "Emiliozzo Bianco" \
  --update-cache

What It Does:

Searches analysis.identity.manual_mappings for the old name
Updates the name field to the new name
Preserves all other fields (primary_email, aliases)
Optionally updates developer_identities and developer_aliases tables

Use Cases:

Fix typos in developer names
Use preferred names or nicknames
Update names after marriage or legal name changes
Standardize name formatting across team

Notes:

Without --update-cache, old name persists in cached data until next analysis
Always test with --dry-run first to preview changes
See Managing Aliases Guide for detailed usage

add-alias

Add alias mappings to a configuration file non-interactively. Suitable for scripting and CI pipelines where interactive prompts are not available.

gfa add-alias -c config.yaml \
  --canonical "developer@example.com" \
  --alias "dev@personal.com" \
  --alias "Dev Name" \
  [OPTIONS]

Required Options:

-c, --config PATH - Path to YAML configuration file

Mapping Options (mutually exclusive — use one or the other):

--canonical EMAIL - Primary/canonical email for this developer identity; combine with one or more --alias flags
--from-file PATH - YAML or JSON file containing batch alias mappings (cannot be combined with --canonical)
--alias EMAIL_OR_NAME - Email address or display name to map to --canonical; repeatable

Behaviour Flags:

--dry-run - Show what would be changed without writing to the config file
--apply - Trigger identity re-resolution after updating the config

Examples:

# Map a personal email and display name to a canonical work email
gfa add-alias -c config.yaml \
  --canonical "alice@company.com" \
  --alias "alice@gmail.com" \
  --alias "Alice Smith"

# Preview changes before writing
gfa add-alias -c config.yaml \
  --canonical "alice@company.com" \
  --alias "alice@gmail.com" \
  --dry-run

# Load batch mappings from a YAML file and re-resolve identities
gfa add-alias -c config.yaml \
  --from-file aliases.yaml \
  --apply

# Load batch mappings from a JSON file
gfa add-alias -c config.yaml \
  --from-file aliases.json

Supported --from-file Formats:

GFA native YAML — a config file with a developer_aliases: key:

developer_aliases:
  - canonical: "alice@company.com"
    aliases: ["alice@gmail.com", "Alice Smith"]

Flat YAML list — a list of {canonical, aliases} objects:

- canonical: "alice@company.com"
  aliases:
    - alice@gmail.com
    - Alice Smith
- canonical: "bob@company.com"
  aliases:
    - bob@personal.com

JSON array — equivalent structure in JSON:

[
  {"canonical": "alice@company.com", "aliases": ["alice@gmail.com", "Alice Smith"]},
  {"canonical": "bob@company.com",   "aliases": ["bob@personal.com"]}
]

What It Does:

Reads the existing analysis.identity.manual_mappings (or developer_aliases) section in the config
Merges new aliases into the matching canonical entry, or creates a new entry if the canonical is not yet present
Skips duplicates — existing aliases are never written twice (idempotent)
Writes the updated config back to disk (unless --dry-run is specified)
Optionally triggers identity re-resolution via --apply

Use Cases:

Onboarding automation: script alias setup as part of repo initialisation
CI pipelines: keep alias mappings in a separate file and apply them on deploy
Bulk imports: migrate alias lists from another tool's export format
Safe updates: use --dry-run to audit changes before committing them

Notes:

--from-file and --canonical are mutually exclusive; combining them is an error
The operation is idempotent: running the same command twice produces the same config
Always verify with --dry-run before running in unattended automation
See Managing Aliases Guide for detailed identity management guidance

📊 Output Formats

CSV Format (`--format csv`)

Generates structured data files:

weekly_metrics_YYYYMMDD.csv - Weekly development metrics
developers_YYYYMMDD.csv - Developer profiles and statistics
summary_YYYYMMDD.csv - Project-wide summary statistics
untracked_commits_YYYYMMDD.csv - Commits without ticket references

JSON Format (`--format json`)

Generates comprehensive data export:

comprehensive_export_YYYYMMDD.json - Complete analysis data

Markdown Format (`--format markdown`)

Generates human-readable reports:

narrative_report_YYYYMMDD.md - Executive summary with insights

All Formats (`--format all`)

Generates all available output formats.

🚨 Exit Codes

GitFlow Analytics uses standard exit codes:

0: Success - Analysis completed successfully
1: General error - Configuration or processing error
2: Configuration error - Invalid YAML or missing required fields
3: Authentication error - Invalid or missing GitHub token
4: Repository error - Repository access or cloning failed
5: Analysis error - Analysis processing failed
6: Output error - Report generation failed

🔍 Environment Variables

GitFlow Analytics recognizes these environment variables:

Authentication

GITHUB_TOKEN - GitHub personal access token
JIRA_ACCESS_USER - JIRA username for API access
JIRA_ACCESS_TOKEN - JIRA API token or password

Configuration

GITFLOW_CONFIG - Default configuration file path
GITFLOW_CACHE_DIR - Override default cache directory
GITFLOW_LOG_LEVEL - Set logging level (DEBUG, INFO, WARNING, ERROR)

Performance

GITFLOW_MAX_WORKERS - Maximum parallel processing workers
GITFLOW_BATCH_SIZE - Commit processing batch size
GITFLOW_TIMEOUT - Network request timeout in seconds

💡 Usage Patterns

Daily Team Health Check

# Quick 1-week analysis for daily standup insights
gitflow-analytics -c config.yaml --weeks 1 --format markdown --quiet

Weekly Sprint Review

# 2-week analysis with comprehensive data
gitflow-analytics -c config.yaml --weeks 2 --format all

Monthly Planning Analysis

# 4-week analysis with cache clearing for fresh data
gitflow-analytics -c config.yaml --weeks 4 --clear-cache --format all

Quarterly Strategic Review

# 12-week comprehensive analysis
gitflow-analytics -c config.yaml --weeks 12 --format all --verbose

CI/CD Integration

# Automated analysis with JSON export for dashboard integration
gitflow-analytics -c config.yaml --weeks 4 --format json --quiet

🔧 Advanced Usage

Configuration Override

# Override output directory
gitflow-analytics -c config.yaml --output-dir /custom/reports/

# Analyze subset of repositories
gitflow-analytics -c config.yaml --repositories "critical-repo,main-app"

Performance Optimization

# Use cached analysis for faster reporting
gitflow-analytics -c config.yaml --weeks 8

# Clear cache for fresh analysis (slower but current)
gitflow-analytics -c config.yaml --weeks 8 --clear-cache

Debugging and Troubleshooting

# Verbose output for debugging
gitflow-analytics -c config.yaml --verbose

# Validate configuration before running
gitflow-analytics validate -c config.yaml --check-tokens --check-repos

# Test configuration without full analysis
gitflow-analytics -c config.yaml --validate-only

🆘 Common Issues

"Command not found"

# Ensure GitFlow Analytics is installed and in PATH
pip show gitflow-analytics
which gitflow-analytics

# Install if missing
pip install gitflow-analytics

"Configuration file not found"

# Provide absolute path to configuration
gitflow-analytics -c /full/path/to/config.yaml

# Check current directory for config file
ls -la *.yaml

"GitHub API rate limit exceeded"

# Check token is set correctly
echo $GITHUB_TOKEN

# Validate token has necessary permissions
gitflow-analytics validate -c config.yaml --check-tokens

"Repository not found or access denied"

# Verify repository names and permissions
gitflow-analytics validate -c config.yaml --check-repos

# Check GitHub token has access to repositories

📚 Related Documentation

Configuration Guide - Complete YAML configuration reference
Getting Started - Installation and first steps
Troubleshooting - Common issues and solutions
Examples - Real-world usage scenarios

🔄 Command History and Aliases

Useful Shell Aliases

# Add to your .bashrc or .zshrc
alias gfa='gitflow-analytics'
alias gfa-weekly='gitflow-analytics -c config.yaml --weeks 1'
alias gfa-monthly='gitflow-analytics -c config.yaml --weeks 4 --clear-cache'
alias gfa-validate='gitflow-analytics validate -c config.yaml --check-all'

Bash Completion

GitFlow Analytics supports bash completion for commands and options:

# Enable bash completion (if supported)
eval "$(_GITFLOW_ANALYTICS_COMPLETE=bash_source gitflow-analytics)"

FilesExpand file tree

cli-commands.md

Latest commit

History

cli-commands.md

File metadata and controls

CLI Commands Reference

🚀 Basic Usage

Default Command (Analyze)

📋 Global Options

Required Options

Analysis Options

Output Options

Utility Options

🔧 Subcommands

analyze (default)

identities

validate

cache

alias-rename

add-alias

📊 Output Formats

CSV Format (--format csv)

JSON Format (--format json)

Markdown Format (--format markdown)

All Formats (--format all)

🚨 Exit Codes

🔍 Environment Variables

Authentication

Configuration

Performance

💡 Usage Patterns

Daily Team Health Check

Weekly Sprint Review

Monthly Planning Analysis

Quarterly Strategic Review

CI/CD Integration

🔧 Advanced Usage

Configuration Override

Performance Optimization

Debugging and Troubleshooting

🆘 Common Issues

"Command not found"

"Configuration file not found"

"GitHub API rate limit exceeded"

"Repository not found or access denied"

📚 Related Documentation

🔄 Command History and Aliases

Useful Shell Aliases

Bash Completion

CSV Format (`--format csv`)

JSON Format (`--format json`)

Markdown Format (`--format markdown`)

All Formats (`--format all`)