Readme.md


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140

# pkb_client

Unofficial client for the Porkbun API

---
[![PyPI](https://img.shields.io/pypi/v/pkb_client)](https://pypi.org/project/pkb-client/) ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pkb_client) [![Downloads](https://static.pepy.tech/personalized-badge/pkb-client?period=total&units=international_system&left_color=grey&right_color=orange&left_text=Total%20Downloads)](https://pepy.tech/project/pkb-client) ![GitHub](https://img.shields.io/github/license/infinityofspace/pkb_client) ![GitHub Workflow Status](https://img.shields.io/github/workflow/status/infinityofspace/pkb_client/Publish%20release%20distribution%20to%20PyPI)
---

### Table of Contents

1. [About](#about)
2. [Installation](#installation)
    1. [With pip (recommend)](#with-pip-recommend)
    2. [From source](#from-source)
3. [Usage](#usage)
4. [Third party notices](#third-party-notices)
5. [License](#license)

---

### About

*pkb_client* is an unofficial client for the [Porkbun](https://porkbun.com) API. It supports the v3 of the API. You can
find the official documentation of the Porkbun API [here](https://porkbun.com/api/json/v3/documentation).

### Installation

This project only works with Python 3, make sure you have at least Python 3.6 installed.

#### With pip (recommend)

Use the following command to install *pkb_client* with pip:

```commandline
pip3 install pkb_client
```

You can also very easily update to a newer version:

```commandline
pip3 install pkb_client -U
```

#### From source

```commandline
git clone https://github.com/infinityofspace/pkb_client.git
cd pkb_client
pip install .
```

### Usage

Each request must be made with the API key and secret. You can easily create them at Porkbun. Just follow
the [official instructions](https://porkbun.com/api/json/v3/documentation#Authentication). Make sure that you explicitly
activate the API usage for your domain at the end.

After installation *pkb_client* is available under the command `pkb-client`.

You have to specify your API key and secret each time as follows:

```commandline
pkb-client -k <YOUR-API-KEY> -s <YOUR-API-SECRET> ping
```

If you don't want to specify the key and secret in the program call, because for example the command line calls are
logged and you don't want to log the API access, then you can also omit both arguments and *pkb-client* asks for a user
input.

You can see an overview of all usable API methods via the help:

```commandline
pkb-client -h
```

If you need more help on a supported API method, you can use the following command, for example for the ping method:

```commandline
pkb-client ping -h
```

#### Here are a few usage examples:

Create a new TXT record for the subdomain `test` of the domain `example.com` with the value `porkbun is cool` and a TTL
of `500`:

```commandline
pkb-client -k <YOUR-API-KEY> -s <YOUR-API-KEY-SECRET> dns-create example.com TXT "porkbun is cool" --name test --ttl 500
```

The call returns the DNS record id. The record DNS ids are used to distinguish the DNS records and can be used for
editing or deleting records. The ID is only a Porkbun internal identifier and is not publicly available.

Delete the DNS record with the ID `12345` of the domain `example.com`:

```commandline
pkb-client -k <YOUR-API-KEY> -s <YOUR-API-SECRET> dns-delete example.com 12345
```

Get all DNS records of the domain `example.com`:

```commandline
pkb-client -k <YOUR-API-KEY> -s <YOUR-API-SECRET> dns-retrieve example.com
```

Change the TXT DNS record content with the ID `456789` of the domain `example.com` to `the answer is 42`:

```commandline
pkb-client -k <YOUR-API-KEY> -s <YOUR-API-SECRET> dns-edit example.com 456789 TXT "the answer is 42"
```

Exporting all current DNS records of the domain `example.com` to the file `dns_recods.json`:

```commandline
pkb-client -k <YOUR-API-KEY> -s <YOUR-API-SECRET> dns-export example.com dns_recods.json
```

Remove all existing DNS records of the domain `example.com` and restore the DNS records from the file `dns_recods.json`:

```commandline
pkb-client -k <YOUR-API-KEY> -s <YOUR-API-SECRET> dns-import example.com dns_recods.json clear
```

*Note:* The import function uses the record ID to distinguish DNS records.

### Third party notices

All modules used by this project are listed below:

| Name | License|
|:---:|:---:|
| [requests](https://github.com/psf/requests) | [Apache 2.0](https://raw.githubusercontent.com/psf/requests/master/LICENSE) |
| [setuptools](https://github.com/pypa/setuptools) | [MIT](https://raw.githubusercontent.com/pypa/setuptools/main/LICENSE) |

Furthermore, this readme file contains embeddings of [Shields.io](https://github.com/badges/shields)
and [PePy](https://github.com/psincraian/pepy). The tests use [ipify](https://github.com/rdegges/ipify-api).

### License

[MIT](https://github.com/infinityofspace/pkb_client/blob/master/License) - Copyright (c) Marvin Heptner