cfex v2: Go on cloudflared, instant + durable, agent skill, releases by muthuishere · Pull Request #1 · muthuishere/cfex-cli

muthuishere · 2026-10-05T14:46:20Z

cfex v2 (Go, on cloudflared)

main becomes v2 only. The bash version is preserved as the v1.0.0 release (legacy, with bin/cfex and install.sh attached). cloudflared does the tunnel work (create, route dns, list, delete, run); the Cloudflare API is optional and only adds what cloudflared cannot do (DNS ownership comments, deleting DNS records, remote ingress, zone validation).

v2 features

cfex <domain>:<port> instant mode (foreground, Ctrl+C removes the tunnel and the DNS record it created, --keep makes it durable) · cfex add durable routes (launchd/systemd) · list of everything on the machine · stop/start · delete (y/N on a terminal) · status/doctor/troubleshoot · import · skill install|uninstall · uninstall · GoReleaser releases + checksum-verifying install.sh.

Parity with v1 (every v1 item)

v1 (bash)	v2	Proof
`cfex <domain>:<port>`	instant mode	`TestInstantParse`
`cfex <domain> <port>` (original syntax)	same	`TestInstantParse`
`--https`	same	`TestInstantParse`, `TestInstantConfig`
`--verify-cert`	same (default ignores local certificate errors)	`TestInstantConfig`
auto-detect HTTPS origin (openssl / curl -k)	TLS probe of `localhost:<port>`, switches to HTTPS mode	`TestDetectHTTPS`
port must be a number in 1-65535	same messages	`TestInstantParse`
tunnel per domain, config file, DNS route, run in foreground	quick named tunnel via cloudflared, `route dns`, run	`TestInstantCtrlCRemovesDNSRecordAndTunnel`
"Found existing tunnel": cleanup stale connections, reuse	reuses a leftover instant tunnel	`TestInstantReusesALeftoverTunnel`
DNS route failure: warning + "try again in a few minutes", continue	same warning; on a fresh tunnel it stops and removes the tunnel it made	`TestInstantFailedRouteStillRemovesTheTunnelItCreated`
status lines ("accessible at https://...", HTTP/HTTPS, cert verification on/off, "Press Ctrl+C")	same lines	code review (`instant.go`)
Ctrl+C stops the tunnel	stops it and now ALSO removes the tunnel + DNS record (`--keep` to keep)	`TestInstantCtrlCRemovesDNSRecordAndTunnel`, `TestInstantWithoutTokenSaysDNSIsLeft`
prerequisite: cloudflared installed	same check and message	`cfex doctor`
`cloudflared tunnel login` guided flow when `cert.pem` is missing (4 steps, success/failure message)	same text; on success it continues instead of exiting	`ensureLogin` (needs a browser; manual)
API key setup instructions (Edit zone DNS template, zone, export)	printed by `cfex doctor` when no token, same steps	`cfex doctor`
`CLOUDFLARE_API_KEY` required	optional now; `CLOUDFLARE_API_TOKEN` or the old `CLOUDFLARE_API_KEY` both work	`TestTokenFromEnvOnly`
zone validation with the 3 "possible issues"	same message when a token is available	`validateZone`
`jq` and `curl` prerequisites	not needed to run (Go binary); `install.sh` still needs `curl`, `tar`, `cloudflared`	n/a
orphaned DNS record handling (delete + wait + 5 s)	`route dns` never overwrites; an existing record is reported	`TestInstantFailedRouteStillRemovesTheTunnelItCreated`
`cfex list`	`cfex list` (superset: all tunnels, ingress, launchd, live HTTP status; uses cloudflared, API optional)	`TestClassify`; live check
`cfex delete <d1> [d2 ...]`, one confirmation for all, "(not found)", "Skipping"	same flow; y/N on a terminal, `--yes` for scripts, dry run without a terminal	`TestConfirmDeleteDefaultsToNo`, `TestDeleteNeedsConfirmationOnTTYAndDryRunsWithoutOne`
delete: cleanup connections, `delete -f`, then DNS removal, waits up to 60 s for each	same (cloudflared cleanup/delete; DNS removal when a token is set) with the same wait loops	`TestWaitUntilTimesOutAndConfirms`
"Deletion process completed." / "Operation cancelled."	same	`TestConfirmDeleteDefaultsToNo`
`-h/--help` (usage, options, examples, notes)	same structure plus new commands	`TestUsageCoversEveryCommand`
`-v/--version`	same	manual
README troubleshooting (installation, auth, DNS, connection)	`cfex troubleshoot` and README	`TestUsageCoversEveryCommand`
platforms: Linux, macOS, Windows via WSL	binaries for linux/darwin amd64+arm64; WSL documented	`.goreleaser.yaml` (snapshot build verified)
`install.sh` (sudo handling, dependency checks, /usr/local/bin)	downloads the release binary, verifies the checksum, `/usr/local/bin` (sudo) or `~/.local/bin`, installs the skill	`bash -n`; end-to-end after the release exists
`uninstall.sh` (remove binary; optional removal of `~/.cloudflared`)	`cfex uninstall` / `uninstall.sh`: binary + skill; service, cfex config and `~/.cloudflared` are opt-in prompts (default no) or flags	`TestUninstallRemovesBinaryAndSkillButNotCloudflaredFiles`
README sections, AgentNexus community link, alternatives, examples/, article.md	all kept (README rewritten for v2)	n/a

