Configuration Environment

Configuration & Environment

wikigen supports flexible configuration through environment variables defined in .env files and command-line flags. CLI flags take absolute precedence, allowing temporary overrides without modifying configuration files. This page provides a complete reference for all configurable options, their defaults, and how they interact.

Configuration Loading Order

wikigen follows a three-tier configuration precedence system. When the program starts, it first loads .env files, then reads CLI flags, with each layer overriding the previous one.

flowchart TD
    A["Program Start"] --> B["loadEnvFile()"]
    B --> C[".env file loaded<br/>KEY=VALUE pairs"]
    C --> D[".env.local file loaded<br/>Overrides .env"]
    D --> E["System Environment<br/>Already set variables"]
    E --> F["CLI Flags Parsed<br/>flag.Parse()"]
    F --> G["CLI Flag Values<br/>Take final precedence"]
    G --> H["Runtime Configuration<br/>Ready for use"]

The loading sequence ensures that:

Default .env files provide baseline configuration
.env.local files allow local-specific overrides (typically in .gitignore)
System environment variables can be set by the shell or CI/CD
CLI flags provide run-time overrides for immediate needs

Sources: main.go:917,754-774

Environment File Format

wikigen loads environment variables from two optional files, in order:

.env — Standard configuration file (committed to version control)
.env.local — Local overrides (typically in .gitignore)

File Parsing Rules

Each file uses a simple key=value format:

# Comments start with #
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
CLAUDE_MODEL=haiku
WIKI_LANGUAGE=en

# Empty lines are ignored
WIKI_PARALLEL=2

Parsing behavior:

Lines starting with # are comments and are ignored
Empty lines are ignored
Leading and trailing whitespace around keys and values is trimmed
If an environment variable is already set in the shell, .env files will not override it (respecting shell-level precedence)

The parser iterates through each line, splits on the first = character, and uses strings.TrimSpace() to clean keys and values. If an environment variable is already defined in the system environment (os.Getenv(k) == ""), it skips setting it from the file.

Sources: main.go:754-774

Example .env File

A typical .env file configuration looks like this:

# GitHub PAT (optional — if empty, SSH is used)
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Claude model (optional: haiku, sonnet, opus)
CLAUDE_MODEL=haiku

# Output language (default: ja)
WIKI_LANGUAGE=en

# Parallel repos (default: 1)
WIKI_PARALLEL=2

# Parallel pages per repo (default: 3)
WIKI_PAGE_PARALLEL=5

# Output directory (default: ./wiki-output)
WIKI_OUTPUT_DIR=./wiki-output

# Clone directory (default: ./.repos)
WIKI_CLONE_DIR=./.repos

The .env.example file in the repository provides a template.

Sources: .env.example

Configuration Helper Functions

wikigen provides three helper functions that read environment variables and apply type conversion, with fallback defaults:

envOrDefault

Reads a string environment variable and returns a fallback if not set:

func envOrDefault(key, fallback string) string {
    if v := os.Getenv(key); v != "" {
        return v
    }
    return fallback
}

Used for string options like model selection and language.

envOrDefaultInt

Reads an integer environment variable, validates it, and returns a fallback if not set or invalid:

func envOrDefaultInt(key string, fallback int) int {
    if v := os.Getenv(key); v != "" {
        var i int
        fmt.Sscan(v, &i)
        if i > 0 {
            return i
        }
    }
    return fallback
}

Used for numeric options like parallelism flags. Values must be greater than 0, otherwise the fallback is used.

envOrDefaultBool

Reads a boolean environment variable with flexible value matching:

func envOrDefaultBool(key string, fallback bool) bool {
    if v := os.Getenv(key); v != "" {
        return v == "true" || v == "1" || v == "yes"
    }
    return fallback
}

Accepts "true", "1", or "yes" as truthy values. Any other non-empty value is treated as falsy.

Sources: main.go:729-752

Configuration Reference

All configurable options, their environment variables, defaults, and descriptions:

