DEV Community

TechLatest
TechLatest

Posted on • Originally published at Medium on

How to Automatically Document Your Repository with OpenWiki

#opensource #openwiki #agents #langchain

OpenWiki is a CLI that writes and maintains agent documentation for your codebase and can keep it fresh by opening PRs from CI.

Reference: langchain-ai/openwiki

What you’ll have at the end

  • OpenWiki installed and verified
  • A generated openwiki/ folder in a sample repository
  • A local update workflow: openwiki --update
  • A CI path to keep docs updated automatically (PR-based)

Part 1 — Install OpenWiki

Prerequisites

Node.js 18+: OpenWiki is a Node CLI

Git: Docs generation is repo-aware

An LLM provider key: Stored locally by OpenWiki (see below)

Install (global) 

npm install -g openwiki
Enter fullscreen mode Exit fullscreen mode

Verify 

openwiki --help
Enter fullscreen mode Exit fullscreen mode 


Expected output (v0.0.1):

  _____ ___ _ _ 
 / _ \ _ _____ _ __ \ \ / (_) | _(_)
| | | | '_ \ / _ \ '_ \ \ \ /\ / /| | |/ / |
| |_| | |_) | __/ | | | \ V V / | | <| |
 \ ___/| .__ / \___|_| |_| \_/\_/ |_|_|\_\_|
      |_|

╭─────────────────────────────────────────────────────────────────────────────╮
│ >_ OpenWiki v0.0.1 agent docs for codebases │
│ provider: OpenRouter │
│ model: z-ai/glm-5.2 │
│ directory: …/agentic-ai-ecosystem/guides/openwiki │
╰─────────────────────────────────────────────────────────────────────────────╯

# Usage
   openwiki [--modelId <model>]
   openwiki [--modelId <model>] [message]
   openwiki --init [message]
   openwiki --update [message]

# Options
    --init Generate initial OpenWiki documentation.
    --update Update existing OpenWiki documentation.
    -p, --print Run once and print the final assistant output.
    --modelId <id> Use a model ID for this run.
Enter fullscreen mode Exit fullscreen mode

Your provider and model come from ~/.openwiki/.env (configured on first interactive run).

Part 2 — Understand the core commands

OpenWiki usage patterns from upstream README:

  • Interactive : openwiki
  • Start with a request : openwiki "Please generate documentation for this repository"
  • One-shot print : openwiki -p "Summarize what you can do"
  • Initialize : openwiki --init
  • Update existing docs : openwiki --update

Part 3 — Configure provider & credentials

OpenWiki reads provider settings from ~/.openwiki/.env. For non-interactive commands (-p, --init, --update), Credentials must also be exported in your shell  — OpenWiki will not prompt you.

This guide uses local Ollama as the primary path ($0, no rate limits). OpenRouter (cloud) is documented as an alternative.

Option A — Local Ollama with qwen2.5:1.5b

OpenWiki v0.0.1 does not yet ship the openai-compatible Provider from the upstream README. Use the built-in openai provider and point it at Ollama’s OpenAI-compatible API on localhost:11434.

Step 3.1 — Verify Ollama is running 

ollama list
Enter fullscreen mode Exit fullscreen mode

Expected output:

NAME ID SIZE MODIFIED
qwen2.5:1.5b 65ec06548149 986 MB …
Enter fullscreen mode Exit fullscreen mode

If Ollama is not installed, see Ollama Small Models.

Pull the model if missing:

ollama pull qwen2.5:1.5b
Enter fullscreen mode Exit fullscreen mode

Step 3.2 — Write ~/.openwiki/.env

Important: remove any OPENROUTER_API_KEY line from this file. If it’s present, OpenWiki v0.0.1 keeps routing to OpenRouter even when you set another provider.

mkdir -p ~/.openwiki

cat > ~/.openwiki/.env <<'EOF'
OPENWIKI_PROVIDER=openai
OPENAI_API_KEY=ollama
OPENWIKI_MODEL_ID=qwen2.5:1.5b
EOF

chmod 600 ~/.openwiki/.env
Enter fullscreen mode Exit fullscreen mode

