cf-redirects

cf-redirects is a small Go CLI that discovers Cloudflare bulk redirect lists across the accounts available to your API token and prints each redirect as:

• source URL
• target URL
• status
• parameters

It supports tsv output by default, plus csv, table, and json.

Requirements

Create a Cloudflare API token with at least:

• Account Filter Lists Read

The CLI uses the Cloudflare v4 API to:

1. List accessible accounts
2. Find redirect lists in each account
3. Fetch the redirect items from those lists

Cloudflare Redirect Setup Reminder

If you are setting up Bulk Redirects in Cloudflare, the easy-to-forget DNS details are:

• The hostname being redirected must be proxied by Cloudflare.
• For a redirect-only hostname with no origin behind it, use a proxied A record pointing to 192.0.2.1.
• If you also redirect www, create a proxied record for www too.

Typical DNS records look like:

Type  Name  IPv4       Proxy
A     @     192.0.2.1  Proxied
A     www   192.0.2.1  Proxied

Then create:

1. A Bulk Redirect List containing the source and target URLs
2. A Bulk Redirect Rule that enables that list

Cloudflare docs for this setup:

• Redirect one domain to another: https://developers.cloudflare.com/fundamentals/setup/manage-domains/redirect-domain/
• Create Bulk Redirects in the dashboard: https://developers.cloudflare.com/rules/url-forwarding/bulk-redirects/create-dashboard/

Token Setup

cf-redirects looks for a token in this order:

1. CLOUDFLARE_API_TOKEN
2. CF_API_TOKEN
3. .env

Environment variables take precedence over values in .env.

CLOUDFLARE_ACCOUNT_ID is optional. Use it when:

• your token cannot enumerate accessible accounts
• you want to scope the CLI to one account by default

Option 1: Environment variable

export CLOUDFLARE_API_TOKEN=your_token_here
export CLOUDFLARE_ACCOUNT_ID=your_account_id_here # optional

Option 2: .env file

Create a .env file in the repo root:

CLOUDFLARE_API_TOKEN=your_token_here
CLOUDFLARE_ACCOUNT_ID=your_account_id_here

You can copy the example file:

cp .env.example .env

Usage

go run ./cmd/cf-redirects list

Print the binary version:

go run ./cmd/cf-redirects version
go run ./cmd/cf-redirects --version

Default output is tab-separated, one redirect per line:

example.com/old	https://example.com/new	301	preserve_query_string,subpath_matching,preserve_path_suffix

Pretty table output:

go run ./cmd/cf-redirects list --format table

JSON output:

go run ./cmd/cf-redirects list --format json

CSV output with headers:

go run ./cmd/cf-redirects list --format csv --header

Filter to a specific account or list:

go run ./cmd/cf-redirects list --account-id <account_id>
go run ./cmd/cf-redirects list --list-id <list_id>

Show account and list IDs in human output:

go run ./cmd/cf-redirects list --format table --show-ids
go run ./cmd/cf-redirects list --show-ids

Use a custom env file path:

go run ./cmd/cf-redirects list --env-file .env.local

Output Formats

TSV

Default output is TSV and prints exactly four columns per line:

1. source URL
2. target URL
3. status
4. parameters

With --show-ids, TSV output prepends:

1. account ID
2. list ID

Add --header if you want a header row for spreadsheet import.

CSV

Use --format csv for comma-separated output with proper CSV quoting. Add --header when you want column names in the first row.

Table

--format table prints those same fields in a formatted table with headers. With --show-ids, it also includes account and list IDs.

JSON

--format json prints structured records and includes extra metadata:

• account_id
• account_name
• list_id
• list_name
• redirect fields
• a derived parameters array

Legacy shorthands still work:

• --json maps to --format json
• --table maps to --format table

Development

make fmt
make test
make build

Local builds default to version dev. To stamp a specific version into the binary:

make build VERSION=v0.1.0
./cf-redirects version

Releases

GitHub Actions builds release archives for:

• Linux amd64 and arm64
• macOS amd64 and arm64
• Windows amd64 and arm64

On every push to main, pull request, or manual workflow run, the workflow produces downloadable build artifacts in GitHub Actions.

To publish executables as a GitHub Release, push a version tag:

git tag v0.1.0
git push origin v0.1.0

That tag creates release archives such as:

• cf-redirects_v0.1.0_linux_amd64.tar.gz
• cf-redirects_v0.1.0_darwin_arm64.tar.gz
• cf-redirects_v0.1.0_windows_amd64.zip