# ViRb3/wgcf: a CLI that turns Cloudflare Warp into a WireGuard profile

> wgcf registers a Cloudflare Warp account and writes a WireGuard config you can import into any client. It is a small Go binary with a narrow job, and the README is candid about the account bug that trips up Warp+ users.

**ViRb3/wgcf** — 🚤 Cross-platform, unofficial CLI for Cloudflare Warp

- Repository: https://github.com/ViRb3/wgcf
- Stars: 8,747 · Forks: 870
- Language: Go
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/virb3-wgcf

## The gap wgcf fills between the 1.1.1.1 app and a WireGuard client

Cloudflare Warp is normally consumed through the official 1.1.1.1 app. wgcf exists for people who would rather not run that app: it registers a Warp account on your behalf and emits a standard WireGuard profile, which any WireGuard client can then import. The project describes itself as an unofficial, cross-platform CLI for Cloudflare Warp, and it is written in Go, so the same binary runs on the platforms Go targets.

The audience is narrow and technical. If you already use WireGuard for other tunnels and want Warp as one more peer in the same client, wgcf produces that peer. If you want a graphical VPN with a kill switch and a support channel, wgcf is the wrong layer: it hands you a config file and stops there. The README also carries a non-affiliation notice, so nobody should read this as a Cloudflare product.

The feature list is short by design: register an account, change the license key to use an existing Warp+ subscription, generate a WireGuard profile, check account status, and print trace information to debug Warp or Warp+ status. Five verbs. That is the whole tool.

## How registration, the account file and profile generation fit together

The flow is a local file pipeline. wgcf register creates a new account and saves it under wgcf-account.toml. That TOML file is the durable state: the account identity lives there, not in a daemon. wgcf generate reads it and writes wgcf-profile.conf, a WireGuard configuration. wgcf status reports on the account, and wgcf trace prints trace information you read after connecting, where the last line should say warp=on or warp=plus.

The codebase reflects this split. There is a cloudflare/ package, a wireguard/ package, a cmd/ package for the Cobra commands, a config/ package, and an openapi/ package. According to the README, the API client code in openapi/ is auto-generated from openapi-spec.yml, and contributors are told not to touch anything under that package; instead they change the spec and regenerate. The go.mod confirms the openapi package is a separate module wired in with a replace directive pointing at ./openapi, and it lists github.com/refraction-networking/utls among the direct dependencies, which is the kind of TLS library a client reaches for when the default Go TLS fingerprint is a problem.

So the data flow is: an HTTP call to Cloudflare's API registers or updates the account, the result is persisted to wgcf-account.toml, and a local transformation turns that account into WireGuard key material and endpoint settings in wgcf-profile.conf. Nothing runs in the background.

## Installing wgcf and generating your first profile

The README points to pre-compiled binaries on the releases page, and does not document a package-manager install. There is also a Dockerfile in the repository, which builds the binary in a golang:1.27.0-alpine stage and copies it into an alpine:3.24.1 image with ENTRYPOINT ["/wgcf"], so the container takes wgcf subcommands as its arguments. Building from source follows the usual Go path, and the module is github.com/ViRb3/wgcf/v2.

Once you have the binary, the first real use is two commands. Registration writes the account file:

```bash
wgcf register
```

You should end up with wgcf-account.toml in the working directory. Then generate the profile:

```bash
wgcf generate
```

That writes wgcf-profile.conf, which you import into a WireGuard client following the upstream WireGuard Quick Start that the README links to. If you need the tunnel to keep NAT mappings alive, the optional keepalive flag adds PersistentKeepalive to the profile's [Peer] section; it is omitted by default, and the default interval is 25 seconds:

```bash
wgcf generate --keepalive
wgcf generate --keepalive=60
```

After connecting the profile, run wgcf trace and read the last line. It should read warp=on, or warp=plus if you have Warp+.

## Binding a Warp+ license key, and the Cloudflare bug that blocks it

If you already pay for Warp+, you can bind the account wgcf generated to your phone's account so it shares the Warp+ status. The README notes a limit of 5 maximum devices linked at a time, and says you can remove linked devices from the 1.1.1.1 app. It also states plainly that only subscriptions purchased directly from the official 1.1.1.1 app are supported, and that keys obtained by any other means, including referrals, will not work and will not be supported. That is a hard boundary, not a soft warning.

The commands are:

```bash
wgcf update --license-key "YOUR_LICENSE_KEY_GOES_HERE"
wgcf generate
```

The README then documents a bug on Cloudflare's side: existing accounts cannot get Warp+ even after a correct key is bound, and any account that has ever connected to Warp is affected. The prescribed workaround is to register a fresh account with wgcf register and immediately proceed with the license-key steps, without running any other commands in between. If wgcf trace still reports warp=on after binding a key, the README says you are likely hitting this bug. This is the least pleasant part of the tool, and it is not wgcf's fault, but it is the part most likely to waste an afternoon.

