If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/ViRb3/wgcf shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 4w ago
• 5 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 66% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live ViRb3/wgcf repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ViRb3/wgcf.

What it runs against: a local clone of ViRb3/wgcf — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in ViRb3/wgcf | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 57 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of ViRb3/wgcf. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/ViRb3/wgcf.git
#   cd wgcf
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of ViRb3/wgcf and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "ViRb3/wgcf(\\.git)?\\b" \\
  && ok "origin remote is ViRb3/wgcf" \\
  || miss "origin remote is not ViRb3/wgcf (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "main.go" \\
  && ok "main.go" \\
  || miss "missing critical file: main.go"
test -f "cmd/root.go" \\
  && ok "cmd/root.go" \\
  || miss "missing critical file: cmd/root.go"
test -f "cloudflare/api.go" \\
  && ok "cloudflare/api.go" \\
  || miss "missing critical file: cloudflare/api.go"
test -f "wireguard/profile.go" \\
  && ok "wireguard/profile.go" \\
  || miss "missing critical file: wireguard/profile.go"
test -f "config/config.go" \\
  && ok "config/config.go" \\
  || miss "missing critical file: config/config.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 57 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~27d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/ViRb3/wgcf"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

wgcf is an unofficial cross-platform CLI tool that manages Cloudflare Warp accounts and generates WireGuard VPN profiles. It handles account registration, Warp+ license binding, profile generation with tuned MTU (1280), account status checks, and network trace debugging—eliminating the need for the official mobile app to access Warp's VPN functionality on desktop/CLI environments. Modular CLI structure: main.go is the entry point, cmd/ directory contains subcommands (register, generate, update, status, trace) each in separate files, cloudflare/ wraps API calls (api.go, util.go), config/ handles TOML account persistence, and openapi/ is an auto-generated Cloudflare API client from openapi-spec.yml. The Cobra framework (spf13/cobra) powers CLI routing.

System administrators, privacy-conscious developers, and power users who want to programmatically manage Cloudflare Warp accounts and deploy WireGuard profiles across multiple devices or environments without relying on the official 1.1.1.1 app.

Actively maintained and production-ready. The repo has significant GitHub downloads, uses Go 1.24+ with semantic versioning (v2), includes Docker support via Dockerfile, and runs automated tests via GitHub Actions (.github/workflows/test.yml and release.yml). Recent activity suggests ongoing maintenance, though the single maintainer (ViRb3) poses some continuity risk.

