Installation Setup

Installation & Setup

wikigen is a single Go binary that generates GitHub Wiki documentation from source code using Claude Code. This page covers system prerequisites, step-by-step installation, environment configuration, authentication setup, and troubleshooting.

wikigen has minimal dependencies and requires no Docker, Ollama, embedding infrastructure, or additional services. A single binary, once built, can be deployed anywhere Go is supported.

Prerequisites

Before installing wikigen, ensure your system meets the following requirements:

Go Version

Go 1.22 or later — wikigen is built with Go 1.25.7

To verify your Go version:
```
go version
```
If you don't have Go installed, download it from golang.org.

Git

git (any recent version) — wikigen uses git clone to fetch source code
SSH key configured (if using SSH authentication) — required for private repositories
PAT (Personal Access Token) (optional) — alternative to SSH, required for environments without SSH key setup

To verify git is installed:
```
git --version
```

Claude CLI

Claude Code CLI installed and authenticated
Authentication test: Run claude -p "hello" — it should work without errors

If not installed, install from npm:
```
npm install -g @anthropic-ai/claude-code
```
Then authenticate:
```
claude login
```

Step-by-Step Installation

1. Clone the wikigen Repository

git clone https://github.com/tomohiro-owada/wikigen.git
cd wikigen

2. Copy the Example Environment File

cp .env.example .env

The .env file is optional but recommended for setting default configuration values. See the Environment Configuration section below.

3. Build the Binary

go build -o wikigen .

This creates a wikigen executable in the current directory.

Optional: Install globally to use wikigen from any directory:

go install .

This installs the binary to $GOPATH/bin/wikigen (typically ~/go/bin/wikigen).

4. Verify the Installation

./wikigen -h

This should display the command-line usage:

Usage of ./wikigen:
  -clone-dir string
        clone directory (default "./.repos")
  -f string
        file containing repo list (one per line)
  -lang string
        output language (default "ja")
  -local string
        use local directory instead of cloning (skip git clone)
  -log string
        log file path (default: stderr)
  -model string
        claude model (e.g., haiku, sonnet, opus)
  -o string
        output directory (default "./wiki-output")
  -p int
        parallel repos (default 1)
  -pp int
        parallel pages per repo (default 3)
  -r string
        comma-separated repo list (owner/repo or project:owner/repo)
  -retry
        retry only failed pages in existing wiki-output
  -token string
        GitHub PAT (default: $GITHUB_TOKEN, empty=SSH)

Environment Configuration

wikigen supports configuration via .env file and environment variables. CLI flags take precedence over environment variables, which take precedence over defaults.

.env File Format

The .env file is a plain-text configuration file with KEY=VALUE pairs. Comments start with #.

Location: .env or .env.local (both are supported; .env is loaded first)

Example .env file:

# GitHub Personal Access Token (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=ja

# Parallel repos (default: 1)
# WIKI_PARALLEL=2

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

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

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

Configuration Options Reference

Environment Variable	CLI Flag	Default	Description
`GITHUB_TOKEN`	`-token`	(empty)	GitHub Personal Access Token. If empty, SSH authentication is used.
`CLAUDE_MODEL`	`-model`	(empty)	Claude model to use for generation (e.g., `haiku`, `sonnet`, `opus`). If empty, uses the user's default model.
`WIKI_LANGUAGE`	`-lang`	`ja`	Output language. Supported: `en`, `ja`, `zh`, `zh-tw`, `es`, `kr`, `vi`, `pt-br`, `fr`, `ru`
`WIKI_OUTPUT_DIR`	`-o`	`./wiki-output`	Directory where generated wiki files are saved.
`WIKI_CLONE_DIR`	`-clone-dir`	`./.repos`	Temporary directory for cloning repositories.
`WIKI_PARALLEL`	`-p`	`1`	Number of repositories to process in parallel.
`WIKI_PAGE_PARALLEL`	`-pp`	`3`	Number of pages to generate in parallel per repository.

(Other flags like -f, -r, -retry, -dry-run, -json, -log, -local do not have environment variable equivalents.)

Configuration Precedence

Configuration is loaded in this order (highest to lowest priority):

CLI flags — Specified on the command line
Environment variables — Set in the shell environment or .env file
Defaults — Built-in defaults if neither CLI flag nor environment variable is set

Example: If you set WIKI_LANGUAGE=en in .env but run ./wikigen -lang ja owner/repo, the wiki will be generated in Japanese (CLI flag takes precedence).

Loading .env Files

wikigen automatically loads .env and .env.local files from the current working directory on startup.

.env is loaded first
.env.local is loaded second (overrides .env if keys conflict)
Environment variables already set in the shell take final precedence

This follows the standard dotenv convention.

Authentication Setup

wikigen supports two authentication methods for accessing private repositories: SSH (default) and PAT (GitHub Personal Access Token).

Method 1: SSH (Default)