Items that changed on purpose (OWNER APPROVED: "cfex: yes to the six")

package.json (npm bin) removed: it only pointed at the bash script and the package was never published.
list output: v1 printed a flat domain id list; v2 prints a richer table (a superset). Instant tunnels show their domain.
DNS deletion: v1 deleted every record with the domain's name; v2 deletes only the record that points at the tunnel being removed.
Tunnel/config naming: v1 tunnel_<domain> + ~/.cloudflared/<domain>_config.yml; v2 cfex-instant-<domain> + state under ~/.local/share/cfex/. A leftover v1 tunnel is not auto-recognised (list it with cfex list, delete it with cloudflared tunnel delete).
Ctrl+C now cleans up (v1 left the tunnel for reuse); --keep keeps it.
uninstall.sh no longer offers rm -rf ~/.cloudflared without the explicit opt-in.

Tests

make test passes (go vet; cmd/cfex, internal/cfd, internal/cfg, internal/ingress). The suite refuses to run unless CFEX_CONFIG points under the temp dir. goreleaser check and a snapshot build for darwin/linux amd64+arm64 succeed. gitleaks is clean.

Not yet verified live: the cloudflared-driven paths (create, route dns, list, instant cleanup) need cloudflared tunnel login on a machine with a Cloudflare domain; the unit tests use fakes for them. The API-only parts were verified earlier against a real zone.

Release plan

After review: merge, tag v2.0.0, the release workflow publishes the binaries + checksums.txt + install.sh. A Homebrew tap is a proposal only.

…tor/import Keeps every v1 command and flag working (cfex host:port, cfex host port, --https, --verify-cert, list, delete). Adds cfex add (one tunnel owned by cfex, additive ingress merge, launchd/systemd service), list of everything on the machine with live HTTP status, stop/start, status, doctor, import. Protected and client tunnels come from the user's config; the API token comes from the environment or an optional token_cmd. The bash script stays in bin/ until the Go binary ships.

…kill, uninstall, releases main becomes v2 only; the bash version lives on as the v1.0.0 release. - cloudflared does the tunnel work (create, route dns, list, delete, run); the API token is optional and only adds DNS ownership checks, DNS deletion, remote ingress and zone validation - instant mode (cfex host:port) removes its tunnel and DNS record on exit; --keep makes it durable - delete asks y/N on a terminal, --yes for scripts, dry run without a terminal - cfex skill install, cfex uninstall, troubleshoot - GoReleaser config, release workflow, install.sh that verifies checksums

muthuishere added 2 commits October 5, 2026 20:27

muthuishere force-pushed the v2-go branch from 9f54b8c to f8064ac Compare October 5, 2026 14:58

muthuishere changed the title ~~cfex v2: Go rewrite with durable routes and a machine-wide list~~ cfex v2: Go on cloudflared, instant + durable, agent skill, releases Oct 5, 2026

Navigation Menu

Repository navigation

cfex v2: Go on cloudflared, instant + durable, agent skill, releases - #1

cfex v2: Go on cloudflared, instant + durable, agent skill, releases#1
muthuishere wants to merge 2 commits into
mainfrom
v2-go

muthuishere commented Oct 5, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

muthuishere commented Oct 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!