goal

Goal

Goal is your release autopilot: a CLI that runs tests, writes conventional commits, updates changelogs, bumps versions, and publishes packages for you—while keeping you in control with clear prompts or full automation.

Why you might need Goal

Solo dev finishing a feature → run one command, get a polished commit, synced versions, and a tagged release without memorizing git plumbing.
Team ready for a patch fix → ensure the changelog, VERSION file, and package registry stay in lockstep, even when multiple people touch the repo.
CI/CD pipeline → same command powers nightly builds, preview releases, or fully automated publishing.

What you get out of the box

🔍 Context-aware diagnostics – detects repo state, project types, missing remotes, config drift.
🧠 Commit intelligence – auto-scoped conventional messages that explain what changed, what was tested, and the scale of work.
🏷️ Release hygiene – synchronized VERSION files, changelog updates, git tags, and optional registry publish.
⚙️ Multi-language support – Python, Node.js, Rust, Go, Java, .NET, PHP, Ruby, and hybrid repos.
🤖 Prompted or headless – run interactively (goal) or fire-and-forget in CI with goal --all.

Three real-life flows

# 1. First-time setup in a folder without git
goal           # Goal offers to init git, add a remote, then re-run the workflow.

# 2. Everyday feature release
goal push      # Runs tests, suggests a commit, bumps patch, updates changelog, pushes, tags.

# 3. CI/CD or cron-driven release
goal --all --bump minor   # Non-interactive; perfect for nightly builds or release pipelines.

🆕 What’s New in v2.1.65

TODO Management & Publishing Fixes — Automatic issue tracking and reliable PyPI publishing

✨ New Features

🎫 Automatic TODO Management

goal doctor --todo adds detected issues to TODO.md
Unique ticket IDs prevent duplicates
Rich formatting with severity icons
Timestamped sections for tracking

🔧 Publishing Improvements

Fixed “cannot access local variable ‘Path’” error
Better handling of ~/.pypirc authentication
Improved error messages and debugging
Support for both token and config-based auth

🛠️ Enhanced Diagnostics

Better error detection in project configuration
More reliable build process
Improved artifact management

📋 Example Usage

# Check version
goal -v

# Diagnose and track issues
goal doctor --todo
goal doctor -t

# Full workflow with TODO tracking
goal --all --todo
goal -a -t

# Standard workflow
goal --all

# Check project health
goal doctor

## 📚 Previous Features (v2.1)

> **Smart Commit Intelligence** — commit bodies that answer *what changed, what was tested, and at what scale*

❌ BEFORE: refactor(core): add testing, logging, validation
✅ AFTER:  feat(goal): intelligent code analysis pipeline

changes:
  - file: cli.py
    area: cli
    added: [ensure_git_repository, ensure_remote, _run_git_verbose]
    modified: [push]
  - file: test_clone_repo.py
    area: test
    new_tests: 3

testing:
  new_tests: 3
  scenarios:
    - auto_mode_skips
    - init_and_add_remote
    - clone_option_with_valid_url

stats:
  lines: "+210/-45 (net +165)"
  files: 2
  complexity: "Stable complexity"

Interactive Git Setup — goal now guides you through repository configuration when no git repo is found

⚠  Not a git repository.

What would you like to do?
  [1] Initialize git here and connect to a remote  (keeps local files in 'myproject/')
  [2] Clone a remote repository into this directory  (downloads remote files)
  [3] Initialize a local-only git repository        (no remote)
  [4] Exit

📖 Full Documentation

📂 Examples

Features

🚀 Interactive workflow - Confirms each stage (test, commit, push, publish) with Y/n prompts
🧠 Smart commit messages - Generates conventional commits based on diff analysis
🎯 Enhanced Summary - Business-value focused messages with capabilities, metrics, relations
👤 User configuration - Auto-detects git user info and license preferences (stored in ~/.goal)
📄 Smart metadata management - Automatically updates author and license in project files
📝 README automation - Updates license badges and author sections automatically
🔍 Version validation - Checks registry versions and README badge consistency
📦 Multi-language support - Python, Node.js, Rust, Go, Ruby, PHP, .NET, Java
🏷️ Version management - Automatic version bumping and synchronization across project files
📝 Changelog updates - Maintains CHANGELOG.md with version history
🐳 CI/CD ready - --yes flag for automated workflows
🧪 Test integration - Runs project-specific test commands before committing
📦 Publish support - Publishes to package managers (PyPI, npm, crates.io, etc.)

