Config file

cipr uses the same config file path on Linux and MacOS:

~/.config/cipr/cipr.toml

The file is created automatically on first run with the default endpoints below:

cipr.toml (default)

# cipr config. Override per-provider data sources here, or pass --source on
# the command line. For each provider:
#   <provider>_endpoint   = URL fetched when --source=config (the default)
#   <provider>_local_file = if set, read ranges from this path instead of the network
#   <provider>_cache_ttl  = how long to reuse a cached hosted response. Go duration
#                           string ("24h", "30m"). "0s" disables caching for this
#                           provider; defaults to 24h if unset or unparseable.

proxy = ""
debug = false

aws_endpoint = "https://ip-ranges.amazonaws.com/ip-ranges.json"
aws_local_file = ""
aws_cache_ttl = "24h"

azure_endpoint = "https://www.microsoft.com/en-us/download/details.aspx?id=56519"
azure_local_file = ""
azure_cache_ttl = "24h"

cloudflare_ipv4_endpoint = "https://www.cloudflare.com/ips-v4/"
cloudflare_ipv4_local_file = ""
cloudflare_ipv4_cache_ttl = "24h"

cloudflare_ipv6_endpoint = "https://www.cloudflare.com/ips-v6/"
cloudflare_ipv6_local_file = ""
cloudflare_ipv6_cache_ttl = "24h"

digitalocean_endpoint = "https://digitalocean.com/geo/google.csv"
digitalocean_local_file = ""
digitalocean_cache_ttl = "24h"

gcp_endpoint = "https://www.gstatic.com/ipranges/cloud.json"
gcp_local_file = ""
gcp_cache_ttl = "24h"

github_endpoint = "https://api.github.com/meta"
github_local_file = ""
github_cache_ttl = "24h"

icloud_endpoint = "https://mask-api.icloud.com/egress-ip-ranges.csv"
icloud_local_file = ""
icloud_cache_ttl = "24h"

Config options

cipr will get IP ranges from sources defined in this config unless it is overridden with the --source flag.

You can use a configured endpoint or local file for IP ranges.

tip

If defined, *_local_file will always take precedence over *_endpoint!

Field	Description	File type	Required
aws_endpoint	Hosted endpoint for aws command.	JSON	👍
aws_local_file	Local file for aws command.	JSON	❌
azure_endpoint	Hosted endpoint for azure command. Either the Microsoft download page (cipr scrapes the latest ServiceTags JSON URL from it) or a direct ServiceTags JSON URL.	HTML or JSON	👍
azure_local_file	Local file for azure command.	JSON	❌
cloudflare_ipv4_endpoint	Hosted endpoint for cloudflare command. IPv4 IP ranges.	TXT	👍
cloudflare_ipv4_local_file	Local file for cloudflare command. IPv4 IP ranges.	TXT	❌
cloudflare_ipv6_endpoint	Hosted endpoint for cloudflare command. IPv6 IP ranges.	TXT	👍
cloudflare_ipv6_local_file	Local file for cloudflare command. IPv6 IP ranges.	TXT	❌
digitalocean_endpoint	Hosted endpoint for do command.	CSV	👍
digitalocean_local_file	Local file for do command.	CSV	❌
gcp_endpoint	Hosted endpoint for gcp command.	JSON	👍
gcp_local_file	Local file for gcp command.	JSON	❌
github_endpoint	Hosted endpoint for github command.	JSON	👍
github_local_file	Local file for github command.	JSON	❌
icloud_endpoint	Hosted endpoint for icloud command.	CSV	👍
icloud_local_file	Local file for icloud command.	CSV	❌
<provider>_cache_ttl	How long to reuse a cached configured-endpoint response. Go duration string (24h, 30m). 0s disables caching for that provider. Defaults to 24h if unset or unparseable.	Duration	❌
proxy	HTTP or HTTPS proxy used for network requests. An empty value uses standard proxy environment variables.	URL	❌
debug	Write source, cache, proxy and HTTP diagnostics to stderr.	Boolean	❌

Configure command

Use cipr configure to inspect or update managed settings. With no source key, it prints the effective config for all sources:

CLI command

cipr configure

Pass a source key to inspect or update one source:

CLI commands

cipr configure aws
cipr configure aws --endpoint https://example.com/aws-ranges.json
cipr configure azure --local-file /path/to/azure-ranges.json
cipr configure azure --cache-ttl 0s
cipr configure gcp

Valid source keys are aws, azure, cloudflare_ipv4, cloudflare_ipv6, digitalocean, gcp, github and icloud.

Existing config files do not require migration. If the GCP keys are absent, cipr uses the default cloud.json endpoint and a 24-hour cache TTL; cipr configure gcp displays the effective values.

Setting --endpoint clears the local file override. --endpoint and --local-file cannot be changed in the same command.

Empty values reset managed settings:

CLI commands

cipr configure aws --endpoint ""
cipr configure aws --local-file ""
cipr configure aws --cache-ttl ""
cipr configure --proxy ""
cipr configure --debug=false

You can also save a proxy or enable debug logging:

CLI commands

cipr configure --proxy http://proxy.example.com:8080
cipr configure --debug

Updates are written to the active config file. Use --config to inspect, create or update another file:

CLI command

cipr --config /path/to/cipr.toml configure

Caching

When fetching from a configured endpoint, cipr caches the response on disk and reuses it until the provider TTL expires. This keeps scripts, cron jobs and CI runs fast while reducing requests to provider endpoints.

Cache location:

• $XDG_CACHE_HOME/cipr/ if XDG_CACHE_HOME is set
• ~/.cache/cipr/ otherwise

One file per source (e.g. aws.cache, gcp.cache, cloudflare_ipv4.cache). To wipe the cache, delete the directory.

TTL: controlled per provider via the <provider>_cache_ttl config key (see the table above). Default is 24h. Set to 0s to disable caching for that provider.

When the cache is bypassed:

• --no-cache flag (one-off, skips both read and write; see Global Flags)
• --source <url> or --source <path> (custom sources never use the cache)
• <provider>_local_file is set in the config (the local file is the source of truth)
• <provider>_cache_ttl = "0s" in the config

tip

If you change a <provider>_endpoint, delete the matching .cache file before the next normal run. --no-cache fetches fresh data for one invocation but deliberately does not delete or replace an existing cache file.