Visit djangoplay.org ↗
gitaiflow / User guide / Installation
DocsgitaiflowUser guideInstallation

Installation

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

3 min readApplies to v1.1.3
On this page ▾
  1. Supported Platforms & Asset Coverage
  2. 1. Quick Install (Recommended)
  3. Verify Installation
  4. Build From Source
  5. Configure an AI Provider (Required Before First Run)
  6. Uninstallation
  7. Upgrading

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 below).

# 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

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