Installation

pip install goal

Quick Start

1. Install Goal

pip install goal

2. Run `goal` in any project directory

cd my-project/
goal

Goal detects your situation and guides you interactively:

Scenario A: No git repository yet

⚠  Not a git repository.

What would you like to do?
  [1] Initialize git here and connect to a remote  (keeps local files in 'my-project/')
  [2] Clone a remote repository into this directory  (downloads remote files)
  [3] Initialize a local-only git repository        (no remote)
  [4] Exit
Choose [1]: 1

  → git init
✓ Initialized git repository.

Enter repository URL:
  SSH   example: git@github.com:user/repo.git
  HTTP  example: https://github.com/user/repo.git
URL: git@github.com:wronai/my-project.git

  → git remote add origin git@github.com:wronai/my-project.git
✓ Remote 'origin' → git@github.com:wronai/my-project.git

Fetching remote branches...
  → git fetch origin
  Remote is empty (no branches yet). Your local files will be the first push.

✓ Ready. Run 'goal' again to commit and push.

Scenario B: Git repo exists, no remote configured

⚠  No git remote configured.

Would you like to add a remote?
  [1] Add remote origin (connect to GitHub/GitLab/etc.)
  [2] Skip — commit locally without pushing
Choose [1]: 1

  → git remote add origin git@github.com:wronai/my-project.git
  Verifying connection...
  ✓ Remote is reachable.
✓ Remote 'origin' → git@github.com:wronai/my-project.git

Scenario C: Everything configured — the normal workflow

Detected project types: python
Will commit 5 files (+120/-15 lines, NET 105, 11% churn deletions)
Commit message: feat(api): add user authentication endpoint

Run tests? [Y/n]
Commit changes? [Y/n]
Push to remote? [Y/n]
Publish version 1.2.3? [Y/n]

Every git command is shown transparently (lines starting with →) so you always know what goal is doing.

3. Automation modes

# Full automation — tests, commit, push, publish (skips if no repo/remote)
goal -a

# Skip prompts but don't auto-publish
goal --yes

# Preview what would happen
goal --dry-run

Note: goal -a in a directory without a git repository will skip gracefully instead of failing. This is safe for CI/CD pipelines.

Running from a local clone

If you’re working with the goal source code:

git clone https://github.com/wronai/goal.git
cd goal

# Use the local version without installing
python3 -m goal

# Or install in development mode
pip install -e .

Documentation

📚 Complete Documentation: docs/README.md

Key Topics

Installation Guide - Detailed installation instructions
Quick Start - Get started in 5 minutes
Configuration Guide - Complete goal.yaml reference
Examples - Real-world examples and use cases
CI/CD Integration - Use Goal in pipelines
Command Reference - All commands and options

Usage Examples

Basic interactive workflow

# Run full interactive workflow with default patch bump
goal

# Run with minor version bump
goal --bump minor

# Run without prompts (for CI/CD)
goal --yes

# Automate ALL stages without any prompts
goal --all

Real-world examples

1. Python project with pytest

# Make changes to your Python code
git add .

# Run the full workflow
goal

# Output:
# ✓ Detected project types: python
# ✓ Running tests: pytest tests/ -v
# ✓ Tests passed (23/23)
# ✓ Generated commit: feat(api): add user authentication endpoint
# ✓ Updated VERSION to 1.2.3
# ✓ Updated CHANGELOG.md
# ✓ Created tag v1.2.3
# ✓ Pushed to origin
# ? Publish to PyPI? [Y/n]: Y
# ✓ Published version 1.2.3

2. Node.js project with npm

# Quick patch release for bug fix
goal push --yes -m "fix: resolve memory leak in parser"

# Output:
# ✓ Detected project types: nodejs
# ✓ Running tests: npm test
# ✓ Tests passed
# ✓ Committed: fix: resolve memory leak in parser
# ✓ Updated package.json to 1.0.1
# ✓ Updated CHANGELOG.md
# ✓ Created tag v1.0.1
# ✓ Pushed to origin

3. Rust project with cargo

# Major release with breaking changes
goal push --bump major --yes