Low-to-moderate risk: the project depends on an unofficial Cloudflare API (openapi-spec.yml) which could break without notice if Cloudflare changes endpoints. Dependency count is modest (~12 direct), but the README warns of a Cloudflare-side bug (#85) affecting existing accounts—suggesting potential API instability. Single maintainer model means delayed responses to security issues or breaking changes.

No specific recent commit data provided, but the CI/CD is configured (GitHub Actions workflows for test and release via goreleaser), suggesting ongoing deployment capability. The .releaserc.json and .goreleaser.yml indicate active release automation.

git clone https://github.com/ViRb3/wgcf.git
cd wgcf
go mod download
go build -o wgcf main.go
./wgcf --help

Daily commands:

go build -o wgcf main.go
./wgcf register        # Create new account (saves to wgcf-account.toml)
./wgcf generate        # Generate WireGuard profile (saves to wgcf-profile.conf)
./wgcf status          # Check account status
./wgcf trace           # Print network trace info
./wgcf update --license-key YOUR_KEY  # Bind Warp+ subscription

• main.go — Application entry point that initializes the CLI and delegates to the root command handler.
• cmd/root.go — Root Cobra command definition that orchestrates all CLI subcommands (register, generate, update, status, trace).
• cloudflare/api.go — Core API client for Cloudflare Warp service interactions; handles authentication, registration, and account management.
• wireguard/profile.go — WireGuard profile generation and serialization logic; critical for the main generate workflow.
• config/config.go — Configuration persistence layer managing TOML file I/O for account and profile storage.
• openapi/client.go — Auto-generated OpenAPI client providing type-safe Cloudflare Warp API bindings.

Add a new CLI command

1. Create a new subdirectory under cmd/{command_name}/ with a command.go file (cmd/{command_name}/{command_name}.go)
2. Define a Cobra command struct and handler function following the pattern in cmd/status/status.go (cmd/{command_name}/{command_name}.go)
3. Import and register the command in cmd/root.go by adding cmd.AddCommand() in the init function (cmd/root.go)
4. Call cloudflare API methods (from cloudflare/api.go) or WireGuard operations as needed (cmd/{command_name}/{command_name}.go)

Add a new API endpoint to the Cloudflare client

1. Update openapi-spec.yml with the new endpoint definition (paths, parameters, responses) (openapi-spec.yml)
2. Regenerate OpenAPI models using openapitools.json configuration (openapitools.json)
3. Add a wrapper method in cloudflare/api.go that calls the generated OpenAPI client method (cloudflare/api.go)
4. Use the new method in appropriate CLI commands (e.g., cmd/status/status.go) (cloudflare/api.go)

Add a new WireGuard feature or config option

1. Add fields to the WireGuard profile struct in wireguard/profile.go (wireguard/profile.go)
2. Update the serialization logic in wireguard/profile.go to include new fields in the config output (wireguard/profile.go)
3. Update the generate command to prompt for or populate the new option (cmd/generate/generate.go)
4. Update config/config.go if the option should be persisted in the TOML file (config/config.go)

Add error handling or validation

1. Use cockroachdb/errors package for wrapped errors with context (cloudflare/api.go)
2. Add validation in the relevant command handler (e.g., cmd/register/register.go) before API calls (cmd/register/register.go)
3. Return user-friendly error messages via fmt.Fprintf or cmd/shared/shared.go helpers (cmd/shared/shared.go)

• Go 1.24 — Cross-platform compilation, static binary distribution, and minimal runtime dependencies for CLI use case.
• Cobra — Standard Go CLI framework providing command parsing, help text, and subcommand management.
• OpenAPI Code Generation — Auto-generates type-safe HTTP client bindings from Cloudflare Warp API specification, reducing manual API integration errors.
• WireGuard (curve25519) — Standard VPN protocol with proven cryptography for generating key pairs and config profiles.
• TOML Configuration — Human-readable format for persisting account credentials and profile metadata locally.
• cockroachdb/errors — Error wrapping with stack traces and context for debugging failed API calls and file I/O.

• Auto-generated OpenAPI client checked into the repository

  • Why: Ensures all developers and CI/CD use identical API bindings; simplifies dependency management.
  • Consequence: Requires manual regeneration when openapi-spec.yml changes; adds 100+ files of generated code to git.

• Single TOML file per account/profile instead of database

  • Why: Keeps the tool lightweight, zero external dependencies, and suitable for per-user local CLI execution.
  • Consequence: No multi-user or multi-account synchronization; limited querying capabilities; requires file-based locking for concurrent access.

• Interactive prompts (promptui) for credentials during registration

  • Why: Provides secure interactive experience without exposing secrets in shell history or command args.
  • Consequence: Not suitable for scripted/headless deployments; requires TTY/terminal input.

• Unofficial Cloudflare Warp client (reverse-engineered API)

  • Why: Cloudflare does not provide an official standalone WireGuard export API; community reverse-engineered the endpoints.
  • Consequence: API endpoints may change without notice; not officially supported by Cloudflare; potential risk of account suspension.

• Does not manage WireGuard daemon lifecycle or apply profiles to the system (user responsibility).
• Does not provide GUI or web interface (CLI-only).
• Does not support real-time account synchronization across multiple devices (one-time export per device).
• Does not handle VPN routing or traffic management (profile generation only).
• Does not provide offline key storage or hardware security module integration.

1. Cloudflare bug (#85): Existing accounts that ever connected to Warp VPN cannot upgrade to Warp+, even with valid license key. Workaround requires registering a fresh account immediately (no other commands between register and update). 2. License key source: Only keys from the official 1.1.1.1 app work; referral keys and keys from other sources fail silently. 3. Account file location: wgcf-account.toml and wgcf-profile.conf are saved to the current working directory, not a .config folder; scripts must manage paths carefully. 4. Unofficial API: No guarantee Cloudflare won't change or block API endpoints; tool can break without warning.

• WireGuard Protocol & VPN Tunneling — wgcf's entire purpose is generating valid WireGuard profiles; you must understand how WireGuard endpoints, keys, and MTU affect VPN connectivity and performance
• OpenAPI 3.0 Code Generation — The openapi/ directory is auto-generated from openapi-spec.yml; knowing how OpenAPI tooling works explains why regenerating the client (openapi-generator) is necessary if Cloudflare's API changes
• Account Licensing & Device Binding — wgcf implements Warp+ license key binding (5 device limit, account-level subscription tracking); understanding Cloudflare's licensing model prevents user confusion around key reuse and device limits
• CLI Argument Parsing & Subcommand Routing (Cobra Framework) — Cobra's Command/AddCommand pattern is how wgcf structures register/generate/update/status/trace commands; modifying or extending CLI requires understanding this routing model
• TOML Configuration Serialization — wgcf persists account state to wgcf-account.toml using Viper/pelletier/go-toml; understanding TOML unmarshaling and key naming prevents data corruption or migration issues
• Maximum Transmission Unit (MTU) Optimization — wgcf hardcodes MTU to 1280 (like the official app) in generated profiles; misunderstanding MTU can cause fragmentation issues or performance degradation on certain networks
• Cross-Platform Binary Distribution & GoReleaser — wgcf uses GoReleaser (.goreleaser.yml) to build and publish binaries for Windows/macOS/Linux; understanding this automates deployment and ensures version consistency across platforms

• WireGuard/wireguard-go — Pure Go WireGuard implementation; understanding this is helpful for validating the profile structure wgcf generates
• cloudflare/warp-cli — Official Cloudflare WARP CLI tool; wgcf is a reverse-engineered alternative to this, useful for comparing command parity
• ipfs/kubo — Large Go CLI project using Cobra and similar config patterns (Viper); reference for scaling multi-command Go tools
• helm/helm — Mature Cobra + Viper CLI; demonstrates patterns for config file management and subcommand structure that wgcf follows
• ViRb3/wgcf-docker — Likely the official Docker wrapper around wgcf; shows how users containerize and deploy wgcf in production

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for cloudflare/api.go API interactions

The cloudflare/ directory currently lacks test files despite containing critical API logic in api.go and util.go. Given that this CLI depends entirely on Cloudflare Warp API interactions for register, update, and status commands, adding unit tests would catch regressions early. Tests should mock HTTP responses and validate error handling for network failures, invalid credentials, and API changes.

• [ ] Create cloudflare/api_test.go with table-driven tests for each public function in api.go (register, update, getSourceDevice, etc.)
• [ ] Create cloudflare/util_test.go for utility function tests
• [ ] Add test fixtures or use httptest.Server to mock Cloudflare API responses
• [ ] Update .github/workflows/test.yml to run these new tests with go test ./cloudflare

Add integration tests for all cmd/ subcommands in GitHub Actions

The repo has cmd/register, cmd/generate, cmd/update, cmd/status, and cmd/trace but no visible integration tests validating end-to-end workflows. The test.yml workflow exists but its actual test coverage is unclear. Adding integration tests would ensure command parsing, config file handling, and output formatting work correctly across platforms.

• [ ] Create cmd/register/register_test.go, cmd/generate/generate_test.go, cmd/status/status_test.go with integration tests that use temporary config directories
• [ ] Test that wgcf register properly saves to wgcf-account.toml and validates required flags
• [ ] Test that wgcf generate reads config and outputs valid WireGuard format
• [ ] Ensure .github/workflows/test.yml runs go test ./cmd/... with proper test coverage reporting

Add OpenAPI client regeneration validation and documentation in CI

The openapi/ directory appears to be auto-generated from openapi-spec.yml, but there's no CI check ensuring the generated code stays in sync with the spec. If the spec updates but openapi/ isn't regenerated, the CLI could use stale API bindings. Add validation and document the regeneration process.

• [ ] Create a new GitHub Actions workflow (e.g., .github/workflows/openapi-validate.yml) that regenerates the openapi/ client using openapi-generator-cli and checks for git diff
• [ ] Add a Makefile target or script that documents how to regenerate with: openapi-generator-cli generate -i openapi-spec.yml -g go -o ./openapi
• [ ] Update README.md with a 'Contributing' section explaining the OpenAPI workflow and how to regenerate when openapi-spec.yml changes
• [ ] Add generated files validation step to prevent accidental commits of out-of-sync openapi/ directory

• Add unit tests for cmd/generate/generate.go: Currently no test files visible in cmd/. Write tests for WireGuard profile generation logic (MTU calculation, endpoint formatting, interface config) to ensure profiles render correctly across platforms.
• Improve error messages for license key validation: cloudflare/api.go likely has generic HTTP errors when an invalid/referral license key is submitted. Add specific error detection and user-friendly messages to cmd/update/update.go explaining why the key failed (vs generic '401 Unauthorized').
• Document config file format and schema: No openapi/docs/ files cover the wgcf-account.toml structure. Create docs/ACCOUNT_FORMAT.md explaining the TOML fields (account ID, token, install date, etc.) that config/config.go uses, with examples for manual editing.

• High · Outdated Golang Base Image in Dockerfile — Dockerfile (line 1). The Dockerfile uses golang:1.25.5-alpine for building, but this version doesn't exist in the official Go repository. The latest stable Go version is 1.24.x. Using non-existent or unofficial images could introduce supply chain risks and may fail in CI/CD pipelines. Fix: Update to a valid and recent Go version like golang:1.24-alpine or golang:1.23-alpine. Verify the image exists in the official golang registry.
• Medium · Outdated Alpine Base Image — Dockerfile (line 9). Alpine 3.23.2 appears to be a future or non-existent version. Current Alpine releases are in the 3.20.x range. Using non-existent base images creates unpredictability and potential security issues. Fix: Update to a current Alpine release like alpine:3.20 or alpine:3.21. Verify the image tag exists in the official alpine registry.
• Medium · Missing SBOM and Dependency Pinning — go.mod. The go.mod file uses loose version constraints for critical dependencies (cockroachdb/errors, manifoldco/promptui, spf13/cobra). Indirect dependencies are also not pinned to specific versions, increasing the risk of supply chain attacks and unexpected breaking changes. Fix: Use go get -u to fetch latest compatible versions and commit go.sum. Consider using Go 1.21+ with workspace mode for better control. Implement dependency scanning in CI/CD with tools like govulncheck.
• Medium · Potential Credential Storage in Configuration Files — config/config.go and cmd/register/register.go. The application saves account credentials to 'wgcf-account.toml' (as mentioned in README). If this file is stored in world-readable locations or accidentally committed to version control, credentials could be exposed. Fix: Ensure configuration files are created with restrictive permissions (0600). Add wgcf-account.toml to .gitignore (verify it's present). Document secure credential storage practices. Consider encrypting sensitive fields in the TOML file.
• Medium · Outdated Cryptography Dependency — go.mod (line 7). golang.org/x/crypto v0.46.0 is specified, but newer versions (0.47.0+) are available. Using older crypto packages increases exposure to potential cryptographic vulnerabilities. Fix: Update golang.org/x/crypto to the latest stable version. Run 'go get -u golang.org/x/crypto' and test thoroughly.
• Low · Weak Compiler Flags in Build Process — Dockerfile (line 7). The Dockerfile uses '-s -w' ldflags which strips all symbols and debug information. While this reduces binary size, it may complicate security incident investigations and makes crash debugging harder. Fix: Consider using '-s -w' only for production releases. For development/testing, maintain debug symbols. Alternatively, use build caching to minimize image bloat without stripping symbols.
• Low · Missing Security Context in Docker — Dockerfile (line 9-13). The Dockerfile does not specify a non-root user or security context. The container runs as root, which is a security best practice violation. Fix: Add a non-root user creation and switch to it before running the application. Example: 'RUN addgroup -g 1000 wgcf && adduser -D -u 1000 -G wgcf wgcf && USER wgcf'
• Low · Missing Health Check in Docker — Dockerfile. The Dockerfile does not include a HEALTHCHECK instruction, making it difficult to monitor container health in orchestration environments. Fix: Add a HEALTHCHECK instruction to verify the application is responsive. Example: 'HEALTHCHECK --interval=30s --timeout=3s CMD /wgcf status || exit 1'
• Low · No OpenAPI Generator Version Lock — undefined. The openapi directory contains generated code from OpenAPI spec with a .openapi-generator/VERSION file but no explicit versioning in the main build Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.