---
since: 1.1.1
---

# Command Reference

gitaiflow has a single-command surface — every feature is a flag on the root `gitaiflow` invocation rather than a subcommand.

```text
usage: gitaiflow [--path PATH] [--remote REMOTE] [--base-branch BASE_BRANCH]
                  [--skip [PATH_OR_PATTERN ...]] [-o OUTPUT_DIR] [--markdown]
                  [--no-chunk] [--change-summary] [--show-analysis]
                  [--last-summary] [--regenerate-summary] [--allow-billing]
                  [--changelog] [--since DATE] [--until DATE] [--release-notes]
                  [--list-models] [--free-only] [--json]
                  [--version] [--usage [current|VERSION]]
                  [--telemetry {enable,disable,status,history}] [--uninstall]
```

An AI provider must be configured before any summary-generating flag will run — see [`configuration.md`](configuration.md). `--list-models`, `--usage`, `--telemetry`, and `--version` are exceptions: they exit immediately and never require provider configuration or touch Git.

## Target selection

```bash
gitaiflow --path mailer/                # summarize a directory
gitaiflow --path users/views/logout.py  # summarize a single file
gitaiflow --path .                      # summarize the whole repo (default)
```

Defaults to the current directory when `--path` is omitted.

## `--remote` / `--base-branch`

```bash
gitaiflow --path . --remote upstream --base-branch develop
```

`--remote` defaults to the current branch's upstream remote if it has one, else the `GITAIFLOW_REMOTE` environment variable if set, else `origin` if present, else the only remote if there's exactly one. If none of those resolve, gitaiflow fails with an explicit error listing the available remotes rather than guessing. `--base-branch` defaults to the remote's detected default branch (its `HEAD`), falling back to `main`.

## `--skip`

```bash
gitaiflow --path . --skip dist/ "*.svg" "*.json"
```

Accepts three kinds of entries, space-separated (not comma-separated — each is a distinct CLI argument):

1. A directory (e.g. `dist/`, `build/vendor`) — skips everything under it.
2. An exact file path (e.g. `src/generated.py`).
3. A file-type pattern like `*.svg` or `*.json` — skips every matching file wherever it is. Quote these so your shell doesn't expand the `*`.

Paths are relative to `--path` unless given as absolute paths.

## `-o`, `--output-dir`

```bash
gitaiflow --path . -o artifacts/
```

Root artifact output directory (default: `change-summary`). With `--changelog`, pass the same value used when the change-summary was generated so the changelog reads from the right place.

## `--markdown`

```bash
gitaiflow --path . --markdown
```

Also writes a human-facing Markdown view derived from the same canonical JSON payload.

## `--no-chunk`

```bash
gitaiflow --path . --no-chunk
```

By default, when `--path` points at a directory, gitaiflow groups changed files by their top-level subdirectory and generates one commit summary per group — keeping individual AI requests small enough to avoid provider context-length limits and free-tier token quotas on large diffs. `--no-chunk` forces a single AI request covering the entire diff instead.

With `--change-summary`, each chunk's title/body is printed under a `=== <chunk-name> ===` header.

## `--change-summary` / `--show-analysis`

```bash
gitaiflow --path . --change-summary
gitaiflow --path . --change-summary --show-analysis
```

`--change-summary` prints just the commit title/body to stdout — pipeable straight into `git commit -F -` (this flag was previously named `--print-commit`). `--show-analysis` additionally prints the model's raw reasoning/analysis text (if any) that preceded its final `TITLE:`/`BODY:` answer; off by default, useful for debugging odd or truncated commit messages.

## `--last-summary`

```bash
gitaiflow --path . --last-summary
```

Prints the most recently generated change-summary straight from disk — no git diff, no AI call, no new run. Reads only the single latest saved `change-summary/` JSON file, across any past run or day, and says so instead of generating one if none exists yet.

## `--regenerate-summary`

```bash
gitaiflow --path . --regenerate-summary
```

Forces a fresh AI summary for every group even if its diff exactly matches one already summarized before (on any previous day, not just today). Normally a matching diff skips the AI call and reuses the earlier summary to save cost; this flag forces regeneration anyway — useful after `change-summary/` was deleted by mistake, or when you just want a fresh take.

## `--allow-billing`

```bash
gitaiflow --path . --allow-billing
```

Skips the pre-flight free-model check. For OpenRouter, this bypasses the catalog check that normally blocks non-free/unverifiable model IDs. For other providers (Gemini, OpenAI, Ollama, xAI-via-custom, ...) it also silences the passive reminder that gitaiflow can't verify their pricing.

## Changelog generation

```bash
gitaiflow --changelog --since 2026/08/01 --path .                # exact date, through today
gitaiflow --changelog --since "3 days ago" --path .               # relative, through right now
gitaiflow --changelog --since "2 weeks ago" --until "3 days ago" --path .
gitaiflow --changelog --since 2026/08/01 --path . -o artifacts/   # match a custom -o used to generate change-summary
```

`--since` (required with `--changelog`, defaults to the start of today when omitted) and `--until` (optional) each accept either an exact date (`YYYY/MM/DD`) or a relative expression — `<N> minute(s)/hour(s)/day(s)/week(s)/month(s) ago`. Years aren't a supported unit — use an exact date for anything that wide.