Best for: Local development, environments with SSH key setup, personal machines

Prerequisites:

SSH key registered with your GitHub account
SSH key added to your SSH agent

Setup:

Generate an SSH key (if you don't have one):

ssh-keygen -t ed25519 -C "your-email@example.com"

Add the key to GitHub:
- Go to GitHub Settings → SSH and GPG Keys
- Click "New SSH key"
- Copy your public key (~/.ssh/id_ed25519.pub) and paste it
- Click "Add SSH key"

Add the key to your SSH agent:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

Test the connection:
```
ssh -T git@github.com
```
You should see: Hi username! You've successfully authenticated, but GitHub does not provide shell access.
Run wikigen without setting GITHUB_TOKEN:
```
./wikigen owner/repo
```

How it works (in code): When GITHUB_TOKEN is not set, wikigen converts the HTTPS clone URL to SSH format (lines 160-164 of main.go):

cloneURL = strings.Replace(repoURL, "https://github.com/", "git@github.com:", 1)

Method 2: PAT (GitHub Personal Access Token)

Best for: CI/CD pipelines, containerized environments, machines without SSH key setup

Prerequisites:

GitHub Personal Access Token with repo scope

Setup:

Generate a PAT:
- Go to GitHub Settings → Developer settings → Personal access tokens
- Click "Generate new token"
- Give it a name (e.g., wikigen-token)
- Select scopes: at minimum, check repo (full control of private repositories)
- Click "Generate token"
- Copy the token immediately — you won't see it again

Set the token in .env:

GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Or set as an environment variable:

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Run wikigen:
```
./wikigen owner/repo
```

How it works (in code): When GITHUB_TOKEN is set, wikigen injects it into the HTTPS clone URL (lines 156-158 of main.go):

cloneURL = strings.Replace(repoURL, "https://", fmt.Sprintf("https://%s@", token), 1)

Choosing Between SSH and PAT

Aspect	SSH	PAT
Setup complexity	Medium (key generation, GitHub upload)	Low (single token string)
Best for	Local development, personal machines	CI/CD, containers, shared machines
Security	Private key on local machine	Token can be revoked immediately
Token expiry	Never (key-based)	30 days to 1 year (configurable)
Revocation	Delete key from GitHub	One-click revocation in GitHub UI
Portability	Requires SSH key on each machine	Works from any machine with token

Quick Start Examples

Generate a Single Repository

./wikigen owner/repo

Output is saved to ./wiki-output/repo/

Generate Multiple Repositories in Parallel

./wikigen -f repos.txt -p 2 -pp 5

-f repos.txt: List of repositories to process
-p 2: Process 2 repositories in parallel
-pp 5: Generate up to 5 pages per repository in parallel

Preview Wiki Structure Without Generating Pages

./wikigen -dry-run owner/repo

This determines the wiki structure (decides which pages will be created) without generating actual page content. Useful for validating that wikigen correctly understands your repository before spending time on generation.

Retry Failed Pages

./wikigen -retry

Scans the existing ./wiki-output/ directory for pages that failed generation and regenerates only those pages, without re-processing all repositories.

Generate in English

./wikigen -lang en owner/repo

Default language is Japanese. See Configuration Options for supported languages.

Generate in Specific Directory

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

Troubleshooting

Issue: `claude: command not found`

Cause: Claude Code CLI is not installed or not in the PATH.

Solution:

npm install -g @anthropic-ai/claude-code
which claude  # Verify it's in PATH
claude -p "hello"  # Test authentication

If the issue persists, you can specify the path to the claude binary explicitly:

./wikigen -claude /path/to/claude owner/repo

Issue: `invalid repo format: "owner/repo" (expected owner/repo)`

Cause: The repository argument doesn't match the owner/repo format.

Solution:

Use the exact format: owner/repo (e.g., octocat/Hello-World)
For batch files (-f repos.txt), ensure each line is in the correct format
For comma-separated input (-r), use owner/repo1,owner/repo2

See Input Validation & Security for full validation rules.

Issue: `fatal: Authentication failed` or `Permission denied (publickey)`

Cause: Authentication failed — SSH key not set up, or PAT is invalid.

Solution for SSH:

# Test SSH connection
ssh -T git@github.com

# If that fails, add key to agent
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

# Verify key is registered on GitHub
# https://github.com/settings/keys

Solution for PAT:

# Verify token is set correctly
echo $GITHUB_TOKEN

# Test token with curl
curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user

# Regenerate token if expired:
# https://github.com/settings/tokens

Issue: `mkdir: permission denied` on output directory

Cause: The output directory path is not writable.

Solution:

# Use a writable directory
./wikigen -o ~/my-wiki-output owner/repo

# Or fix permissions on the current output directory
chmod 755 ./wiki-output

Issue: `Failed to read repos file` or `no such file or directory`

Cause: The -f file doesn't exist or isn't readable.

Solution:

# Verify the file exists
ls -la repos.txt

# Use absolute path if relative path doesn't work
./wikigen -f /absolute/path/to/repos.txt

Issue: Generated wiki is incomplete or has `_errors.log`

Cause: Some pages failed to generate.

Solution:

# Check error log
cat wiki-output/repo/_errors.log

# Retry failed pages
./wikigen -retry

# If retry fails, increase page parallel limit or try a different model:
./wikigen -retry -pp 2 -model haiku

Issue: Out of memory or slow generation on large repositories

Cause: Processing too many repositories/pages in parallel.

Solution:

# Reduce parallelism
./wikigen -p 1 -pp 2 owner/repo

# Or reduce Claude model to haiku (faster, lower memory)
./wikigen -model haiku owner/repo

Environment Variable Precedence (Detailed)

The .env loading mechanism respects shell environment variables — they are not overwritten by .env file values. This allows you to set sensitive values (like tokens) in the shell environment without committing them to .env.

Example:

.env contains: GITHUB_TOKEN=ghp_abc123
Shell has: export GITHUB_TOKEN=ghp_xyz789
wikigen will use: ghp_xyz789 (shell environment takes precedence)

This is implemented in loadEnvFile() (line 719 of main.go):

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

The function only sets the environment variable if it's not already set.

Validation & Security

wikigen validates all repository inputs to prevent security vulnerabilities.

Repository Format Validation

All repository inputs must match the format: owner/repo

Rejected patterns (source: line 79 of main.go):

validRepoPattern = regexp.MustCompile(`^[a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+$`)

✅ octocat/Hello-World
❌ octocat (missing /repo)
❌ owner/repo/extra (too many parts)
❌ owner/repo- (trailing hyphen in repo name)

Path Traversal Prevention

wikigen rejects repositories containing .. to prevent path traversal attacks (line 85 of main.go):

if strings.Contains(repo, "..") {
    return fmt.Errorf("path traversal detected in repo: %q", repo)
}

❌ owner/../other-owner/repo
❌ owner/../../tmp

Shell Injection Prevention

wikigen rejects repositories containing shell metacharacters (line 88 of main.go):

if strings.ContainsAny(repo, ";&|`$(){}[]!~") {
    return fmt.Errorf("invalid characters in repo: %q", repo)
}

❌ owner/repo; rm -rf /
❌ owner/$(command)repo
❌ owner/repo|other-command

For more information, see Input Validation & Security.

Next Steps

Once wikigen is installed and configured:

Generate your first wiki: ./wikigen owner/repo
Review the output: Check wiki-output/repo/ for generated .md files
Push to GitHub Wiki: See Output Format & Wiki Structure for push instructions
Set up automation: See GitHub Actions Integration to automatically regenerate on code changes

Related Pages

CLI Usage & Commands — Complete command reference and real-world examples
Configuration & Environment Variables — Detailed configuration reference
Repository Access & Authentication — SSH and PAT authentication details
Input Validation & Security — Security validation rules
Output Format & Wiki Structure — How to push generated wiki to GitHub
System Overview — Project purpose and architecture
Error Handling & Retry Mechanism — Error recovery strategies

Sources: wikigen/main.go:1-25, wikigen/main.go:79-92, wikigen/main.go:147-171, wikigen/main.go:719-739, wikigen/go.mod:3

Home

Installation Setup

Installation & Setup

Prerequisites

Go Version

Git

Claude CLI

Step-by-Step Installation

1. Clone the wikigen Repository

2. Copy the Example Environment File

3. Build the Binary

4. Verify the Installation

Environment Configuration

.env File Format

Configuration Options Reference

Configuration Precedence

Loading .env Files

Authentication Setup

Method 1: SSH (Default)

Method 2: PAT (GitHub Personal Access Token)

Choosing Between SSH and PAT

Quick Start Examples

Generate a Single Repository

Generate Multiple Repositories in Parallel

Preview Wiki Structure Without Generating Pages

Retry Failed Pages

Generate in English

Generate in Specific Directory

Troubleshooting

Issue: claude: command not found

Issue: invalid repo format: "owner/repo" (expected owner/repo)

Issue: fatal: Authentication failed or Permission denied (publickey)

Issue: mkdir: permission denied on output directory

Issue: Failed to read repos file or no such file or directory

Issue: Generated wiki is incomplete or has _errors.log

Issue: Out of memory or slow generation on large repositories

Environment Variable Precedence (Detailed)

Validation & Security

Repository Format Validation

Path Traversal Prevention

Shell Injection Prevention

Next Steps

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!

Issue: `claude: command not found`

Issue: `invalid repo format: "owner/repo" (expected owner/repo)`

Issue: `fatal: Authentication failed` or `Permission denied (publickey)`

Issue: `mkdir: permission denied` on output directory

Issue: `Failed to read repos file` or `no such file or directory`

Issue: Generated wiki is incomplete or has `_errors.log`