Taggo.Cli 0.0.4

Taggo

Taggo is an interactive CLI for calculating, previewing, creating, and pushing annotated semantic-version Git tags. It can work in the current checkout or orchestrate the same flow across configured repositories.

Taggo preserves Git as the source of truth: it tags the checked-out commit, never commits working-tree changes, and never deletes a local tag automatically.

Install

.NET tool

The .NET tool requires the .NET 10 runtime:

dotnet tool install --global Taggo.Cli
taggo --version

Self-contained installers

Tagged releases also provide self-contained distributions that do not require a separate .NET runtime:

• Windows x64: Taggo-<version>-win-x64.msi
• Debian-compatible Linux x64: Taggo_<version>_amd64.deb
• macOS Apple silicon: Taggo-<version>-osx-arm64.pkg

Download release artifacts from the authenticated GitHub release or the project’s published installer endpoint. Verify the published SHA-256 checksum before installation. Windows and macOS tagged-release installers are signed; the macOS package is also notarized and stapled.

All installations require Git. Creating tags also requires an interactive ANSI-capable terminal, a Git worktree on a checked-out branch, and a configured non-local upstream with fetch and push access.

Commands

Create a tag in the current checkout:

taggo create new

Create tags in one or more configured repositories, preserving argument order:

taggo create new --repo <name-or-alias> [--repo <name-or-alias> ...]

Select configured repositories interactively:

taggo create new --select

Manage the repository registry:

taggo repo add <name> [--path <local-path>] [--alias <alias> ...]
taggo repo list
taggo repo remove <name-or-alias> [<name-or-alias> ...]
taggo repo path
taggo repo edit

repo add defaults to the current directory when --path is omitted. Repository names and aliases are case-insensitively unique and may not be blank, contain whitespace or control characters, or start with -. Paths are stored as absolute canonical paths without redundant trailing separators.

General information:

taggo --help
taggo --version

Exit codes are 0 for success or an intentional no-op, 1 for an operational failure, 2 for invalid usage, and 130 for cancellation.

Tag workflow

For every selected repository, Taggo:

1. verifies the worktree, checked-out branch, and remote upstream;
2. checks for tracked and untracked working-tree changes;
3. pulls the upstream using fast-forward-only mode and fetches tags;
4. displays the three highest tags matching vX.Y.Z;
5. asks for a major, minor, or patch bump;
6. builds the selected annotated-tag metadata;
7. shows the complete plan and asks for confirmation;
8. creates the local annotated tag and pushes its fully qualified ref.

Use <kbd>Space</kbd> to toggle multi-select values and <kbd>Enter</kbd> to continue. Tag, Branch, Hash, and Date are selected by default. Title and Description are requested only when selected.

If no valid version tag exists, calculation starts at v0.0.0. Other tag formats are ignored. Taggo rechecks local tag availability immediately before the final plan to reduce prompt-time races.

For batch operations, preparation and release selection happen per repository. Metadata settings may be shared, but each repository keeps its own baseline, branch, commit, and tag. A failed repository is reported independently; when more work remains, Taggo asks whether to continue. The final summary distinguishes succeeded, failed, skipped, and unattempted repositories.

Local changes, cancellation, and recovery

When local changes exist, continuing defaults to No. If you continue, Taggo explains that the changes are not included in the tag and asks whether to skip the pull, defaulting to Yes. Skipping the pull still fetches remote tags.

Cancellation before local tag creation leaves no intentional Git mutation. If creation or push fails or is cancelled, Taggo checks whether the local tag exists. When it exists—or its state cannot be verified safely—Taggo prints recovery guidance:

git push -- <remote> refs/tags/<tag>:refs/tags/<tag>
git tag --delete -- <tag>

The first command retries the exact tag push. The second removes the local tag so the workflow can be rerun. Inspect the tag before deleting it; Taggo never removes it automatically.

Repository configuration

taggo repo path prints the exact configuration path. It is normally:

• Windows: %APPDATA%\taggo\config.json
• macOS: ~/Library/Application Support/taggo/config.json
• Linux: $XDG_CONFIG_HOME/taggo/config.json, or the platform application-data fallback

Example:

{
  "repositories": [
    {
      "name": "payments",
      "path": "/absolute/path/to/payments",
      "aliases": [
        "pay"
      ]
    }
  ]
}

repositories is required. Unknown and duplicate properties are rejected, as are duplicate identifiers, duplicate canonical paths, relative or missing paths, and control characters. aliases may be omitted. Writes use an exclusive cross-process lease and atomic replacement. On Unix-like systems, the registry, temporary replacement, and lock file are user-readable/writable only.

taggo repo edit uses VISUAL, then EDITOR, without a shell. The edited file is validated before the command succeeds. Add, remove, and edit operations hold the same mutation lease so concurrent commands cannot silently overwrite one another.

Development

The repository pins .NET SDK 10.0.302, package dependency graphs, NuGet.org as the only package/audit source, latest-recommended analyzers, and warnings as errors.

Run the complete local gate:

./.agentvault/validate

Equivalent focused checks include:

dotnet restore Taggo.Cli.slnx --locked-mode
dotnet format Taggo.Cli.slnx --verify-no-changes --no-restore
dotnet build Taggo.Cli.slnx -c Release --no-restore -m:1 --disable-build-servers
dotnet test Taggo.Cli.slnx -c Release --no-build \
  --results-directory ./artifacts/test-results \
  --collect "XPlat Code Coverage"
python3 scripts/check_coverage.py \
  ./artifacts/test-results/*/coverage.cobertura.xml
dotnet list Taggo.Cli.slnx package --vulnerable --include-transitive
dotnet pack src/Taggo.Cli/Taggo.Cli.csproj -c Release --no-restore \
  -m:1 --disable-build-servers

The coverage gate requires at least 70% overall line and 70% overall branch coverage.

Release trust boundaries

CI external actions are pinned to full commit SHAs and run with minimal default permissions. Reusable workflow inputs are allowlisted or validated before they reach shell commands. Dependency restore is locked, audited, and restricted to NuGet.org.

Tagged releases require protected release-environment credentials. GitHub uses OIDC for Azure access and a short-lived NuGet API key. Versioned Azure artifacts are immutable and hash-verified before the guarded latest.json promotion. Windows artifacts require Authenticode signing and timestamp verification; macOS artifacts require separate application/installer certificates plus notarization. Release metadata rejects malformed versions, unsafe paths, credential-bearing URLs, inconsistent artifact names, and missing artifacts.