## The MTU default and the keepalive flag are the two tuning knobs

The generated profile ships with an MTU of 1280, chosen, per the README, to match the official Android app and to maximize compatibility. The README is direct that this can cost you speed: if you see performance issues, increasing the value may improve speed, and it links to issue #40 for discussion. There is no documented automatic MTU discovery, so this is a manual trade-off between compatibility and throughput. If you are on a network where 1280 works and you are happy with the speed, leave it alone.

PersistentKeepalive is the second knob, and it is off unless you ask for it. On a network with aggressive NAT timeouts, a tunnel that is idle can lose its mapping, and periodic packets are the fix. The flag accepts a bare form that defaults to 25 seconds or an explicit interval. Both settings end up in the file wgcf writes, so if you regenerate the profile you should re-check them; the README does not describe a merge or preserve step for hand edits.

## Where wgcf stops and a full VPN client begins

The honest comparison is not another Warp CLI, it is the official 1.1.1.1 app. The app manages the connection, ships a UI, and is the thing Cloudflare supports. wgcf does none of that: it produces a config, and the WireGuard client you already trust does the rest. The practical difference is control versus support. With wgcf you get one more peer in a client you chose, with your own routing rules, and you accept that the tool is unofficial and that Cloudflare's API can change underneath it.

A second comparison is WireGuard itself. wgcf is not a WireGuard implementation; it is a provisioning tool for one specific provider. If your goal is peer-to-peer WireGuard between your own machines, wgcf contributes nothing, because it only knows how to talk to Cloudflare's Warp endpoints. Likewise, if you want Warp on a device where you cannot import a WireGuard profile, the generated file is useless to you.

One more boundary worth naming: the account file is the state. Lose wgcf-account.toml and you have lost the local handle on that account; the README does not document an export, import or backup path for it.

## Maintenance, licence and what an upgrade actually costs you

The repository is not archived, and the last push was on 2026-09-18, the same day as the v2.3.0 release. Before that, v2.2.32 landed on 2026-07-23 and v2.2.31 on 2026-05-23, so releases have been arriving at a steady clip. The project is MIT licensed, which permits commercial and private use, modification and redistribution provided the copyright notice and permission notice are included; that is a summary of the licence, not legal advice, and anyone embedding wgcf in a product should read the LICENSE file themselves.

Upgrade cost is low in the normal case. The binary is self-contained, the account file is TOML, and the generated profile is a text file you can diff. The real risk sits in the API layer: the client is generated from openapi-spec.yml, so a Cloudflare-side change to that API is the kind of thing that shows up as a broken command rather than a version bump. The README's instruction to regenerate the client with go generate after editing the spec means contributors need openapi-generator installed, which is an extra toolchain step for anyone touching that package. For ordinary users, upgrading means replacing the binary and, if the profile format changed, regenerating wgcf-profile.conf.

## Conclusion

Adopt wgcf if you want a Warp connection managed by a standard WireGuard client instead of the 1.1.1.1 app, and you are willing to run a small unofficial binary against Cloudflare's API. Skip it if you need a supported, vendor-backed client, or if your Warp+ key came from referrals, which the README says will not work. Before relying on it, verify that wgcf trace reports warp=plus after you bind a key, and check whether your existing account is affected by the Cloudflare-side bug that blocks Warp+ on accounts that have already connected to Warp.

## FAQ

### Is Cloudflare WARP VPN safe to use?

The README does not make a security claim about Warp itself. It does state that wgcf is not affiliated with, authorized by or endorsed by Cloudflare, and that the tool only talks to Cloudflare's API to register an account and generate a WireGuard profile.

### What does Cloudflare WARP do exactly?

The README does not describe Warp's network behaviour beyond wgcf's interaction with it. What can be confirmed is that wgcf register creates a Warp account at Cloudflare and wgcf trace reports warp=on or warp=plus after you connect the generated WireGuard profile.

### Is CloudFlare WARP free to use?

The README does not state Warp pricing. It does say that Warp+ requires a subscription purchased directly from the official 1.1.1.1 app, and that keys obtained by other means, including referrals, will not work and will not be supported.

## Sources

- [Issues](https://github.com/ViRb3/wgcf/issues)
- [License: MIT](https://github.com/ViRb3/wgcf/blob/master/LICENSE)
- [README](https://github.com/ViRb3/wgcf/blob/master/README.md)
- [Releases](https://github.com/ViRb3/wgcf/releases)
- [ViRb3/wgcf on GitHub](https://github.com/ViRb3/wgcf)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/virb3-wgcf