---
since: 1.1.1
---

# Installation

gitaiflow is distributed as a standalone native binary — no Python runtime or package manager is required to run it.

## Supported Platforms & Asset Coverage

| Binary File | Target OS / Environment | Target Architecture |
| --- | --- | --- |
| `gitaiflow-darwin-arm64` | macOS (Apple Silicon: M1, M2, M3, M4) | ARM 64-bit (`arm64`) |
| `gitaiflow-linux-amd64` | Linux (Ubuntu, Debian, RedHat, standard cloud VMs) | Intel/AMD 64-bit (`x86_64`) |
| `gitaiflow-linux-arm64` | Linux (AWS Graviton, Raspberry Pi, Apple Silicon Docker) | ARM 64-bit (`aarch64`/`arm64`) |
| `gitaiflow-windows-amd64.exe` | Windows 10, 11, Server | 64-bit (`x86_64`) |

macOS Intel (`x86_64`) has no prebuilt binary yet — install from source on that platform (see [Build From Source](#build-from-source) below).

## 1. Quick Install (Recommended)

::: tabs
```bash [macOS & Linux]
# latest
curl -fsSL https://install.djangoplay.org/gitaiflow | bash

# a specific version (note the -s -- before args when piping into bash)
curl -fsSL https://install.djangoplay.org/gitaiflow | bash -s -- v1.0.0
```
```powershell [Windows (PowerShell)]
# latest (run PowerShell as Administrator)
irm https://install.djangoplay.org/gitaiflow.ps1 | iex

# a specific version
$env:GITAIFLOW_VERSION = "v1.0.0"; irm https://install.djangoplay.org/gitaiflow.ps1 | iex
```
:::

Both installers detect OS/architecture automatically (`uname -s`/`uname -m` on macOS/Linux, `$env:PROCESSOR_ARCHITECTURE` on Windows), resolve the latest version from R2 when none is given, download the matching binary, and place it on `PATH`:

- macOS/Linux: `/usr/local/bin/gitaiflow`
- Windows: `%LOCALAPPDATA%\Programs\gitaiflow\gitaiflow.exe`, added to the user `PATH`

Either installer also creates an empty `~/.gitaiflow/config.env` (left untouched on upgrades) for the four mandatory provider variables — see [Configure an AI Provider](#configure-an-ai-provider-required-before-first-run) below.

## Verify Installation

```bash
gitaiflow --version
gitaiflow --help
```

## Build From Source

For customized environments, or platforms without a prebuilt binary (macOS Intel):

```bash
git clone https://gitlab.com/clizero/gitaiflow.git
cd gitaiflow

# Install compilation prerequisites
pip install -e .[dev]
pip install -U nuitka zstandard

# Compile into a standalone single-file binary
chmod +x scripts/install/compile.sh
./scripts/install/compile.sh

# Binary is written to ./bin/gitaiflow
./bin/gitaiflow --version
```

See [`../deployment/local-development.md`](../deployment/local-development.md) for the full local build/test workflow.

## Configure an AI Provider (Required Before First Run)

gitaiflow needs four environment variables set — `AI_PROVIDER`, `AI_API_KEY`, `AI_BASE_URL`, and `AI_MODEL` — and none of them has a built-in default; it will not run until all four resolve to a non-empty value. See [`configuration.md`](configuration.md) for the full provider reference; the quickest path is OpenRouter's free router:

```bash
# fill in the ~/.gitaiflow/config.env the installer created, a project-local
# .env anywhere from your current directory up to your repository root, or
# export these as real environment variables — gitaiflow checks all three
AI_PROVIDER=custom
AI_BASE_URL=https://openrouter.ai/api/v1
AI_API_KEY=<your-openrouter-api-key>
AI_MODEL=openrouter/free
```

Running `gitaiflow` with any of the four still empty prints exactly which ones are missing.

## Uninstallation

```bash
gitaiflow --uninstall
```

Removes the running gitaiflow binary itself (wherever it's actually installed, not just the default install path) along with its local state files, and warns if any `AI_*`/`GITAIFLOW_*` environment variables are still exported in your current shell.

## Upgrading

Re-running the original install command cleanly overwrites the existing binary — you do **not** need to uninstall first:

```bash
curl -fsSL https://install.djangoplay.org/gitaiflow | bash
```

```powershell
irm https://install.djangoplay.org/gitaiflow.ps1 | iex
```

Your `~/.gitaiflow/config.env` provider configuration, `~/.gitaiflow/usage.jsonl` local usage log, and telemetry decision are untouched by an upgrade — they live independently of the binary itself, and the installer leaves an existing `config.env` alone.