Installation & Setup

Follow these steps to install the repotographer CLI and configure your environment.

1. Prerequisites

1. Install and authenticate GitHub CLI (gh)

   repotographer invokes gh to retrieve public repository metadata from GitHub.

   macOS (Homebrew)

   brew install gh
   gh auth login

   Linux (apt)

   sudo apt install gh
   gh auth login

   Windows (winget)

   winget install --id GitHub.cli
   gh auth login

   Verify authentication before running repotographer:

   gh auth status

2. Install Graphviz (Optional, for PNG rendering)

   repotographer renders static .png diagrams when the dot command is present on your PATH. When Graphviz is missing, the tool generates .dot and interactive .html files without halting.

   macOS (Homebrew)

   brew install graphviz

   Linux (apt)

   sudo apt install graphviz

3. Configure Gemini or Vertex AI (Optional, for AI taxonomy)

   repotographer uses gemini-3.7-flash to organize repositories into high-level domain pillars.

   Gemini Developer API (Default)

   Obtain an API key from Google AI Studio and export it:

   export GEMINI_API_KEY="your-gemini-api-key"

   Google Cloud Vertex AI

   Authenticate with Google Cloud and specify your project:

   export GOOGLE_GENAI_USE_VERTEXAI="true"
   export GOOGLE_CLOUD_PROJECT="your-project-id"  # Or PROJECT_ID / GCP_PROJECT
   export GOOGLE_CLOUD_LOCATION="global"

   Tip

   If GEMINI_API_KEY is not set, but a GCP project is present in your ambient environment (GOOGLE_CLOUD_PROJECT, PROJECT_ID, or GCP_PROJECT), repotographer automatically detects and uses Vertex AI with Application Default Credentials. If no credentials are configured, it falls back cleanly to deterministic keyword heuristics.

---

2. Install repotographer

Install directly with Go 1.23+ or clone the source repository:

Pre-built Binaries

Download the latest release archive for macOS (Apple Silicon or Intel), Linux, or Windows from the GitHub Releases page, unpack the binary, and move it to your $PATH.

Go Install

go install github.com/ghchinoy/repotographer@latest

From Source

git clone https://github.com/ghchinoy/repotographer.git
cd repotographer
make build
# Binary is created in ./bin/repotographer

Verify the binary is available:

repotographer version

Output:

repotographer v0.2.1