Step 3.3 — Export Ollama base URL (required every session)

OPENAI_BASE_URL is not loaded from ~/.openwiki/.env in v0.0.1 (it’s on OpenWiki’s deprecated key list). Export it in your shell:

export OPENAI_BASE_URL=http://localhost:11434/v1
set -a && source ~/.openwiki/.env && set +a
Enter fullscreen mode Exit fullscreen mode

Step 3.4 — Test print mode 

cd guides/openwiki
openwiki -p "Summarize what OpenWiki can do"
Enter fullscreen mode Exit fullscreen mode

Example output (connection verified on qwen2.5:1.5b):

OpenWiki is designed to provide information based on structured data from various
online sources, including Wikipedia. It aims to retrieve specific facts and statistics
about different topics efficiently…
Enter fullscreen mode Exit fullscreen mode

Quality note: A 1.5B model may hallucinate on OpenWiki’s large agent prompt (~46 KB + 9 tools). The test above proves Ollama → OpenWiki → response works. For --init doc generation, consider ollama pull llama3.2:3b if output quality is weak.

Option B — OpenRouter

Use OpenRouter if you prefer cloud models or don’t have Ollama installed.

Step 3.6 — Create OpenRouter API key

Step 3.7 — Write ~/.openwiki/.env for OpenRouter 

cat > ~/.openwiki/.env <<'EOF'
OPENWIKI_PROVIDER=openrouter
OPENROUTER_API_KEY=your-key-here
OPENWIKI_MODEL_ID=meta-llama/llama-3.2-3b-instruct:free
EOF

chmod 600 ~/.openwiki/.env
Enter fullscreen mode Exit fullscreen mode

Step 3.8 — Export and test 

set -a && source ~/.openwiki/.env && set +a
openwiki -p "Summarize what OpenWiki can do"
Enter fullscreen mode Exit fullscreen mode

If you skip exporting credentials, you will see:

OPENROUTER_API_KEY is required for non-interactive runs. Run openwiki in an interactive terminal to save credentials.
Enter fullscreen mode Exit fullscreen mode

Fix paths:

OpenRouter free models (no token cost)

Append :free to any model that offers a free tier:

List all free models:

curl -s https://openrouter.ai/api/v1/models \
  | python3 -c "
import json,sys
for m in json.load(sys.stdin)['data']:
    p=m.get('pricing') or {}
    if p.get('prompt')=='0' and p.get('completion')=='0':
        print(m['id'])
"
Enter fullscreen mode Exit fullscreen mode

Per-run model override:

openwiki -p --modelId meta-llama/llama-3.2-3b-instruct:free "Summarize what OpenWiki can do"
Enter fullscreen mode Exit fullscreen mode

Diagnose OpenRouter issues 

source ~/.openwiki/.env

