Skip to content

Configuration Guide

Jump to bottom
github-actions[bot] edited this page Mar 14, 2026 · 1 revision

Configuration and Environment Variables

This page provides a complete reference for all configuration options in wikigen, including environment variables, .env file format, configuration precedence, and practical configuration examples. Configuration in wikigen controls repository access methods, output language, parallelism settings, model selection, and directory locations. Settings can be configured via CLI flags (highest priority), environment variables, .env files, or hardcoded defaults (lowest priority). This documentation covers how to set up each option, understand configuration precedence, and manage configurations across different deployment scenarios.

Configuration Methods

wikigen supports multiple configuration methods that work together through a clear precedence system. Configuration can be provided via CLI flags, environment variables, .env files, or combinations thereof.

Configuration Sources and Priority

The configuration system loads settings in the following order, with later sources overriding earlier ones:

  1. Hardcoded Defaults — Built-in fallback values in the code
  2. .env.example — Example configuration file (reference only)
  3. .env file — Local project-specific configuration
  4. .env.local file — Machine-specific overrides (git-ignored)
  5. Environment Variables — Shell-level variables set via export
  6. CLI Flags — Command-line arguments (highest priority)

Sources: main.go:692-715, main.go:717-737

flowchart TD
    A["1. Hardcoded Defaults<br/>(in code)"]
    B["2. .env.example<br/>(reference)"]
    C["3. .env<br/>(local project config)"]
    D["4. .env.local<br/>(machine-specific)"]
    E["5. Environment Variables<br/>(shell exports)"]
    F["6. CLI Flags<br/>(command-line args)"]
    G["Final Configuration<br/>(used by wikigen)"]

    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    F --> G

    style A fill:#e3f2fd
    style G fill:#4CAF50,color:#fff
    style F fill:#ff9800,color:#fff
Loading

.env File Format

The .env and .env.local files use standard key=value format. Configuration options are defined one per line, with optional comments.

File Format Specification

# This is a comment (ignored)
VARIABLE_NAME=value

# Spaces around = are trimmed
KEY = value  # becomes: KEY = "value"

# Empty lines are ignored

# Options not set default to hardcoded values