CLI Flag	Environment Variable	Default	Description
`-f`	—	—	File path containing repository list (one per line)
`-r`	—	—	Comma-separated repository list (e.g., `owner/repo1,owner/repo2`)
`-local`	—	—	Use local directory instead of cloning (skips git operations)
`-token`	`GITHUB_TOKEN`	(empty → use SSH)	GitHub Personal Access Token for HTTPS authentication
`-model`	`CLAUDE_MODEL`	(empty)	Claude model name (e.g., `haiku`, `sonnet`, `opus`)
`-lang`	`WIKI_LANGUAGE`	`ja`	Output language (e.g., `ja`, `en`)
`-o`	`WIKI_OUTPUT_DIR`	`./wiki-output`	Output directory for generated wiki
`-clone-dir`	`WIKI_CLONE_DIR`	`./.repos`	Directory where repositories are cloned
`-p`	`WIKI_PARALLEL`	`1`	Number of repositories to process in parallel
`-pp`	`WIKI_PAGE_PARALLEL`	`3`	Number of pages per repository to generate in parallel
`-claude`	—	`claude`	Path to the `claude` CLI binary
`-log`	—	(stderr)	Log file path; if empty, logs go to standard error
`-retry`	—	`false`	Retry only failed pages in existing wiki-output
`-dry-run`	—	`false`	Determine structure only; do not generate page content
`-json`	—	`false`	Output results as JSON to stdout

Notes on Specific Options

GITHUB_TOKEN — If this environment variable or -token flag is not set, wikigen uses SSH authentication via your local git SSH key configuration. SSH is the default authentication method.

CLAUDE_MODEL — If not specified, the default Claude model configured in your Claude Code installation is used. Common values are haiku, sonnet, and opus.

WIKI_LANGUAGE — Defaults to Japanese (ja). Set to en for English or other language codes as needed.

WIKI_PARALLEL — Number of repositories processed concurrently. Default is 1 (sequential). Increasing this improves throughput but uses more memory.

WIKI_PAGE_PARALLEL — Number of pages generated in parallel within each repository. Default is 3. Does not apply when -dry-run is used.

WIKI_CLONE_DIR — Repositories are cloned into this directory. Each repository gets a subdirectory based on the repository name. See Authentication & Git Integration for details.

Sources: main.go:937-951

CLI Flags Override Environment Variables

When a configuration option has both a CLI flag and an environment variable, the CLI flag always takes precedence. This allows for ad-hoc overrides:

# .env has WIKI_OUTPUT_DIR=./wiki-output
# But this invocation uses a different output dir:
./wikigen -o /tmp/wiki-output owner/repo

# .env has CLAUDE_MODEL=haiku
# But this invocation uses sonnet:
./wikigen -model sonnet owner/repo

This precedence is enforced by Go's flag package, which sets default values from environment variables but allows CLI arguments to override those defaults during flag.Parse().

Sources: main.go:937-951

Environment Variable Precedence

Environment variables set in the shell or CI/CD system take precedence over values defined in .env files. The loadEnvFile() function only calls os.Setenv() if the variable is not already set:

if os.Getenv(k) == "" {
    os.Setenv(k, v)
}

This allows CI/CD pipelines to set variables at runtime without needing to modify .env files:

export WIKI_PARALLEL=8
export CLAUDE_MODEL=opus
./wikigen -f repos.txt

Sources: main.go:768-770

Complete Configuration Priority Order

From lowest to highest precedence:

Hard-coded defaults — Built into the program (e.g., ./wiki-output)
.env file — Committed project configuration
.env.local file — Local machine overrides
Shell environment variables — Set by export or CI/CD
CLI flags — Command-line arguments (highest precedence)

Example showing all layers:

# .env defines:
# WIKI_PARALLEL=2
# WIKI_OUTPUT_DIR=./wiki-output

# .env.local defines:
# WIKI_OUTPUT_DIR=/data/wiki

# Shell has:
export WIKI_PARALLEL=4

# Command:
./wikigen -p 8 -lang en owner/repo

# Result:
# - WIKI_PARALLEL = 8 (from CLI flag)
# - WIKI_OUTPUT_DIR = /data/wiki (from .env.local)
# - WIKI_LANGUAGE = en (from CLI flag)

Positional Arguments and File Input

In addition to configuration options, wikigen accepts repository inputs in multiple ways:

Command-Line Positional Arguments

Repositories can be passed as positional arguments:

./wikigen owner/repo1 owner/repo2 owner/repo3

This is internally converted to a comma-separated list and assigned to the -r option. If -r is already set, positional arguments are ignored.

Sources: main.go:954-959

