goal

Command Reference

Complete reference for all Goal commands and options.

Global Options

These options can be used with any Goal command:

Option	Short	Description
--config PATH	-c PATH	Path to goal.yaml config file
--markdown		Use markdown output format (default)
--ascii		Use ASCII output format
--help	-h	Show help message
--version		Show version and exit

Main Commands

goal (default)

Run the interactive push workflow.

goal [OPTIONS]

Options:

• --bump, -b {patch,minor,major}: Version bump type (default: patch)
• --yes, -y: Skip all prompts (run automatically)
• --all, -a: Automate all stages including tests, commit, push, and publish
• --dry-run: Show what would be done without doing it

Examples:

goal                          # Interactive workflow
goal --bump minor            # Interactive with minor bump
goal --yes                   # Automatic workflow
goal --all                   # Full automation
goal --dry-run               # Preview changes

goal push

Add, commit, tag, and push changes to remote.

goal push [OPTIONS]

Options:

• --bump, -b {patch,minor,major}: Version bump type (default: patch)
• --no-tag: Skip creating git tag
• --no-changelog: Skip updating changelog
• --no-version-sync: Skip syncing version to project files
• --message, -m TEXT: Custom commit message
• --dry-run: Show what would be done without doing it
• --yes, -y: Skip all prompts
• --split: Create separate commits per change type
• --ticket TEXT: Ticket prefix for commit titles

Examples:

goal push                                    # Interactive
goal push --yes                              # Automatic
goal push --bump minor                       # Minor version bump
goal push -m "Custom message"                # Custom message
goal push --split                            # Split by type
goal push --no-tag                           # No git tag
goal push --dry-run                          # Preview

goal init

Initialize Goal in current repository.

goal init [OPTIONS]

Options:

• --force, -f: Overwrite existing goal.yaml

Creates:

• VERSION file with initial version
• CHANGELOG.md with template
• goal.yaml with auto-detected settings

Examples:

goal init                # Initialize if not exists
goal init --force        # Regenerate config

goal config

View or manage user configuration stored in ~/.goal.

goal config [OPTIONS]

Options:

• --reset: Reset configuration and run setup again
• --show: Show current configuration (default)

Configuration includes:

• Author name and email (from git config)
• Default license preference
• License classifier for package managers

Examples:

goal config                  # Show current configuration
goal config --reset          # Reset and reconfigure

What it shows:

======================================================================
  📋 Goal User Configuration
======================================================================

Config file: /home/tom/.goal

Current settings:
  Author name:  Tom Sapletta
  Author email: info@softreck.com
  License:      Apache License 2.0 (Apache-2.0)

💡 Tip: Run 'goal config --reset' to reconfigure

goal status

Show current git status and version info.

goal status [OPTIONS]

Options:

• --markdown/--ascii: Output format (default: markdown)

Shows:

• Current version
• Current branch
• Staged files
• Unstaged/untracked files

goal version

Show or bump version.

goal version [OPTIONS]

Options:

• --type, -t {patch,minor,major}: Version bump type (default: patch)

Examples:

goal version              # Show current and next versions
goal version --bump minor # Show next minor version

goal check-versions

Validate version consistency across project files, README badges, and published registry versions.

goal check-versions [OPTIONS]

Options:

• --update-badges: Update README badges if they don’t match current version

Behavior:

• Compares local version with registry versions (PyPI, npm, crates.io, RubyGems)
• Validates README badge versions match current version
• Checks version consistency across project files (package.json, pyproject.toml, etc.)
• Warns about mismatches before publishing

Examples:

goal check-versions                    # Check all versions
goal check-versions --update-badges  # Check and update badges

Output:

🔍 Version Check for v2.1.33
Detected project types: python

📦 Registry Versions:
  ✅ python: Version 2.1.33 is up to date

🏷️  README Badges:
  ✅ Badges are up to date

📁 Local Version Files:
  ✅ pyproject.toml: 2.1.33
  ✅ All version files are consistent

📋 Summary:
  ✅ All versions are consistent and ready for publishing!

goal publish

Publish the current version to package registries.

goal publish [OPTIONS]

Options:

• --yes, -y: Skip confirmation prompts
• --dry-run: Show what would be published without doing it

Behavior:

• Detects project type and builds packages if needed
• Uploads only the current version artifacts (not everything in dist/)
• Shows clear error messages for common issues (File already exists, Authentication)

Examples:

goal publish                    # Interactive
goal publish --yes              # Automatic

Note: If a Makefile with a publish target exists, goal publish will use make publish instead.

goal commit

Generate a smart commit message for current changes.

goal commit [OPTIONS]

Options:

• --detailed, -d: Generate detailed commit message with body
• --unstaged, -u: Analyze unstaged changes instead of staged
• --markdown/--ascii: Output format (default: markdown)
• --ticket TEXT: Ticket prefix for commit title

Examples:

goal commit               # Simple message
goal commit --detailed    # Detailed message with body
goal commit --unstaged    # Analyze unstaged changes

Configuration Commands

goal config

Manage goal.yaml configuration.

goal config show

Show current configuration.

goal config show [OPTIONS]

Options:

• --key, -k KEY: Show specific config key (dot notation)

Examples:

goal config show                    # Show full config
goal config show -k project        # Show project section
goal config show -k git.commit.strategy  # Show specific key

goal config get

Get a configuration value.

goal config get KEY

Arguments:

• KEY: Configuration key (dot notation)

Examples:

goal config get project.name
goal config get versioning.files

goal config set

Set a configuration value.

goal config set KEY VALUE

Arguments:

• KEY: Configuration key (dot notation)
• VALUE: Value to set (JSON parsed for complex types)

Examples:

goal config set git.commit.scope "my-app"
goal config set versioning.bump_rules.minor 100
goal config set versioning.files '["VERSION", "pyproject.toml:version"]'

goal config validate

Validate goal.yaml configuration.

goal config validate

Returns:

• Success if configuration is valid
• List of errors if invalid

goal config update

Update goal.yaml based on project detection.

goal config update

Updates:

• Detected project types
• Version files
• Other auto-detected settings

Exit Codes

Code	Meaning
0	Success
1	General error
2	Invalid arguments
3	Git repository not found
4	Configuration error
5	Tests failed (when using –yes)

Environment Variables

Variable	Description
PYPI_TOKEN	PyPI authentication token
NPM_TOKEN	npm authentication token
CARGO_REGISTRY_TOKEN	Cargo registry token
GITHUB_TOKEN	GitHub token for releases

Configuration File Location

Goal looks for goal.yaml in this order:

1. Path specified with --config
2. Current directory
3. Parent directories (up to git root)

Examples by Use Case

Development Workflow

# Make changes...
goal                    # Interactive commit and push

CI/CD Pipeline

goal --all --bump patch    # Full automation

Quick Fix

goal push -m "fix: critical bug" --yes

Feature Branch

goal push --no-tag --no-changelog    # No release on feature branch

Split Changes

goal push --split                     # Separate commits by type

Custom Config

goal -c staging.yaml --all           # Use staging config

See Also

• Configuration Guide - Detailed configuration options
• Examples - Practical examples
• Troubleshooting - Common issues

This site is open source. Improve this page.