Goal

AI Cost Tracking

🤖 LLM usage: $0.9104 (531 commits)
👤 Human dev: ~$17627 (176.3h @ $100/h, 30min dedup)

Generated on 2026-08-12 using openrouter/x-ai/grok-code-fast-1

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.

Adopt repository governance

Existing projects can install or check a pinned wellmanifest/new-project governance package without manually copying files:

goal governance adopt --source-revision <FULL_PUBLISHED_SHA> --check
goal governance adopt --source-revision <FULL_PUBLISHED_SHA>

The command fetches the exact 40-character commit SHA, verifies the checkout, and runs the standard's immutable adoption generator. --check reports drift without writing; reviewed managed-file upgrades require --upgrade. See docs/governance-adoption.md for the retrofit workflow and remaining project-local Docker/ticket steps.

🆕 What's New in v2.2.2

Monorepo sweep — run the full goal -a workflow across every git repository with uncommitted changes under a folder, in one command.

✨ New Features

🧹 goal all — sweep many repos at once

goal all [PATHS...] runs goal -a in every sub-repo that has uncommitted changes (defaults to * — all sub-folders of the current directory).
Clean repos and non-git folders are skipped automatically.
Lists the matched dirty projects and asks one batch confirmation (skipped with -y/--yes, or with --dry-run).
Continues past per-project failures and prints a succeeded/failed summary.