# Account limits
curl -s [https://openrouter.ai/api/v1/key](https://openrouter.ai/api/v1/key) \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" | python3 -m json.tool

# Tiny free-model test
curl -s [https://openrouter.ai/api/v1/chat/completions](https://openrouter.ai/api/v1/chat/completions) \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"meta-llama/llama-3.2-3b-instruct:free","messages":[{"role":"user","content":"hi"}]}' \
  | python3 -m json.tool
Enter fullscreen mode Exit fullscreen mode

Provider comparison (this guide)

Part 4 — One-shot print mode (-p)

Print mode runs one request and exits — ideal for scripts, smoke tests, and CI logs.

After completing Part 3 (Ollama or OpenRouter), every non-interactive run needs:

# Ollama path — export base URL every session
export OPENAI_BASE_URL=http://localhost:11434/v1
set -a && source ~/.openwiki/.env && set +a

# OpenRouter path — source env only
# set -a && source ~/.openwiki/.env && set +a
Enter fullscreen mode Exit fullscreen mode

Then:

cd guides/openwiki
openwiki -p "Summarize what OpenWiki can do"
Enter fullscreen mode Exit fullscreen mode

Other useful print-mode prompts:

openwiki -p "Please generate documentation for this repository"
openwiki -p --modelId qwen2.5:1.5b "List the main folders in this repo"
Enter fullscreen mode Exit fullscreen mode

Part 5 — Initialize a repo (--init)

Run this inside a repo you want to document. Export Ollama env first if using Part 3 → Option A :

export OPENAI_BASE_URL=http://localhost:11434/v1
set -a && source ~/.openwiki/.env && set +a

cd guides/openwiki
openwiki --init
Enter fullscreen mode Exit fullscreen mode

Or with a starting message:

openwiki --init "Please generate documentation for this repository"
Enter fullscreen mode Exit fullscreen mode

What --init does (from upstream README):

  • Creates initial docs under openwiki/ if no wiki exists
  • Configures provider + model + API key on first run (saved to ~/.openwiki/.env)
  • May append prompting to AGENTS.md and/or CLAUDE.md to help coding agents reference the docs

Part 6 — Generate docs for a repo

From the repo root:

openwiki "Please generate documentation for this repository"
Enter fullscreen mode Exit fullscreen mode

If you want a one-shot output that exits (good for CI logs), use print mode:

openwiki -p "Please generate documentation for this repository"
Enter fullscreen mode Exit fullscreen mode

Part 7 — Update docs after changes (--update)

After you change the code, rerun:

openwiki --update
Enter fullscreen mode Exit fullscreen mode

Update — verified recording

Part 8 — CI: keep docs updated via PRs

OpenWiki’s recommended approach is to run updates in CI and open a PR when docs drift.

From upstream README:

  • GitHub Actions: copy openwiki-update.yml into .github/workflows/openwiki-update.yml
  • GitLab CI: copy openwiki-update.gitlab-ci.yml into your pipeline

In this repo, we’ll keep the CI snippet inside the guide and only add it to a real project when you’re ready.

Part 9 — Provider configuration (reference)

OpenWiki supports multiple providers out of the box (from upstream README):

  • OpenRouter
  • Fireworks
  • Baseten
  • OpenAI
  • OpenAI-compatible endpoint (e.g. a LiteLLM gateway)
  • Anthropic

OpenWiki saves provider configuration and secrets to ~/.openwiki/.env. For non-interactive commands (-p, --init, --update in CI), export them first:

set -a && source ~/.openwiki/.env && set +a
Enter fullscreen mode Exit fullscreen mode

OpenRouter 

OPENWIKI_PROVIDER=openrouter
OPENROUTER_API_KEY=your-key
OPENWIKI_MODEL_ID=meta-llama/llama-3.2-3b-instruct:free
Enter fullscreen mode Exit fullscreen mode

List free models on your machine:

curl -s https://openrouter.ai/api/v1/models \
  | python3 -c "
import json,sys
for m in json.load(sys.stdin)['data']:
    p=m.get('pricing') or {}
    if p.get('prompt')=='0' and p.get('completion')=='0':
        print(m['id'])
"
Enter fullscreen mode Exit fullscreen mode

Per-run override:

openwiki -p --modelId meta-llama/llama-3.2-3b-instruct:free "Summarize what OpenWiki can do"
Enter fullscreen mode Exit fullscreen mode

Anthropic-compatible gateway 

OPENWIKI_PROVIDER=anthropic
ANTHROPIC_API_KEY=your-key
ANTHROPIC_BASE_URL=https://your-gateway.example.com/anthropic
Enter fullscreen mode Exit fullscreen mode

Local Ollama (qwen2.5:1.5b)

Full step-by-step setup is in Part 3 → Option A. Summary:

OPENWIKI_PROVIDER=openai
OPENAI_API_KEY=ollama
OPENWIKI_MODEL_ID=qwen2.5:1.5b
# + export OPENAI_BASE_URL=http://localhost:11434/v1 in shell
Enter fullscreen mode Exit fullscreen mode

See also: Ollama Small Models

OpenAI-compatible gateway (future / upstream README)

The upstream README documents OPENWIKI_PROVIDER=openai-compatible — not in npm v0.0.1 yet. Use the Ollama + openai provider workaround in Part 3 until a newer release adds it.

Part 10 — Troubleshooting

Insufficient credits (402) on a :free model

Three common causes:

  • Negative account balance  — OpenRouter blocks all requests (even free) if the balance < 0. Fix: openrouter.ai/settings/credits → add credits until the balance is positive.
  • Prompt too large for free tier  — OpenWiki’s agent sends ~46 KB + 9 tools. Free accounts may reject this with a 402. Fix: use local Ollama (Part 3 → Option A) or add OpenRouter credits.
  • Paid model by mistake  — e.g. z-ai/glm-5.2 without :free. Fix: OPENWIKI_MODEL_ID=meta-llama/llama-3.2-3b-instruct:free

Diagnose your key + free model (small request) 

source ~/.openwiki/.env

# Account limits / balance
curl -s [https://openrouter.ai/api/v1/key](https://openrouter.ai/api/v1/key) \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" | python3 -m json.tool

# Tiny free-model test (should work if account is healthy)
curl -s [https://openrouter.ai/api/v1/chat/completions](https://openrouter.ai/api/v1/chat/completions) \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"meta-llama/llama-3.2-3b-instruct:free","messages":[{"role":"user","content":"hi"}]}' \
  | python3 -m json.tool
Enter fullscreen mode Exit fullscreen mode

If the curl test works but openwiki -p fails , the issue is OpenWiki’s large tool payload — switch to Ollama.

Insufficient credits (402 Payment Required) — paid model

You picked a paid model (e.g. z-ai/glm-5.2). Switch to a free model:

# In ~/.openwiki/.env — small free model (3B)
OPENWIKI_MODEL_ID=meta-llama/llama-3.2-3b-instruct:free
Enter fullscreen mode Exit fullscreen mode

Then re-export and retry:

set -a && source ~/.openwiki/.env && set +a
openwiki -p "Summarize what OpenWiki can do"
Enter fullscreen mode Exit fullscreen mode

OPENROUTER_API_KEY is required for non-interactive runs

You ran openwiki -p … Without exporting credentials. Either:

  1. Run openwiki interactively once to create ~/.openwiki/.env, then set -a && source ~/.openwiki/.env && set +a, or
  2. Pass OPENROUTER_API_KEY=… Inline for that command.

command not found: openwiki

  • Re-run npm install -g openwiki
  • Confirm your npm global bin is on PATH

Provider/API key prompts keep reappearing

  • Ensure ~/.openwiki/.env exists and is writable
  • Confirm you’re running the same user account in the terminal

Docs look stale

  • Re-run openwiki --update
  • Ensure you’re in the repo root (OpenWiki is repo-context aware)

Conclusion

OpenWiki makes it easy to generate and maintain documentation that evolves alongside your codebase. Instead of spending hours writing architecture notes, onboarding guides, and repository documentation manually, you can let OpenWiki analyze your project, generate an initial knowledge base, and keep it up to date as your code changes.

In this guide, you learned how to install OpenWiki, configure it with either a local Ollama model or OpenRouter, generate documentation for a repository, update existing docs, and automate the entire workflow using CI. Whether you’re documenting an open-source project, an internal developer platform, or a production application, OpenWiki helps ensure your documentation stays accurate without becoming another maintenance burden.

For the best experience, local Ollama provides a cost-free solution with unlimited usage, while OpenRouter gives you access to a wide range of cloud models when you need higher-quality outputs. Once your setup is complete, a simple openwiki --update after major code changes—or an automated CI workflow—can keep your documentation synchronized with your repository.

As AI-powered development becomes more common, keeping documentation current is just as important as writing good code. OpenWiki brings that process into your development workflow, making high-quality, always-updated documentation something your team can rely on rather than postpone.

Thank you so much for reading

Like | Follow | Subscribe to the newsletter.

Catch us on

Website: https://www.techlatest.net/

Newsletter: https://substack.com/@parvezmohammed

Twitter: https://twitter.com/TechlatestNet

LinkedIn: https://www.linkedin.com/in/techlatest-net/

YouTube:https://www.youtube.com/@techlatest_net/

Blogs: https://medium.com/@techlatest.net

Reddit Community: https://www.reddit.com/user/techlatest_net/

Top comments (0)