A simple command line interface for managing your porkbun domains.
- Create/Delete domain records
- Edit existing domain records
- Update record content:
- By command line
- By current external IP address
- Periodically, to pick changes in external address (useful if you have a dynamic IP)
The project uses uv to manage its virtual environment and dependencies. If you don't have uv installed yet, install it with either:
curl -LsSf https://astral.sh/uv/install.sh | shpython3 -m pip install uv
From the project root, create the .venv virtual environment and install all dependencies with:
uv sync
That's it! All the example commands below run through uv, so they automatically use this environment - no activation or manual package installation is required.
uv run python src/porkbun-cli -h
Alternatively, you may also activate the virtual environment manually and invoke the tool directly like so:
. .venv/bin/activate
python src/porkbun-cli.py -hBefore using this tool, you will need to generate API keys for your porkbun account and enable API access for any domains that you want to manage with this tool. You can do this from your porkbun dashboard. The tool expects to see two files in it's working directory:
api-key
secret-api-key
Which should contain your api and secret keys respectively. Remember to set appropriate file permissions for your secret key!
The first thing you should probably do is ping the porkbun API to check that your API keys are set up correctly:
uv run python src/porkbun-cli ping
The tool also has comprehensive help output:
uv run python src/porkbun-cli -h
If you are unfamiliar with command line interfaces like this one and find the help message confusing, then here is a brief summary:
<>Indicates an input field[]Indicates an optional argument(A|B)Indicates that you may specify A or B, but not both-or--Indicates an option
If you are a programmer and want to learn how to create beautiful command line interfaces like this one, then look no further!
This tool can be used to create a dynamic updater that will update the content of a record periodically to keep track with your external IP address. This is especially useful if you want your record to point at a residential connection with a dynamic IP.
For example, the following command will check your external IP address every 5 seconds and update the specified record if the IP changes:
uv run python src/porkbun-cli record update <domain> <record-id> --delay=5
The record id can be obtained by listing the records associated with your domain:
uv run python src/porkbun-cli record list <domain>
TODO
The tests exercise the real Porkbun API, so they need developer-provided credentials. Create the following files in the project root (all gitignored, never committed):
api-key- your Porkbun API keysecret-api-key- your Porkbun secret API keytest-domain- a domain the keys are authorized to manipulate
If any of these are missing, the test run aborts with an error explaining what to provide. Run the suite with:
uv run pytest
Note that the tests are live: they call the real Porkbun API and create, edit and delete real records under your test domain (always cleaned up again afterwards). Each test run uses uniquely-named records so runs never collide. To be considerate of Porkbun's servers, the suite pauses for 1 second before every API request, so a full run takes a little while.