# From the parent folder holding all your repos:
goal all ./*# sweep every dirty sub-repo
goal -a ./*# identical shorthand (-a + paths ⇒ sweep)
goal auto all # `auto` is a word-form of the -a flag
goal all ./* --dry-run # preview without committing/pushing

Equivalences

Command	Same as	Action
`goal all ./*`	`goal -a ./*`	sweep dirty sub-repos under the given paths
`goal auto all`	`goal -a all`	sweep dirty sub-repos (defaults to `*`)
`goal auto ./*`	`goal -a ./*`	sweep
`goal auto`	`goal -a`	single-repo push in the current directory

🆕 What's New in v2.2.1

Intelligent Package Manager Broker — Automatic detection and selection of the fastest available package manager (uv, pdm, poetry, pip)

✨ New Features

📦 PackageManagerBroker

Automatic detection of available package managers (uv, pdm, poetry, pip)
Lockfile-aware installation (uv.lock → uv sync, poetry.lock → poetry install)
Priority-based selection (uv fastest, pip as fallback)
Auto-installation of uv when missing and pip is available
Smart dependency installation with timing and reporting

# Doctor shows available managers
goal doctor
📦 Available package managers:
✓ uv ⚡ fast poetry ⚡ fast 🔒
pip 🐢 slow
# Force specific manager
goal doctor --manager uv

⚡ Faster Python Installs

uv integration: 5-30s installs vs 2-10min with pip
Automatic uv installation: pip install uv when uv missing
Lockfile-first strategy: sync from lock when available
Detailed timing reports: "✅ uv (12.3s) | fallback: pip"

🔧 Architecture Improvements

Refactored Bootstrap System

Split project_bootstrap.py (1265L) → goal/bootstrap/ module
goal/installers/ - new package manager abstraction layer
goal/bootstrap/installer.py - unified installation interface
Full backward compatibility maintained

🆕 What's New in v2.2.0

Wizard Setup, License Management & Multi-Author Support — Complete project initialization, professional license handling, and team collaboration features

✨ New Features

🧙‍♂️ Interactive Setup Wizard

One-command project initialization with goal wizard
Guided git repository setup and remote configuration
Interactive user configuration (name, email, license)
Project configuration with versioning and commit strategies
Complete setup summary with next steps

# New project setup in one command
goal wizard

📄 Professional License Management

Create and update LICENSE files with 8 common license templates
Custom license template support for proprietary licenses
SPDX license ID validation with helpful error messages
License compatibility checking between different licenses
Automatic template variable substitution ({year}, {fullname})

# Create MIT license
goal license create MIT --fullname "Your Name"# Check license compatibility
goal license check MIT Apache-2.0

👥 Multi-Author Project Support

Team-based author management stored in project configuration
Import authors from git history automatically
Co-author support in commit messages with --co-author flag
Export team list to CONTRIBUTORS.md
Find authors by name, email, or alias

# Add team members
goal authors add "Jane Doe" jane@example.com --role "Developer"# Commit with co-authors
goal commit --co-author "Jane Doe <jane@example.com>"

🛠️ Enhanced Commands

All new commands integrate seamlessly with existing Goal workflows:

# Complete workflow with co-authors
goal push --co-author "Jane Doe <jane@example.com>"# Automated release with team attribution
goal --all --co-author "Team <team@example.com>"

🆕 What's New in v2.1.99

Security Validation & Proactive .gitignore Management — Automatic protection against large files, API tokens, and unwanted dot folders

✨ New Security Features

🔒 File Size Validation

Automatically blocks files larger than 10MB (configurable)
Prevents GitHub push failures due to file size limits
Clear error messages with file size information

🔑 API Token Detection

Scans for exposed API tokens before commit
Supports GitHub, AWS, Slack, Stripe, GitLab patterns
Detects private keys and sensitive credentials
Blocks commit with location details

📁 Proactive .gitignore Management

Automatically detects dot folders (.idea, .vscode, etc.)
Adds problematic folders to .gitignore before commit
Unstages files that should be ignored
Respects existing whitelist patterns (!.vscode)
Safe dot files are never ignored: .gitignore, .github/, .editorconfig, .gitattributes

🛡️ Security Validation in Action

# Before commit, Goal automatically checks:
goal push
# Also works with automation modes:
goal -a # Full automation with validation
goal -au # Full automation + update dependencies to latest
goal -aiu # Full automation, but ask per subproject before upgrading deps
goal -aur # Full automation + recursive dependency scan in subfolders
goal --all # All stages with validation
goal --yes # Auto-confirm with validation# Output examples:
✅ Added 2 dot folder(s)/file(s) to .gitignore: .idea, .DS_Store
→ Unstaged: .idea
→ Unstaged: .DS_Store
# Or blocks dangerous commits:
❌ Validation Error: File secrets.db is 15.2MB, which exceeds the limit of 10MB
❌ Validation Error: Potential GitHub Personal Access token detected in .env:5

⚙️ Configuration Options

# goal.yamladvanced:
file_validation:
max_file_size_mb: 10# File size limitblock_large_files: true # Block or just warndetect_api_tokens: true # Enable token detectionauto_manage_gitignore: true # Auto-update .gitignoreauto_add_dot_folders: true # Auto-add dot foldersknown_dot_folders: # Custom list of folders to ignore
- .idea
- .vscode
- .DS_Store
- .code2llm_cache
- .llm

🚀 Bypass Options

# Force commit (not recommended for security)
goal push --force
# Dry run to check what would be blocked
goal push --dry-run

🆕 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.)
🔒 Security validation - Blocks large files, detects API tokens, manages .gitignore automatically

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.

4. Monorepo sweep — run `goal -a` across many repos

When a folder contains many independent git repositories (a "monorepo of repos"), you can run the full goal -a workflow in every sub-repo that has uncommitted changes — clean repos and non-git folders are skipped.

# From the parent folder holding all your repos:
goal all ./*# sweep every dirty sub-repo (lists them, asks once)
goal -a ./*# identical shorthand: -a + paths ⇒ sweep
goal auto all # word-form of -a; defaults to * (all sub-folders)# Preview first (no commits/pushes/publishes), then run for real:
goal all ./* --dry-run
goal all ./* -y # skip the batch confirmation

How it behaves:

Prints the list of matched dirty projects and asks one confirmation before running (skipped with an explicit -y/--yes, or with --dry-run).
Runs goal -a in each project as an isolated subprocess.
Continues past per-project failures and prints a succeeded/failed summary at the end (exit code is non-zero if any project failed).

goal auto … is a word-form of the -a flag, so goal auto, goal auto ./* and goal auto all behave exactly like goal -a, goal -a ./* and goal -a all respectively.

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.ymlname: Releaseon:
push:
branches: [main]jobs:
release:
runs-on: ubuntu-lateststeps:
- uses: actions/checkout@v3
- uses: actions/setup-python@v4with:
python-version: '3.11'
- name: Install Goalrun: pip install goal
- name: Configure PyPI tokenrun: echo "__token__=${{ secrets.PYPI_TOKEN }}" > ~/.pypirc
- name: Releaserun: 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

11. Security Validation Examples

# Goal automatically protects against security issues
goal push
# Example 1: Large file detected# ❌ Validation Error: File database.dump is 15.2MB, which exceeds the limit of 10MB# For security reasons, the commit has been blocked.# To bypass this check, you can:# 1. Remove the sensitive/large file(s)# 2. Add the file(s) to .gitignore# 3. Use --force to bypass validation (not recommended)# Example 2: API token detected# ❌ Validation Error: Potential GitHub Personal Access token detected in .env:5# For security reasons, the commit has been blocked.# Example 3: Dot folder auto-management# ✅ Added 3 dot folder(s)/file(s) to .gitignore: .idea, .vscode, .DS_Store# → Unstaged: .idea# → Unstaged: .vscode# → Unstaged: .DS_Store

12. 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 pushproject_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
--upgrade-deps, -u: Update project dependencies to latest available versions
--recursive, -r: Scan subfolders for dependency manifests (monorepo support)
--interactive, -i: Ask before processing each subproject during dependency updates
--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)

`goal wizard`

Interactive guided setup for new projects.

Walks you through:

Git repository initialization and remote configuration
User configuration (name, email, license)
Project configuration (name, description, versioning strategy)
Complete setup summary with next steps

Options:

--reset: Reset and reconfigure everything
--skip-git: Skip git repository setup
--skip-user: Skip user configuration
--skip-project: Skip project configuration

`goal license`

Manage project licenses.

Subcommands:

create <license_id>: Create LICENSE file
update: Update existing LICENSE file
validate: Validate LICENSE file
info <license_id>: Show license information
check <license1> <license2>: Check compatibility
list: List available templates
template <license_id>: Add/show custom templates

Examples:

goal license create MIT --fullname "Your Name"
goal license check MIT Apache-2.0
goal license list

`goal authors`

Manage project authors and team members.

Subcommands:

list: List all project authors
add <name> <email>: Add an author
remove <email>: Remove an author
update <email>: Update author info
import: Import from git history
export: Export to CONTRIBUTORS.md
find <identifier>: Find author by name/email/alias
current: Show current user info

Examples:

goal authors add "Jane Doe" jane@example.com --role "Developer"
goal authors list
goal authors import

Co-author Support

Add co-authors to commits:

goal commit --co-author "Jane Doe <jane@example.com>"
goal commit --co-author "Jane <jane@example.com>" --co-author "Bob <bob@example.com>"

Examples by Use Case

New Project Setup

# Interactive guided setup
goal wizard

📖 Full Wizard Example

License

Licensed under Apache-2.0.

Check license compatibility

goal license check MIT Apache-2.0

📖 [License Management Examples](examples/license-management/)
### Team Collaboration
```bash
# Add team members
goal authors add "Jane Doe" jane@example.com --role "Developer"
# Commit with co-authors
goal commit --co-author "Jane Doe <jane@example.com>"

📖 Multi-Author Project Examples

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
# Update dependencies and run full workflow
goal -au
goal -a -u
# Monorepo: auto-discovers subprojects when root has no manifest
goal -au
# Monorepo: explicit recursive scan (root + all subfolders)
goal -aur
# Monorepo: choose which subprojects to upgrade
goal -aiu
# With specific version bump
goal --all --bump minor

Dependency Updates (Monorepo)

Goal can update dependencies across multiple packages in one run. It detects pyproject.toml, uv.lock, package.json, requirements.txt, and other manifests in subfolders.

Mode	Command	Behavior
Auto (CI)	`goal -au`	Upgrade all detected projects without prompts
Recursive	`goal -aur`	Same as `-au`, but also scans when root has a manifest
Interactive	`goal -aiu`	Ask `Process project <path>?` before each subproject
Manual	`goal -u`	Single project: one prompt; many projects: one bulk confirm

Short flags can be combined: -au, -aur, -aiu, -air, etc.

# Root has no pyproject.toml — auto-discovers packages/frontend, packages/backend, ...cd my-monorepo
goal -au
# Preview dependency upgrades only
goal -au --dry-run
# Pick subprojects interactively
goal -aiu

Rules:

Without -i, -a/--all upgrades all detected projects automatically.
With -i, Goal asks before each subproject (even when -a is set).
Without -a and without -i, a single project gets one confirmation; multiple projects get one bulk confirm first.

CI/CD Pipeline

# GitHub Actions example
- name: Deploy with Goalrun: | goal push --yes --bump minor# Or with --all flag
- name: Full releaserun: | 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 fileversion: "1.0"project:
name: "my-project"# Auto-detected from pyproject.toml/package.jsontype: ["python"] # Auto-detected project typesdescription: "My project"# Auto-detected descriptionversioning:
strategy: "semver"# semver, calver, or datefiles: # Files to sync version to
- "VERSION"
- "pyproject.toml:version"
- "package.json:version"bump_rules: # Auto-bump thresholdspatch: 10# Files changedminor: 50# Lines addedmajor: 200# Large changesgit:
commit:
strategy: "conventional"# conventional, semantic, customscope: "my-project"# Default scope for commitstemplates: # Custom commit templatesfeat: "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: truetemplate: "keep-a-changelog"output: "CHANGELOG.md"sections: ["Added", "Changed", "Fixed", "Deprecated"]tag:
enabled: trueprefix: "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 commitpost_commit: ""# Command to run after commitpre_push: ""# Command to run before pushpost_push: ""# Command to run after pushadvanced:
auto_update_config: true # Auto-update config on detection changesperformance:
max_files: 50# Split commits if > N filestimeout_test: 300# Test timeout in secondsfile_validation:
max_file_size_mb: 10# File size limit (default: 10MB)block_large_files: true # Block large files or just warndetect_api_tokens: true # Scan for API tokensauto_manage_gitignore: true # Auto-update .gitignoreauto_add_dot_folders: true # Auto-add dot folders to .gitignoreknown_dot_folders: # Custom dot folders to ignore
- .idea
- .vscode
- .DS_Store
- .pytest_cache
- .code2llm_cache
- .llmtoken_patterns: [] # Custom regex patterns for token detection

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 releaserelease:
goal
# Automatic patch releasepatch:
goal push --yes
# Full automation releaseall:
goal --all
# Automatic minor releaseminor:
goal push --yes --bump minor
# Automatic major releasemajor:
goal push --yes --bump major
# Dry rundry-run:
goal push --dry-run
# Release with custom messagerelease-message:
goal push --yes -m "$(MSG)"# Release from specific branchrelease-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-commitecho"Running goal pre-commit check..."
goal push --dry-run
if [ $?-eq 0 ];thenecho"✅ Ready to commit!"elseecho"❌ Issues found. Fix them before committing."exit 1
fi

Docker integration

# DockerfileFROM python:3.11-slim
WORKDIR /app
# Install dependenciesCOPY requirements.txt .
RUN pip install -r requirements.txt
# Install goalRUN pip install goal
# Copy source codeCOPY . .
# Run tests and releaseCMD ["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

Security Validation Blocks Commit

Goal automatically protects against security issues:

# Large file detected
❌ Validation Error: File database.dump is 15.2MB, which exceeds the limit of 10MB
# API token detected 
❌ Validation Error: Potential GitHub Personal Access token detected in .env:5
# Solutions:
1. Remove the sensitive/large file
2. Add the file to .gitignore
3. Use --force to bypass (not recommended)

Configure Security Validation

# goal.yamladvanced:
file_validation:
max_file_size_mb: 10# Adjust limitblock_large_files: false # Only warn instead of blockdetect_api_tokens: true # Enable/disable token detectionauto_manage_gitignore: false # Disable auto .gitignore updates

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 = <your-pypi-token>

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.yamladvanced:
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

Licensed under Apache-2.0.

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 ~/.zshrcalias 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 prefixesecho"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.ymlname: Scheduled Releaseon:
schedule:
- cron: '0 9 * * 1'# Every Monday at 9 AMjobs:
release:
runs-on: ubuntu-lateststeps:
- uses: actions/checkout@v3
- name: Install Goalrun: pip install goal
- name: Weekly Releaserun: goal --all --bump patch

License

Licensed under Apache-2.0.

Author

Tom Sapletta

Status

Last updated by taskill at 2026-04-25 13:38 UTC

Metric	Value
HEAD	`7edd05b`
Coverage	—
Failing tests	—
Commits in last cycle	50

Introduces a configuration management system, improves the code analysis engine and commit message generation, expands CLI functionality and markdown output support, and applies bulk TODO fixes and documentation updates.

Name		Name	Last commit message	Last commit date
Latest commit History 709 Commits
.aider		.aider
.github		.github
.governance		.governance
.planfile		.planfile
.redsl		.redsl
.taskill		.taskill
TODO		TODO
docs		docs
examples		examples
goal		goal
integration		integration
project		project
scripts		scripts
testql-scenarios		testql-scenarios
tests		tests
workflows		workflows
.aider.chat.history.md		.aider.chat.history.md
.aider.input.history		.aider.input.history
.dockerignore		.dockerignore
.gitignore		.gitignore
.nojekyll		.nojekyll
.pre-commit-config.yaml		.pre-commit-config.yaml
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
REFACTOR_PLAN.md		REFACTOR_PLAN.md
SUMD.md		SUMD.md
SUMR.md		SUMR.md
TICKET		TICKET
TODO.md		TODO.md
Taskfile.yml		Taskfile.yml
VERSION		VERSION
app.doql.less		app.doql.less
claude-taking-longer-than-usual.webm		claude-taking-longer-than-usual.webm
compose.yml		compose.yml
goal.yaml		goal.yaml
index.html		index.html
local.dev.txt		local.dev.txt
nlp2uri.yaml		nlp2uri.yaml
planfile.yaml		planfile.yaml
prefact.yaml		prefact.yaml
project.bat		project.bat
project.functions.toon		project.functions.toon
project.sh		project.sh
project.toon-schema.json		project.toon-schema.json
pyproject.toml		pyproject.toml
pyqual.yaml		pyqual.yaml
redsl.yaml		redsl.yaml
redsl_refactor_plan.md		redsl_refactor_plan.md
redsl_refactor_plan.toon.yaml		redsl_refactor_plan.toon.yaml
redsl_refactor_report.md		redsl_refactor_report.md
redsl_refactor_report.toon.yaml		redsl_refactor_report.toon.yaml
regix.yaml		regix.yaml
test_recovery.py		test_recovery.py
tree.sh		tree.sh
tree.txt		tree.txt
uv.lock		uv.lock
wup.yaml		wup.yaml

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Goal

AI Cost Tracking

Why you might need Goal

What you get out of the box

Three real-life flows

Adopt repository governance

🆕 What's New in v2.2.2

✨ New Features

🆕 What's New in v2.2.1

✨ New Features

🔧 Architecture Improvements

🆕 What's New in v2.2.0

✨ New Features

🛠️ Enhanced Commands

🆕 What's New in v2.1.99

✨ New Security Features

🛡️ Security Validation in Action

⚙️ Configuration Options

🚀 Bypass Options

🆕 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

4. Monorepo sweep — run goal -a across many repos

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

11. Security Validation Examples

12. 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

goal wizard

goal license

goal authors

Co-author Support

Examples by Use Case

New Project Setup

License

Check license compatibility

Development Workflow

Full Automation

Dependency Updates (Monorepo)

CI/CD Pipeline

Skip Testing in Quick Fixes

2. Run `goal` in any project directory

4. Monorepo sweep — run `goal -a` across many repos

`goal` or `goal push`

`goal doctor`

`goal init`

`goal status`

`goal version`

`goal wizard`

`goal license`

`goal authors`