# Output:
# ✓ Detected project types: rust
# ✓ Running tests: cargo test
# ✓ All tests passed
# ✓ Generated commit: feat!: change public API structure
# ✓ Updated Cargo.toml to 2.0.0
# ✓ Updated CHANGELOG.md
# ✓ Created tag v2.0.0
# ✓ Pushed to origin
# ? Publish to crates.io? [Y/n]: Y
# ✓ Published crate v2.0.0

4. Publishing packages

# Publish only (after committing)
goal publish

# Or include publishing in the full workflow
goal --all  # Will publish automatically

Important: Goal automatically filters artifacts to upload only the current version, avoiding “File already exists” errors on PyPI.

If you see a “File already exists” error:

Clean and rebuild: rm -rf dist build && python -m build
Or bump version again: goal --bump patch
Check you’re using the latest goal: python3 -m goal (in goal repo)

4. Multi-language project

# Project with both Python backend and Node.js frontend
goal info

# Output:
# === Project Information ===
# Project types: python, nodejs
# Current version: 1.5.0
# 
# Version files:
#   ✓ VERSION: 1.5.0
#   ✓ package.json: 1.5.0
#   ✓ pyproject.toml: 1.5.0

# Run release - updates both package.json and pyproject.toml
goal push --yes

5. Documentation updates

# Skip tests for docs-only changes
goal push --no-test -m "docs: update API documentation"

# Or let goal detect it's docs only
git add README.md docs/
goal push --yes

# Output:
# ✓ Detected project types: python
# ✓ Generated commit: docs: update API documentation
# ✓ Updated VERSION to 1.5.1
# ✓ Updated CHANGELOG.md
# ✓ Created tag v1.5.1
# ✓ Pushed to origin

6. CI/CD automation

# .github/workflows/release.yml
name: Release
on:
  push:
    branches: [main]
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - name: Install Goal
        run: pip install goal
      - name: Configure PyPI token
        run: echo "__token__=$" > ~/.pypirc
      - name: Release
        run: goal --all --bump patch

7. Dry run for preview

# Preview what will happen
goal push --dry-run --bump minor

# Output:
# === DRY RUN ===
# Project types: python
# Files to commit: 12 (+342/-15 lines)
#   - src/auth.py (+120/-5)
#   - tests/test_auth.py (+85/-0)
#   - docs/api.md (+137/-10)
# Commit message: feat(auth): add OAuth2 integration
# Version: 1.5.0 -> 1.6.0
# Version sync: VERSION, pyproject.toml
# Tag: v1.6.0

8. Custom commit message

# Override auto-generated message
goal push -m "feat: implement real-time notifications"

# Or use conventional commit format
goal push -m "fix(auth): resolve JWT token expiration issue"

9. Split commits for large changes

# Split changes into logical commits
goal push --split --yes

# Output:
# ✓ Committed docs: update README and API docs
# ✓ Committed feat: add user authentication system
# ✓ Committed test: add comprehensive test coverage
# ✓ Committed chore: update dependencies and CI config
# ✓ Committed release: v2.0.0

10. Skip specific steps

# Skip version bump for hotfix
goal push --yes --no-version-sync -m "hotfix: critical security patch"

# Skip changelog for minor tweak
goal push --yes --no-changelog -m "style: fix linting issues"

# Skip tag creation for experimental feature
goal push --yes --no-tag -m "feat: experimental AI integration"

Using the push command directly

# Interactive push with prompts
goal push

# Automatic push without prompts
goal push --yes

# Dry run to see what would happen
goal push --dry-run

# Custom commit message
goal push -m "feat: add new authentication system"

# Skip specific steps
goal push --no-tag --no-changelog

# With version bump
goal push --bump minor

# Markdown output for CI/CD logs
goal push --markdown

Version management

# Check current version
goal version

# Bump specific version type
goal version --bump minor
goal version --bump major

# Check repository status
goal status

Supported Project Types

Goal automatically detects your project type and uses appropriate commands:

Language	Test Command	Publish Command	Version Files
Python	`pytest`	`python -m build && twine upload dist/*`	pyproject.toml, setup.py
Node.js	`npm test`	`npm publish`	package.json
Rust	`cargo test`	`cargo publish`	Cargo.toml
Go	`go test ./...`	`git push origin --tags`	go.mod (uses git tags)
Ruby	`bundle exec rspec`	`gem build .gemspec && gem push .gem`	*.gemspec
PHP	`composer test`	`composer publish`	composer.json
.NET	`dotnet test`	`dotnet pack && dotnet nuget push *.nupkg`	*.csproj
Java	`mvn test`	`mvn deploy`	pom.xml, build.gradle

