---
since: 1.1.1
---

# API Documentation

gitaiflow exposes its API through the `gitaiflow` executable — a compiled native binary. There is no HTTP API and no subcommand structure; every feature is a flag on the single root invocation.

## Entry point

```bash
gitaiflow --help
```

## Current command surface

```text
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]
```

## Execution modes

gitaiflow has four independent execution modes, selected by which flags are present:

| Mode | Trigger | Calls an AI provider? | Touches Git? |
| --- | --- | --- | --- |
| Normal summary | default (no mode flag) | Yes | Yes |
| Changelog | `--changelog` | No | Yes (or reads existing JSON artifacts) |
| Model catalog | `--list-models` | No (queries OpenRouter's public catalog) | No |
| Usage / telemetry | `--usage`, `--telemetry` | No | No |

`--list-models`, `--usage`, `--telemetry`, and `--version` exit immediately and never run the summary pipeline.

## Global options

```bash
gitaiflow --version   # print version and exit
gitaiflow --help      # print usage and exit
```

## Feature flags

### Target selection

```bash
gitaiflow --path mailer/
```

### Provider-required summary generation

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

Requires a configured AI provider — see [`configuration.md`](configuration.md). Fails fast with configuration instructions rather than partway through a run if nothing is configured.

### Changelog generation

```bash
gitaiflow --changelog --since 2026/08/01 --path .
```

Does not call an AI provider.

### Model discovery

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

Independent of the configured `AI_PROVIDER` — always targets OpenRouter's public catalog endpoint, and doesn't require an API key.

### Telemetry consent

```bash
gitaiflow --telemetry status
```

## Exit behavior

| Condition | Behavior |
| --- | --- |
| Successful summary / changelog / model-list / usage / telemetry command | Exit `0` |
| No AI provider configured (normal summary mode) | Fails fast with configuration instructions before any AI request is attempted |
| `--changelog` range resolves entirely before repository history, or into the future | Rejected upfront with an error, no changelog written |
| AI provider call fails | Non-fatal to the changelog/model-catalog/usage/telemetry paths; a normal summary run reports the failure |

## Full command reference

See [`../user-guide/commands.md`](../user-guide/commands.md) for every flag with usage examples and output schema, and [`configuration.md`](configuration.md) for the environment-variable contract that backs provider selection.