Repository List File (`-f` flag)

Specify a file containing one repository per line:

./wikigen -f repos.txt

See Input Formats & Repository Configuration for detailed format specification and multi-repository wiki support.

Local Directory Support

The -local flag allows wikigen to work with a local directory instead of cloning:

./wikigen -local /path/to/repo -o output

When -local is set, positional arguments are treated as project names rather than repository specifications, and no git cloning occurs.

Sources: main.go:955-956

Logging Configuration

Log File Output

By default, wikigen logs to standard error. Redirect logs to a file using -log:

./wikigen -log build.log -f repos.txt

The log file is opened in append mode (os.O_APPEND), allowing multiple runs to accumulate logs.

Error Logging

In addition to the console log file, wikigen writes generation errors to _errors.log in each project's output directory. This file contains timestamped error messages from failed page generations.

See Error Handling & Retry Mechanism for details on error logging and the retry mechanism.

Sources: main.go:962-969

Configuration in CI/CD

When running wikigen in GitHub Actions or other CI/CD systems, use environment variables to configure the build:

env:
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  CLAUDE_MODEL: haiku
  WIKI_LANGUAGE: en
  WIKI_PARALLEL: 4

CLI flags can override these for specific runs:

- name: Generate wiki
  run: ./wikigen -p 4 -pp 5 -lang en -f repos.txt

See Build & Deployment for a complete GitHub Actions example.

Configuration Validation

wikigen validates configuration during startup:

Integer values must be greater than 0 or the fallback is used
Boolean values are true if set to "true", "1", or "yes"
Repository inputs are validated against the owner/repo format
Paths are converted to absolute paths using filepath.Abs()

See Input Validation & Security for repository format validation rules.

Practical Configuration Examples

Example 1: Basic Configuration

Minimal setup for testing:

cp .env.example .env
# Edit .env with your GitHub token if needed
./wikigen owner/repo

Example 2: Batch Processing with Parallelism

Process multiple repositories with high parallelism:

export WIKI_PARALLEL=4
export WIKI_PAGE_PARALLEL=5
export CLAUDE_MODEL=sonnet
./wikigen -f repos.txt -lang en

Example 3: Dry Run for Structure Preview

Preview the wiki structure without generating page content:

./wikigen -dry-run -f repos.txt

Example 4: Local Directory with Custom Output

Generate wiki for a local repository with custom output directory:

./wikigen -local /home/user/my-repo -o /tmp/wiki-output

Example 5: Retry Failed Pages

Regenerate only failed pages from a previous run:

./wikigen -retry -model opus

Example 6: JSON Output for Scripting

Get structured output for automated processing:

./wikigen -json -f repos.txt | jq '.[] | select(.status == "failed")'

Configuration Reset

wikigen has no persistent configuration state. To reset to defaults:

Delete or rename .env.local
Use CLI flags to override specific options
Omit environment variables from the shell

All configuration is applied fresh on each program invocation.

Related Pages

CLI Usage & Commands — Complete reference for CLI flags and usage patterns
Input Formats & Repository Configuration — repos.txt format and repository input specifications
Authentication & Git Integration — SSH vs. PAT authentication setup and git configuration
Build & Deployment — Building wikigen from source and GitHub Actions integration
Error Handling & Retry Mechanism — Error logging and retry configuration
Parallel Processing & Performance — Parallelism flag tuning and performance optimization

Home

Configuration Environment

Configuration & Environment

Configuration Loading Order

Environment File Format

File Parsing Rules

Example .env File

Configuration Helper Functions

envOrDefault

envOrDefaultInt

envOrDefaultBool

Configuration Reference

Notes on Specific Options

CLI Flags Override Environment Variables

Environment Variable Precedence

Complete Configuration Priority Order

Positional Arguments and File Input

Command-Line Positional Arguments

Repository List File (-f flag)

Local Directory Support

Logging Configuration

Log File Output

Error Logging

Configuration in CI/CD

Configuration Validation

Practical Configuration Examples

Example 1: Basic Configuration

Example 2: Batch Processing with Parallelism

Example 3: Dry Run for Structure Preview

Example 4: Local Directory with Custom Output

Example 5: Retry Failed Pages

Example 6: JSON Output for Scripting

Configuration Reset

Related Pages

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Repository List File (`-f` flag)