A range that resolves entirely before the repository's first commit, or into the future, is rejected upfront with an error instead of silently producing an empty changelog.

gitaiflow resolves `<remote>/<base-branch>` the same way a normal summary run does, then builds the changelog primarily from **change-summary JSON artifacts** already generated for that range. If more than one artifact touches the same file within the range, only the newest one is used. An artifact generated against a different base than the one resolved for this run is not counted; if no artifacts exist for the range, gitaiflow falls back to `git log` on the resolved base ref. Commits are grouped by conventional-commit type and prepended above any existing `CHANGELOG.md` content — existing entries are never modified, and a re-run for the same version replaces that version's block rather than duplicating it.

> `--changelog` doesn't call an AI provider — it either reads already-generated JSON or falls back to `git log` — so it never touches the local usage log or telemetry either way; those are only recorded on a normal summary run.

## `--release-notes`

```bash
gitaiflow --release-notes
```

(Re)writes `RELEASE_NOTES.md` at the repo root, generated by the AI from the `CHANGELOG.md` entry for the current resolved project version — run `--changelog` first if that entry doesn't exist yet. Always a full overwrite describing the release currently being cut, not a rolling history; uses the same AI provider/model and error handling as a normal summary run.

## Model discovery

```bash
gitaiflow --list-models
gitaiflow --list-models --free-only
gitaiflow --list-models --json
```

See [`model-selection.md`](model-selection.md) for the full model-discovery and selection workflow.

## `--usage`

```bash
gitaiflow --usage                    # most recent run
gitaiflow --usage current            # same as bare --usage
gitaiflow --usage 1.0.6              # aggregate for runs recorded under this gitaiflow version
gitaiflow --usage --since "1 week ago" --until "2 days ago"   # custom date range
```

Shows local usage stats (tokens in/out, duration, success) from `~/.gitaiflow/usage.jsonl` and exits — never runs a summary.

## `--telemetry`

```bash
gitaiflow --telemetry enable
gitaiflow --telemetry disable
gitaiflow --telemetry status
gitaiflow --telemetry history
```

Durably sets or checks anonymous usage telemetry consent, independent of the current terminal session (unlike `GITAIFLOW_TELEMETRY`, which only affects the current process). `history` shows every recorded answer with its version and timestamp. Each of these exits immediately — see [`telemetry.md`](telemetry.md) for the full consent model.

## `--version`

```bash
gitaiflow --version
```

## `--uninstall`

```bash
gitaiflow --uninstall
```

Removes the gitaiflow binary and its local state files, and warns if any `AI_*`/`GITAIFLOW_*` environment variables are still exported in your current shell.

## Output

Every summary run writes one JSON file to `change-summary/<YYYY>/<MM>/<DD>/json/<target>-<timestamp>.json`, partitioned by the date of the run so history from previous days is never touched or re-scanned by a later run:

```json
{
  "generated_at": "2026-08-19T14:32:07+05:30",
  "target": "mailer",
  "target_type": "directory",
  "repository": "paystream",
  "branch": "feature/mailer-retry",
  "base": "origin/main",
  "author": { "name": "Chandrashekhar Bhosale", "email": "shekhar@djangoplay.org" },
  "change_window": {
    "first_change_at": "2026-08-18 09:12:03",
    "last_change_at": "2026-08-19 14:30:11"
  },
  "files_changed": [
    { "path": "mailer/tasks.py", "status": "modified" },
    { "path": "mailer/retry.py", "status": "added" }
  ],
  "model": { "provider": "gemini", "name": "gemini-flash-lite-latest" },
  "commit": {
    "title": "mailer: add retry backoff for failed sends",
    "body": "- Added exponential backoff retry logic in retry.py\n- tasks.py now retries send_mail up to 3 times on failure\n- No changes to public function signatures"
  },
  "summary": "(same content as commit.body)"
}
```

`author`, `branch`, `base`, `change_window`, and `files_changed` come straight from Git — never from the model — so they're accurate even if the AI call fails or hallucinates. `commit.title` / `commit.body` are the only model-generated fields, and they're the ones designed to be commit-ready as-is. `base` is also what `--changelog` matches against — it only includes an artifact whose `base` equals the `<remote>/<base-branch>` resolved for that run.

`--markdown` renders a second, human-facing view from the same JSON into `change-summary/<YYYY>/<MM>/<DD>/markdown/` — the JSON is always the source of truth.

## Local usage log

Every summary run appends one line to `~/.gitaiflow/usage.jsonl` — timestamp, repo name, target type, model used, estimated token counts, duration, success. **This file never leaves your machine.** It exists so you can see your own usage (`--usage`) and, optionally, set soft daily limits:

```bash
export GITAIFLOW_MAX_RUNS_PER_DAY=20
export GITAIFLOW_MAX_TOKENS_PER_DAY=50000
```

When set, gitaiflow prints a warning once you've crossed the threshold for the day. This is a courtesy guardrail against accidentally running up a cloud-model bill, not enforcement — it's a local file, and any user can clear it.

## Related

- [`README.md`](README.md) — user-guide index
- [`configuration.md`](configuration.md) — AI provider environment variables
- [`telemetry.md`](telemetry.md) — the full opt-in telemetry consent model
- [`../api/README.md`](../api/README.md) — the flag surface as a stable contract