README.md
1# cloudflare-go
2
3[![Go Reference](https://pkg.go.dev/badge/github.com/cloudflare/cloudflare-go.svg)](https://pkg.go.dev/github.com/cloudflare/cloudflare-go)
4![Test](https://github.com/cloudflare/cloudflare-go/workflows/Test/badge.svg)
5[![Go Report Card](https://goreportcard.com/badge/github.com/cloudflare/cloudflare-go?style=flat-square)](https://goreportcard.com/report/github.com/cloudflare/cloudflare-go)
6
7> **Note**: This library is under active development as we expand it to cover
8> our (expanding!) API. Consider the public API of this package a little
9> unstable as we work towards a v1.0.
10
11A Go library for interacting with
12[Cloudflare's API v4](https://api.cloudflare.com/). This library allows you to:
13
14* Manage and automate changes to your DNS records within Cloudflare
15* Manage and automate changes to your zones (domains) on Cloudflare, including
16 adding new zones to your account
17* List and modify the status of WAF (Web Application Firewall) rules for your
18 zones
19* Fetch Cloudflare's IP ranges for automating your firewall whitelisting
20
21A command-line client, [flarectl](cmd/flarectl), is also available as part of
22this project.
23
24## Features
25
26The current feature list includes:
27
28* [x] Cache purging
29* [x] Cloudflare IPs
30* [x] Custom hostnames
31* [x] DNS Records
32* [x] Firewall (partial)
33* [x] [Keyless SSL](https://blog.cloudflare.com/keyless-ssl-the-nitty-gritty-technical-details/)
34* [x] [Load Balancing](https://blog.cloudflare.com/introducing-load-balancing-intelligent-failover-with-cloudflare/)
35* [x] [Logpush Jobs](https://developers.cloudflare.com/logs/logpush/)
36* [ ] Organization Administration
37* [x] [Origin CA](https://blog.cloudflare.com/universal-ssl-encryption-all-the-way-to-the-origin-for-free/)
38* [x] [Railgun](https://www.cloudflare.com/railgun/) administration
39* [x] Rate Limiting
40* [x] User Administration (partial)
41* [x] Virtual DNS Management
42* [x] Web Application Firewall (WAF)
43* [x] Zone Lockdown and User-Agent Block rules
44* [x] Zones
45* [x] Workers KV
46* [x] Notifications
47
48Pull Requests are welcome, but please open an issue (or comment in an existing
49issue) to discuss any non-trivial changes before submitting code.
50
51## Installation
52
53You need a working Go environment.
54
55```
56go get github.com/cloudflare/cloudflare-go
57```
58
59## Getting Started
60
61```go
62package main
63
64import (
65 "context"
66 "fmt"
67 "log"
68 "os"
69
70 "github.com/cloudflare/cloudflare-go"
71)
72
73func main() {
74 // Construct a new API object
75 api, err := cloudflare.New(os.Getenv("CF_API_KEY"), os.Getenv("CF_API_EMAIL"))
76 if err != nil {
77 log.Fatal(err)
78 }
79
80 // Most API calls require a Context
81 ctx := context.Background()
82
83 // Fetch user details on the account
84 u, err := api.UserDetails(ctx)
85 if err != nil {
86 log.Fatal(err)
87 }
88 // Print user details
89 fmt.Println(u)
90
91 // Fetch the zone ID
92 id, err := api.ZoneIDByName("example.com") // Assuming example.com exists in your Cloudflare account already
93 if err != nil {
94 log.Fatal(err)
95 }
96
97 // Fetch zone details
98 zone, err := api.ZoneDetails(ctx, id)
99 if err != nil {
100 log.Fatal(err)
101 }
102 // Print zone details
103 fmt.Println(zone)
104}
105```
106
107Also refer to the
108[API documentation](https://pkg.go.dev/github.com/cloudflare/cloudflare-go) for
109how to use this package in-depth.
110
111# License
112
113BSD licensed. See the [LICENSE](LICENSE) file for details.
114