Key points:

  • Comments start with # and extend to end of line
  • Empty lines are ignored
  • Whitespace around = is trimmed
  • Inline comments (e.g., KEY=value # comment) are not supported — the entire portion after = becomes the value
  • Variables not present in the file use their hardcoded defaults

Sources: main.go:717-737

Example .env File

# GitHub Authentication
# Leave empty to use SSH, or set to a Personal Access Token
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Claude Model Selection
# Options: haiku (fast), sonnet (balanced), opus (capable)
CLAUDE_MODEL=haiku

# Output Language
# Default: ja (Japanese)
# Options: en, ja, zh, zh-tw, es, kr, vi, pt-br, fr, ru
WIKI_LANGUAGE=en

# Parallelism Settings
# Number of repositories to process in parallel
WIKI_PARALLEL=2

# Number of wiki pages to generate in parallel per repository
WIKI_PAGE_PARALLEL=3

# Directory Paths
WIKI_OUTPUT_DIR=./wiki-output
WIKI_CLONE_DIR=./.repos

Environment Variable Reference

All string and numeric configuration options support environment variable overrides. Boolean flags (-retry, -dry-run, -json) cannot be set via environment variables.

Complete Option Reference

Environment Variable CLI Flag Type Default Description
GITHUB_TOKEN -token string (empty) GitHub Personal Access Token. Leave empty for SSH authentication
CLAUDE_MODEL -model string (unset) Claude model: haiku, sonnet, or opus. If unset, uses Claude CLI default
WIKI_LANGUAGE -lang string ja Output documentation language
WIKI_OUTPUT_DIR -o string ./wiki-output Directory where generated wiki files are written
WIKI_CLONE_DIR -clone-dir string ./.repos Directory where repositories are cloned
WIKI_PARALLEL -p integer 1 Number of repositories/projects to process in parallel
WIKI_PAGE_PARALLEL -pp integer 3 Number of pages to generate in parallel per project
— -f string — Path to file containing repository list
— -r string — Comma-separated list of repositories
— -log string stderr Path to log file (default: stderr)
— -claude string claude Path to claude CLI binary
— -retry flag false Retry only failed pages from previous run
— -dry-run flag false Preview structure, skip page generation
— -json flag false Output results as JSON to stdout
— -local string — Use local directory instead of cloning

Sources: main.go:882-914, main.go:906

Environment Variable Loading

The .env and .env.local files are automatically loaded from the current working directory when wikigen starts. Only variables not already set as environment variables are loaded, allowing shell exports to take precedence.

Loading Logic

func loadEnvFile() {
	for _, path := range []string{".env", ".env.local"} {
		data, err := os.ReadFile(path)
		if err != nil {
			continue
		}
		for _, line := range strings.Split(string(data), "\n") {
			line = strings.TrimSpace(line)
			if line == "" || strings.HasPrefix(line, "#") {
				continue
			}
			if k, v, ok := strings.Cut(line, "="); ok {
				k = strings.TrimSpace(k)
				v = strings.TrimSpace(v)
				if os.Getenv(k) == "" {
					os.Setenv(k, v)
				}
			}
		}
	}
}

Sources: main.go:717-737

Key behaviors:

  • .env is loaded first, then .env.local
  • Both files are optional — missing files are silently skipped
  • Environment variables set in shell take precedence over file values
  • Only the current working directory is searched (not parent directories)

Command-Line Flag Reference

All configuration options can be set via command-line flags. Flags use standard Go flag syntax with single-dash format.

Flag Syntax

./wikigen -flag value owner/repo
./wikigen -flag=value owner/repo
./wikigen -boolean-flag owner/repo

Boolean flags accept no value (presence = true), while string and integer flags require an argument.

Supported Flags

# Repository Input (required — one of: positional args, -r, or -f)
-r "owner/repo1,owner/repo2"      # Comma-separated repos
-f repos.txt                        # File with one repo per line
owner/repo [owner/repo2 ...]       # Positional arguments

# Authentication
-token "ghp_xxxxxxxxxxxxxxxxxxxx"  # GitHub PAT (overrides GITHUB_TOKEN)

# Output Control
-o ./wiki-output                    # Output directory
-lang en                            # Language code
-model haiku                        # Claude model

# Processing Options
-p 2                                # Repository parallelism
-pp 5                               # Page-level parallelism
-clone-dir ./.repos                 # Clone directory

# Operation Modes
-dry-run                            # Structure only, no generation
-retry                              # Regenerate failed pages
-json                               # JSON output to stdout
-local /path/to/repo                # Use local dir instead of clone

# Advanced
-log output.log                     # Log file path
-claude /usr/bin/claude             # Path to claude binary

Sources: main.go:900-914

Language Options

wikigen supports multiple output languages for documentation generation. Language is specified via the -lang flag or WIKI_LANGUAGE environment variable.

Supported Languages

Code Language Native Name
en English English
ja Japanese 日本語
zh Simplified Chinese 中文
zh-tw Traditional Chinese 繁體中文
es Spanish Español
kr Korean 한국어
vi Vietnamese Tiếng Việt
pt-br Brazilian Portuguese Português Brasileiro
fr French Français
ru Russian Русский

Default: ja (Japanese)

Sources: main.go:364-376

Examples:

./wikigen -lang en owner/repo          # Generate in English
./wikigen -lang ja owner/repo          # Generate in Japanese
export WIKI_LANGUAGE=es && ./wikigen owner/repo  # Spanish

Model Selection

wikigen supports different Claude models with different capabilities and costs. Model selection affects generation speed, cost, and documentation quality.

Claude Model Options

Model Speed Cost Capability Use Case
haiku Very Fast Lowest Basic Quick documentation, high parallelism
sonnet Balanced Medium Advanced Recommended for most projects
opus Slower Highest Most capable Complex codebases, detailed analysis

Default: Claude CLI's configured default (usually Sonnet)

Sources: main.go:118-119

./wikigen -model haiku owner/repo      # Fast, low cost
./wikigen -model sonnet owner/repo     # Balanced (recommended)
./wikigen -model opus owner/repo       # Most capable, highest cost

# Via environment variable
export CLAUDE_MODEL=sonnet && ./wikigen owner/repo

# Via .env file
echo "CLAUDE_MODEL=haiku" >> .env
./wikigen owner/repo

Parallelism Configuration

wikigen supports two levels of parallelism for optimizing processing speed: repository-level and page-level parallelism.

Repository-Level Parallelism

The -p flag controls how many repositories are processed simultaneously. Higher values speed up batch processing but increase memory and API usage.

./wikigen -f repos.txt -p 1            # Sequential (one repo at a time)
./wikigen -f repos.txt -p 2            # 2 repos in parallel
./wikigen -f repos.txt -p 4            # 4 repos in parallel

export WIKI_PARALLEL=3 && ./wikigen -f repos.txt

Recommended values:

  • 1 (default): Low resource usage, suitable for CI/CD
  • 2-3: Balanced for local machines
  • 4+: High-performance servers with plenty of resources

Page-Level Parallelism

The -pp flag controls how many pages are generated in parallel per project. Higher values speed up single-project generation.

./wikigen -pp 1 owner/repo             # Generate pages sequentially
./wikigen -pp 3 owner/repo             # 3 pages in parallel (default)
./wikigen -pp 5 owner/repo             # 5 pages in parallel

Recommended values:

  • 1-2: Avoid overwhelming the Claude API
  • 3-5: Balanced for most projects
  • 5+: Only for very stable networks and high API rate limits

Combined Parallelism

Combine both levels for maximum throughput:

./wikigen -f repos.txt -p 2 -pp 5      # 2 repos × 5 pages per repo = 10 concurrent generations

This processes 2 repositories in parallel, with 5 pages being generated per repository concurrently.

Sources: main.go:912-913, main.go:565-615

flowchart TD
    Start["Start: 4 repos"]
    P["Repository Parallelism: -p 2"]
    Start --> P

    P --> R1["Repo 1"]
    P --> R2["Repo 2"]

    R1 --> PP1["Page Parallelism: -pp 3"]
    R2 --> PP2["Page Parallelism: -pp 3"]

    PP1 --> P1A["Page 1"]
    PP1 --> P1B["Page 2"]
    PP1 --> P1C["Page 3"]

    PP2 --> P2A["Page 1"]
    PP2 --> P2B["Page 2"]
    PP2 --> P2C["Page 3"]

    P1A --> Done["Done: 2 repos<br/>processed in parallel"]
    P1B --> Done
    P1C --> Done
    P2A --> Done
    P2B --> Done
    P2C --> Done

    style P fill:#ff9800,color:#fff
    style PP1 fill:#2196F3,color:#fff
    style PP2 fill:#2196F3,color:#fff
Loading

Directory Configuration

wikigen uses two main directories: one for cloned repositories and one for generated wiki output.

Output Directory

The -o flag specifies where generated wiki files are written. Each project creates a subdirectory within this directory.

./wikigen -o ./wiki-output owner/repo    # Default
./wikigen -o /var/www/wikis owner/repo   # Custom absolute path
./wikigen -o ../output owner/repo         # Relative path

export WIKI_OUTPUT_DIR=/tmp/wikis && ./wikigen owner/repo

Output structure:

wiki-output/
  owner/repo/
    Home.md              # Landing page
    _Sidebar.md          # Navigation
    Page-1.md
    Page-2.md
    ...
    _errors.log          # Only if errors occurred

Default: ./wiki-output (relative to current working directory)

Clone Directory

The -clone-dir flag specifies where repositories are temporarily cloned during generation. Does not apply when using -local flag.

./wikigen -clone-dir ./.repos owner/repo       # Default (relative)
./wikigen -clone-dir /tmp/cloned-repos owner/repo  # Absolute path
./wikigen -clone-dir /mnt/fast-disk/repos owner/repo  # SSD location

export WIKI_CLONE_DIR=/var/cache/repos && ./wikigen owner/repo

Clone directory structure:

.repos/
  owner_repo/                # Cloned repository
    .git/
    src/
    docs/
    ...
  owner_repo2/               # Another cloned repo
    ...

Default: ./.repos (relative to current working directory)

Directory Configuration in CI/CD

For CI/CD pipelines, use absolute paths and ensure proper cleanup:

# GitHub Actions example
./wikigen -o /tmp/wiki-output \
          -clone-dir /tmp/repos \
          -f repos.txt

# Clean up after
rm -rf /tmp/wiki-output /tmp/repos

Sources: main.go:909-910, main.go:517-522

Authentication Configuration

wikigen supports two authentication methods for accessing GitHub repositories: SSH (default) and HTTPS with Personal Access Tokens.

SSH Authentication (Default)

SSH authentication is the default and requires no .env configuration beyond having SSH keys set up with GitHub.

When GITHUB_TOKEN is empty or unset, wikigen automatically converts HTTPS URLs to SSH:

# SSH authentication (default when GITHUB_TOKEN is unset)
./wikigen owner/repo

# Verify with:
cat .env | grep GITHUB_TOKEN
# Should be empty or commented out

SSH clone URL format: git@github.com:owner/repo.git

Sources: main.go:147-171

cloneURL := repoURL
if token != "" {
	// PAT specified — use HTTPS with token
	cloneURL = strings.Replace(repoURL, "https://", fmt.Sprintf("https://%s@", token), 1)
} else {
	// No PAT — use SSH
	cloneURL = strings.Replace(repoURL, "https://github.com/", "git@github.com:", 1)
	if !strings.HasSuffix(cloneURL, ".git") {
		cloneURL += ".git"
	}
}

Personal Access Token (PAT) Authentication

For environments without SSH setup (CI/CD, restricted networks), use GitHub Personal Access Tokens with HTTPS:

# Via CLI flag
./wikigen -token "ghp_xxxxxxxxxxxxxxxxxxxx" owner/repo

# Via .env file
echo "GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx" >> .env
./wikigen owner/repo

# Via environment variable
export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"
./wikigen owner/repo

HTTPS clone URL format: https://token@github.com/owner/repo.git

Sources: main.go:906

Token Generation

To generate a Personal Access Token:

  1. Visit GitHub Settings → Personal Access Tokens
  2. Click "Generate new token (classic)"
  3. Set scope: repo (full control of private repositories)
  4. Set expiration: 90 days (recommended)
  5. Copy token immediately (not shown again)
  6. Add to .env or environment variable

Token format: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Authentication Comparison

Aspect SSH PAT
Setup SSH key generation and GitHub registration One-time token generation
Expiration No expiration Configurable (default: no expiration)
Local development Recommended Optional
CI/CD Supported Recommended
Private repos ✓ ✓ (with repo scope)

Local Repository Mode

The -local flag allows wikigen to use a local directory instead of cloning from GitHub. This is useful for testing, offline scenarios, or non-GitHub repositories.

# Use local repository copy
./wikigen -local /path/to/repo myproject

# With dry-run for testing
./wikigen -local /path/to/repo -dry-run myproject

# Combined with other options
./wikigen -local /path/to/repo -lang en -model haiku myproject

When using -local:

  • The repository is not cloned (git clone is skipped)
  • The provided path is used directly as the source for analysis
  • The positional argument or -r flag specifies the project name for output organization
  • Other configuration options (language, model, parallelism) work normally

Sources: main.go:490-494, main.go:903

Practical Configuration Examples

Example 1: Simple Single Repository

Generate documentation for a single repository with default settings:

.env file:

GITHUB_TOKEN=
WIKI_LANGUAGE=en
CLAUDE_MODEL=haiku

Command:

./wikigen owner/repo

This uses SSH authentication (since GITHUB_TOKEN is empty), generates English documentation with the haiku model, and writes output to ./wiki-output/.

Example 2: Batch Processing with Parallelism

Process multiple repositories from a file with high parallelism:

.env file:

GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
CLAUDE_MODEL=sonnet
WIKI_LANGUAGE=en
WIKI_PARALLEL=2
WIKI_PAGE_PARALLEL=5
WIKI_OUTPUT_DIR=./wikis
WIKI_CLONE_DIR=/tmp/clones

repos.txt:

org/repo1
org/repo2
org/repo3
org/repo4

Command:

./wikigen -f repos.txt

This processes 2 repositories in parallel, generating 5 pages per repository concurrently, using Sonnet model for higher quality documentation.

Example 3: Multi-Repository Project

Generate a single integrated wiki for multiple related services:

.env file:

GITHUB_TOKEN=
WIKI_LANGUAGE=en
CLAUDE_MODEL=haiku
WIKI_PARALLEL=1
WIKI_PAGE_PARALLEL=3

repos.txt:

# Multi-repo project (uses project name as wiki name)
myapp:org/frontend
myapp:org/backend
myapp:org/shared-lib

Command:

./wikigen -f repos.txt

Output: ./wiki-output/myapp/ (single wiki containing all three repositories)

Example 4: CI/CD Pipeline

Configuration for GitHub Actions with secure token handling:

.env file:

# Leave empty — token comes from GitHub Actions secrets
GITHUB_TOKEN=
CLAUDE_MODEL=haiku
WIKI_LANGUAGE=en
WIKI_PARALLEL=1
WIKI_PAGE_PARALLEL=3
WIKI_OUTPUT_DIR=/tmp/wiki-output
WIKI_CLONE_DIR=/tmp/repos

.github/workflows/wiki.yml:

name: Generate Wiki

on:
  push:
    branches: [main]

jobs:
  wiki:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-go@v5
        with:
          go-version: '1.22'

      - name: Build wikigen
        run: go build -o wikigen .

      - name: Install Claude CLI
        run: npm install -g @anthropic-ai/claude-code

      - name: Generate wiki
        env:
          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: ./wikigen -lang en owner/repo

      - name: Push to wiki
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          git clone https://x-access-token:${GITHUB_TOKEN}@github.com/owner/repo.wiki.git wiki
          cp -r wiki-output/repo/* wiki/
          cd wiki
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add -A
          git diff --staged --quiet || (git commit -m "Update wiki" && git push)

Example 5: Testing with Local Repository

Test wiki generation against a local repository copy:

# Clone or copy repository locally
git clone https://github.com/owner/repo.git ./my-repo

# Generate wiki using local copy
./wikigen -local ./my-repo -dry-run myproject

# Once satisfied, generate full wiki
./wikigen -local ./my-repo -lang en myproject

Example 6: Development Machine with SSH

Standard development setup using SSH authentication and English output:

.env file:

# SSH authentication (no token)
GITHUB_TOKEN=

# Development settings
WIKI_LANGUAGE=en
CLAUDE_MODEL=sonnet
WIKI_PARALLEL=1
WIKI_PAGE_PARALLEL=3

# Keep clones for faster re-runs
WIKI_CLONE_DIR=./repos-cache
WIKI_OUTPUT_DIR=./wiki-output

Commands:

# Dry run to preview structure
./wikigen -dry-run owner/repo

# Generate wiki
./wikigen owner/repo

# Retry failed pages
./wikigen -retry

Example 7: JSON Output for Monitoring

Extract structured results for monitoring or integration:

./wikigen -json owner/repo 2>/dev/null | jq '.[0] | {project, total_pages, status, failed}'

# Output:
# {
#   "project": "repo",
#   "total_pages": 15,
#   "status": "completed",
#   "failed": 0
# }

This requires -json flag and stderr redirection to isolate JSON output.

Configuration Validation

wikigen validates all configuration values to prevent errors and security issues.

Repository Validation

All repository inputs (owner/repo format) are validated for security:

✓ Valid:       owner/repo, my-org/my-repo-1, user_name/project_2024
✗ Invalid:     owner (missing /repo)
✗ Invalid:     owner/../escape (path traversal)
✗ Invalid:     owner/repo; rm -rf / (shell injection)
✗ Invalid:     owner/repo|cat (pipe character)

Sources: main.go:79-92

Validation rules:

  • Must match owner/repo format with alphanumerics, dots, underscores, hyphens
  • No path traversal sequences (..)
  • No shell metacharacters: ;, &, |, `, $, (, ), {, }, [, ], !, ~

Default Configuration

When no configuration is provided, wikigen uses these hardcoded defaults:

Option Default Value
Language ja (Japanese)
Model (unset — Claude CLI default)
Output Directory ./wiki-output
Clone Directory ./.repos
Repository Parallelism 1
Page Parallelism 3
Authentication SSH (when GITHUB_TOKEN unset)
Claude Binary claude (from PATH)
Log Output stderr

Sources: main.go:692-715, main.go:882-914

Troubleshooting Configuration Issues

Issue: "GITHUB_TOKEN not recognized"

Cause: Environment variable format or precedence issue.

Solution: Verify configuration sources in order:

# Check CLI flag (highest priority)
./wikigen -token "ghp_xxxx" owner/repo

# Check environment variable
echo $GITHUB_TOKEN
export GITHUB_TOKEN="ghp_xxxx"
./wikigen owner/repo

# Check .env file
cat .env | grep GITHUB_TOKEN
# Should show: GITHUB_TOKEN=ghp_xxxx (not commented)

Issue: "Wrong language in output"

Cause: Configuration precedence issue or typo.

Solution:

# CLI flag takes precedence
./wikigen -lang en owner/repo  # Force English

# Check environment variable
export WIKI_LANGUAGE=en && ./wikigen owner/repo

# Check .env file
cat .env | grep WIKI_LANGUAGE
echo "WIKI_LANGUAGE=en" >> .env

Issue: "Parallelism settings not applied"

Cause: Invalid integer values or type issues.

Solution:

# Via CLI (most reliable)
./wikigen -p 2 -pp 5 owner/repo

# Via environment (must be valid integers)
export WIKI_PARALLEL=2
export WIKI_PAGE_PARALLEL=5
./wikigen owner/repo

# Via .env (ensure no quotes or spaces)
echo "WIKI_PARALLEL=2" >> .env
echo "WIKI_PAGE_PARALLEL=5" >> .env

Related Pages

Home

Clone this wiki locally