Markdown Output

Goal outputs structured markdown by default (perfect for LLM consumption and CI/CD logs). Use --ascii to get the legacy console output.

# Default: markdown output
goal push
goal status

# Force legacy output
goal push --ascii
goal status --ascii

# Use with automation
goal --all > release.log

The markdown output includes:

Front matter with metadata (command, version, file count)
Structured sections for overview, files, and test results
Code blocks for command outputs
Summary with actions taken and next steps

Example output:

---
command: goal push
project_types: ["python"]
version_bump: "1.0.1 -> 1.0.2"
file_count: 7
---

# Goal Push Result

## Overview
**Project Type:** python
**Files Changed:** 7 (+1140/-99 lines)
**Version:** 1.0.1 → 1.0.2
...

See docs/markdown-output.md for detailed examples.

Command Reference

`goal` or `goal push`

Main command for the complete workflow.

Options:

-v, --version: Show version and exit
--bump, -b: Version bump type [patch minor major] (default: patch)
--yes, -y: Skip all prompts (run automatically)
--all, -a: Automate all stages including tests, commit, push, and publish
--todo/--no-todo, -t: Add unfixed issues to TODO.md during doctor phase (default: no)
--markdown/--ascii: Output format (default: markdown)
--split: Create separate commits per change type (docs/code/ci/examples)
--ticket: Ticket prefix to include in commit titles (overrides TICKERT)
--no-tag: Skip creating git tag
--no-changelog: Skip updating changelog
--no-version-sync: Skip syncing version to project files
--message, -m: Custom commit message
--dry-run: Show what would be done without doing it

`goal doctor`

Diagnose and auto-fix common project configuration issues.

Options:

--fix/--no-fix: Auto-fix issues (default: yes)
--path, -p: Root directory to scan (default: .)
--todo/--no-todo, -t: Add unfixed issues to TODO.md (default: no)

Examples:

goal doctor              # Diagnose and auto-fix
goal doctor --no-fix     # Diagnose only
goal doctor --todo       # Add issues to TODO.md
goal doctor -t           # Add issues to TODO.md (short form)

Split commits (per type)

When --split is enabled, Goal will create multiple commits:

code: changes in goal/, src/, lib/, *.py
docs: docs/*, README.md, *.md
ci: .github/*, .gitlab/*, *.yml/*.yaml
examples: examples/*
other: everything else

Then it will create a final release metadata commit with version bump + changelog (unless disabled).

Ticket prefixing (TICKET)

Create a TICKET file in repository root:

prefix=ABC-123
format=[{ticket}] {title}

You can override it per run:

goal push --ticket ABC-123
goal push --split --ticket ABC-123
goal commit --ticket ABC-123

`goal init`

Initialize goal in current repository.

Creates:

VERSION file with initial version 1.0.0
CHANGELOG.md with standard template

`goal status`

Show current git status and version info.

Displays:

Current version
Current branch
Staged files
Unstaged/untracked files

`goal version`

Show or bump version.

Options:

--type, -t: Version bump type [patch minor major] (default: patch)

Examples by Use Case

Development Workflow

# Make your changes...
git add some/files

# Run goal with interactive prompts
goal

# Prompts will appear:
# Run tests? [Y/n] - Runs pytest for Python projects
# Commit changes? [Y/n] - Creates smart commit message
# Push to remote? [Y/n] - Pushes to origin with tags
# Publish version 1.2.3? [Y/n] - Publishes to PyPI/npm/etc

Full Automation

# Automate everything - tests, commit, push, publish
goal --all

# Short form
goal -a

# With specific version bump
goal --all --bump minor

CI/CD Pipeline

# GitHub Actions example
- name: Deploy with Goal
  run: |
    goal push --yes --bump minor
    
# Or with --all flag
- name: Full release
  run: |
    goal --all --bump patch

Skip Testing in Quick Fixes

# Skip tests for documentation changes
goal push --yes -m "docs: update README"

Pre-release Workflow

# Check what will be done
goal push --dry-run --bump minor

# Run with specific version bump
goal push --bump minor

# Or skip publishing for internal releases
goal push --yes --no-tag

Working with Multiple Projects

# Monorepo with frontend and backend
# Structure:
# /backend (Python)
# /frontend (Node.js)
# /docs

# From root directory
goal info

# Output:
# Project types: python, nodejs
# Version files:
#   ✓ VERSION: 2.1.0
#   ✓ backend/pyproject.toml: 2.1.0
#   ✓ frontend/package.json: 2.1.0

# Release updates all projects
goal push --yes

Hotfix Workflow

# Critical fix - skip tests and version bump
goal push --yes --no-test --no-version-sync -m "hotfix: security patch"

# Then create proper release
goal push --bump patch -m "release: v1.2.1 with security fix"

Feature Branch Workflow

# On feature branch
goal push --yes --no-tag --no-publish

# After merge to main
goal push --bump minor --yes

Release Candidate

# Create RC version
goal push --bump patch -m "release: v2.0.0-rc1"

# After testing, promote to stable
goal push --bump patch -m "release: v2.0.0 stable"

Configuration

Goal uses goal.yaml for configuration. Run goal init to create it automatically with detected settings.

goal.yaml Structure

# goal.yaml - Goal configuration file
version: "1.0"

project:
  name: "my-project"           # Auto-detected from pyproject.toml/package.json
  type: ["python"]             # Auto-detected project types
  description: "My project"    # Auto-detected description

versioning:
  strategy: "semver"           # semver, calver, or date
  files:                       # Files to sync version to
    - "VERSION"
    - "pyproject.toml:version"
    - "package.json:version"
  bump_rules:                  # Auto-bump thresholds
    patch: 10                  # Files changed
    minor: 50                  # Lines added
    major: 200                 # Large changes

git:
  commit:
    strategy: "conventional"   # conventional, semantic, custom
    scope: "my-project"        # Default scope for commits
    templates:                 # Custom commit templates
      feat: "feat({scope}): {description}"
      fix: "fix({scope}): {description}"
      docs: "docs({scope}): {description}"
    classify_by:               # Classification methods
      - "file_extensions"
      - "directory_paths"
      - "line_stats"
      - "keywords_diff"
  changelog:
    enabled: true
    template: "keep-a-changelog"
    output: "CHANGELOG.md"
    sections: ["Added", "Changed", "Fixed", "Deprecated"]
  tag:
    enabled: true
    prefix: "v"
    format: "{prefix}{version}"

strategies:
  python:
    test: "pytest tests/ -v"
    build: "python -m build"
    publish: "twine upload dist/*"
  nodejs:
    test: "npm test"
    build: "npm run build"
    publish: "npm publish"

registries:
  pypi:
    url: "https://pypi.org/simple/"
    token_env: "PYPI_TOKEN"
  npm:
    url: "https://registry.npmjs.org/"
    token_env: "NPM_TOKEN"

hooks:
  pre_commit: ""               # Command to run before commit
  post_commit: ""              # Command to run after commit
  pre_push: ""                 # Command to run before push
  post_push: ""                # Command to run after push

advanced:
  auto_update_config: true     # Auto-update config on detection changes
  performance:
    max_files: 50              # Split commits if > N files
    timeout_test: 300          # Test timeout in seconds

Config Commands

# Show full configuration
goal config show

# Show specific key (dot notation)
goal config show -k git.commit.strategy

# Get a value
goal config get project.name

# Set a value
goal config set git.commit.scope "my-app"

# Validate configuration
goal config validate

# Update config based on project detection
goal config update

Custom Config File

# Use a custom config file
goal --config custom-goal.yaml push

# Or in CI/CD
goal -c .goal/ci.yaml --all

Conventions (without goal.yaml)

Goal also works without configuration based on conventions:

Version detection: Looks for VERSION file first, then project-specific files
Project detection: Automatically detects project type from files
Commit messages: Uses conventional commit format based on diff analysis
Changelog: Updates CHANGELOG.md in Keep a Changelog format

Integration Examples

Makefile

.PHONY: release patch minor major

# Interactive release
release:
	goal

# Automatic patch release
patch:
	goal push --yes

# Full automation release
all:
	goal --all

# Automatic minor release
minor:
	goal push --yes --bump minor

# Automatic major release
major:
	goal push --yes --bump major

# Dry run
dry-run:
	goal push --dry-run

# Release with custom message
release-message:
	goal push --yes -m "$(MSG)"

# Release from specific branch
release-branch:
	git checkout main
	git pull
	goal --all --bump $(BUMP)

package.json scripts

{
  "scripts": {
    "release": "goal",
    "release:patch": "goal push --yes",
    "release:all": "goal --all",
    "release:minor": "goal push --yes --bump minor",
    "release:major": "goal push --yes --bump major",
    "release:dry": "goal push --dry-run",
    "release:docs": "goal push --yes -m 'docs: update documentation'"
  }
}

pre-commit hook

#!/bin/sh
# .git/hooks/pre-commit
echo "Running goal pre-commit check..."
goal push --dry-run
if [ $? -eq 0 ]; then
    echo "✅ Ready to commit!"
else
    echo "❌ Issues found. Fix them before committing."
    exit 1
fi

Docker integration

# Dockerfile
FROM python:3.11-slim

WORKDIR /app

# Install dependencies
COPY requirements.txt .
RUN pip install -r requirements.txt

# Install goal
RUN pip install goal

# Copy source code
COPY . .

# Run tests and release
CMD ["sh", "-c", "goal --all"]

Smart Commit Messages

Goal analyzes your changes to generate appropriate commit messages:

feat: New features, additions
fix: Bug fixes, patches
docs: Documentation changes
style: Formatting, linting
refactor: Code restructuring
perf: Performance improvements
test: Test additions/changes
build: Build system, CI/CD
chore: Dependencies, maintenance

Examples:

feat: add user authentication
fix: resolve memory leak in parser
docs: update API documentation
test: add coverage for payment module

Troubleshooting

Tests fail but I want to continue

The interactive workflow will ask if you want to continue when tests fail:

Tests failed. Continue anyway? [y/N]

Custom test/publish commands

If Goal doesn’t detect your test command correctly, you can run them manually before using goal push --yes.

TODO Management

Goal can automatically add detected issues to TODO.md without duplicates:

# Diagnose and add unfixed issues to TODO.md
goal doctor --todo
goal doctor -t

# Diagnose without auto-fix but add to TODO.md
goal doctor --todo --no-fix
goal doctor -t --no-fix

# Full workflow with TODO tracking
goal --all --todo
goal -a -t

Features:

🎫 Unique ticket IDs - Format [CODE-identifier] for each issue
🚫 No duplicates - Checks existing tickets before adding
🎨 Rich formatting - Icons, severity levels, file references
📅 Timestamped sections - Groups issues by detection date

Example TODO.md entry:

## Issues Found - 2026-02-24

- [PY002-missingbuildsysteminpyprojecttoml] 🔴 **Missing [build-system] in pyproject.toml** (`pyproject.toml`)
  - pyproject.toml has no [build-system] section.
  - pip and build tools need this to know how to build your package.
  - Adding a default setuptools build-system.

Publishing fails

Ensure you’re authenticated with the appropriate package manager:

PyPI Authentication Options:

Recommended: Configure ~/.pypirc file (development)
CI/CD: Set PYPI_TOKEN environment variable
Interactive: Run twine configure

~/.pypirc setup (recommended for development):

[pypi]
  username = __token__
  password = pypi-AgEIcHlwaS5vcmcC...

Environment variable setup (for CI/CD):

export PYPI_TOKEN=your_token_here

Other package managers:

npm: npm login
crates.io: cargo login

Common Issues

Goal doesn’t detect my project type

# Check what's detected
goal info

# Manually specify in goal.yaml
project:
  type: ["python", "nodejs"]

Version sync not working

# Check version files
goal info

# Manually configure in goal.yaml
versioning:
  files:
    - "VERSION"
    - "my-app/__init__.py:__version__"

Tests timing out

# In goal.yaml
advanced:
  performance:
    timeout_test: 600  # 10 minutes

Commit message not accurate

# Use custom message
goal push -m "your custom message"

# Or configure templates in goal.yaml
git:
  commit:
    templates:
      feat: "feat({scope}): {description}"

User Configuration

Goal automatically manages your project metadata using your git configuration and license preferences.

First-time Setup

On first run, Goal will:

Auto-detect your git user.name and user.email
Ask for license preference (8 popular open source licenses)
Save to ~/.goal for future use

$ goal

======================================================================
  🎯 Goal - First Time Setup
======================================================================

✓ Detected git user.name: Tom Sapletta
✓ Detected git user.email: info@softreck.com

======================================================================
  📄 License Selection
======================================================================

  1. Apache License 2.0
  2. MIT License
  3. GNU General Public License v3.0
  4. BSD 3-Clause License
  5. GNU General Public License v2.0
  6. GNU Lesser General Public License v3.0
  7. GNU Affero General Public License v3.0
  8. Mozilla Public License 2.0

Enter your choice [1]: 1

✓ Configuration saved to ~/.goal

What Gets Updated Automatically

Every time you run goal, it updates:

Project Files:

pyproject.toml - authors, license, classifier
package.json - author, license, contributors
Cargo.toml - authors, license
VERSION - version number
__init__.py - __version__ variable (in all packages)

README.md:

License badges (Apache-2.0, MIT, GPL, etc.)
## License section
## Author section

Smart Author Management

Goal adds authors instead of replacing them:

# Before (existing author)
authors = [{name = "Original Author", email = "original@example.com"}]

# After (Goal adds you)
authors = [
    {name = "Original Author", email = "original@example.com"},
    {name = "Tom Sapletta", email = "info@softreck.com"},
]

Managing Your Configuration

# View current configuration
goal config

# Reset and reconfigure
goal config --reset

# Configuration file location
~/.goal

Example Output

$ goal config

======================================================================
  📋 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

Tips & Tricks

1. Use with aliases

# Add to ~/.bashrc or ~/.zshrc
alias g='goal'
alias gp='goal push --yes'
alias ga='goal --all'
alias gd='goal push --dry-run'

2. Team workflow

# For team development, use ticket prefixes
echo "prefix=PROJ-123" > TICKET
goal push --split  # Creates commits like "PROJ-123: feat: add feature"

3. Release checklist

# Before release
goal status      # Check status
goal push --dry-run  # Preview changes

# Release
goal --all       # Full automation

4. Working with feature flags

# Commit feature flag changes
goal push -m "feat: enable beta feature flag"

# Later, remove the flag
goal push -m "feat: launch feature to all users"

5. Automated releases on schedule

# .github/workflows/scheduled-release.yml
name: Scheduled Release
on:
  schedule:
    - cron: '0 9 * * 1'  # Every Monday at 9 AM
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Goal
        run: pip install goal
      - name: Weekly Release
        run: goal --all --bump patch

License

Apache License 2.0 - see LICENSE for details.

Author

Created by Tom Sapletta - tom@sapletta.com

_{Built with ❤️ by the community}

This site is open source. Improve this page.

goal

Goal

Why you might need Goal

What you get out of the box

Three real-life flows

🆕 What’s New in v2.1.65

✨ New Features

📋 Example Usage

Features

Installation

Quick Start

1. Install Goal

2. Run goal in any project directory

Scenario A: No git repository yet

Scenario B: Git repo exists, no remote configured

Scenario C: Everything configured — the normal workflow

3. Automation modes

Running from a local clone

Documentation

Key Topics

Usage Examples

Basic interactive workflow

Real-world examples

1. Python project with pytest

2. Node.js project with npm

3. Rust project with cargo

4. Publishing packages

4. Multi-language project

5. Documentation updates

6. CI/CD automation

7. Dry run for preview

8. Custom commit message

9. Split commits for large changes

10. Skip specific steps

Using the push command directly

Version management

Supported Project Types

Markdown Output

Command Reference

goal or goal push

goal doctor

Split commits (per type)

Ticket prefixing (TICKET)

goal init

goal status

goal version

Examples by Use Case

Development Workflow

Full Automation

CI/CD Pipeline

Skip Testing in Quick Fixes

Pre-release Workflow

Working with Multiple Projects

Hotfix Workflow

Feature Branch Workflow

Release Candidate

Configuration

goal.yaml Structure

Config Commands

Custom Config File

Conventions (without goal.yaml)

Integration Examples

Makefile

package.json scripts

pre-commit hook

Docker integration

Smart Commit Messages

Troubleshooting

Tests fail but I want to continue

Custom test/publish commands

TODO Management

Publishing fails

Common Issues

Goal doesn’t detect my project type

Version sync not working

Tests timing out

Commit message not accurate

User Configuration

First-time Setup

What Gets Updated Automatically

2. Run `goal` in any project directory

`goal` or `goal push`

`goal doctor`

`goal init`

`goal status`

`goal version`