Skip to main content

dncli

Manage your DevNomads services from the command line: inspect your services, manage DNS zones and records, and move zones over from other providers - from a shell or a script.

The command is dncli - named to avoid clashing with the macOS dnctl traffic-shaper at /usr/sbin/dnctl. Install it from PyPI as devnomads-cli.

Install

Install dncli with uv. It gives dncli its own isolated environment and installs the dncli command in ~/.local/bin:

uv tool install devnomads-cli
uv tool update-shell   # adds ~/.local/bin to your PATH, if it isn't yet

Then open a new terminal so the PATH change takes effect. On a fresh machine, and on macOS in particular, ~/.local/bin is not on your PATH by default, so without this step the shell reports dncli: command not found.

No uv yet? Install it first:

curl -LsSf https://astral.sh/uv/install.sh | sh                               # macOS, Linux
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"  # Windows

The installer adds ~/.local/bin to your shell profile, but only new terminals pick that up: open a new one before running uv tool install.

pipx (pipx install devnomads-cli) and pip (pip install devnomads-cli) work as well.

Windows: DLL load failed while importing _ctypes. When no Python is installed, uv downloads its own Python build. On Windows with Smart App Control or an App Control policy, that build's DLLs can be blocked ("… blocked by an application control policy"). Install the official Python and tell uv to use it instead; --force replaces the broken install:

winget install Python.Python.3.12
uv tool install devnomads-cli --python-preference only-system --force

Updates

Upgrade with:

dncli upgrade

It uses the tool you installed dncli with (uv, pipx, or pip in a virtualenv); where it can't, such as a system-wide pip install or on Windows, it prints the command to run instead. dncli upgrade --dry-run shows what it would do.

dncli checks PyPI at most once a day and tells you when a new version is out. It only does so on an interactive terminal, never in pipes, scripts or CI; set DN_NO_UPDATE_CHECK=1 to turn it off.

dncli also warns when the DevNomads API reports a major version it was not built for, and tells you when the API no longer supports your dncli version. Update dncli in both cases.

Shell completion

Enable shell completion (bash, zsh, fish, PowerShell):

dncli --install-completion

Getting started

Create an API key in the DevNomads portal under Profiel -> API Sleutels, then store it:

dncli configure

The key is written to ~/.config/dncli/credentials, readable only by you. From here every command works:

dncli services list
dncli domains list
dncli containers show <id>

Every DevNomads product has its own command group - apps, buckets, containers, databases, domains, emails, forwards, proxies, servers, sites and more, plus keys for your SSH keys and jobs for background work. Explore with dncli --help and dncli <group> --help.

In a terminal, commands accept any unambiguous prefix: dncli e l is dncli emails list. An ambiguous prefix lists the candidates. Scripts (no terminal on stdin) must spell commands out, so a truncated name can never run a different command; dncli then names the command you meant.

dncli commands lists every command with its options, and marks the ones that change something, ask for confirmation, run in the background or start billing. dncli commands --out json sites gives the full detail for one group, for scripts and AI agents.

Logging in to a site

dncli sites ssh opens an SSH session as the site's system user, site + the service id padded to five digits (service 2467 is site02467), so you don't need to know that name:

dncli sites ssh example.com
dncli sites ssh example.com -- ls -la      # run one command
dncli sites ssh example.com --dry-run      # print the ssh command

dncli logs in on the host the API lists for the site. A site that runs on several hosts (an HA cluster) asks which one; pick it with --host to skip the question, for example in a script. Anything after -- goes to ssh: extra options (-- -p 2222) or a remote command.

ssh logs in with your SSH key when the site has it; otherwise ssh itself asks for the site's password. dncli never sees or stores that password. Scripts and other runs without a terminal cannot answer a password prompt, so they need key login.

dncli helps with the key. Before it connects, it compares the public keys you have here (the ssh agent's, and the ~/.ssh/id_* files ssh would use) with the keys attached to the site. When none of yours is attached, it offers to attach one, adding it to your DevNomads account first if it isn't there yet. --attach-key does that without asking (for scripts), --no-attach-key skips the check. Only public keys are read and sent; your private key never leaves ~/.ssh. You can also do it on its own:

dncli sites keys attach-local example.com   # add to the account if needed, then attach
dncli keys add-local                        # only add it to your account
dncli keys add-local --key ~/.ssh/deploy.pub --name ci

Publishing a site

dncli sites publish uploads a folder (the current one by default) to a site with rsync, over the same SSH login as dncli sites ssh:

dncli sites publish example.com ./dist --dry-run   # show what would change
dncli sites publish example.com ./dist             # new and changed files
dncli sites publish example.com ./dist --delete    # also remove files not in ./dist

Files go to /home/site<NNNNN>/domains/<domain>/public_html. .git/ is never uploaded; --exclude leaves out more (repeat it). You need rsync locally and on the server.

Release mode. --release switches a site to versioned uploads: each publish goes into public_html/releases/<timestamp>/ (unchanged files are hard links to the previous release, so only changes are transferred) and the public_html/current symlink switches to it in one step, so visitors never see a half-finished upload. dncli points the site's document root into current through the API, e.g. /public becomes /current/public. After that every publish makes a release; --keep (default 5) sets how many stay.

dncli sites publish example.com ./dist --release   # switch, asks first
dncli sites releases example.com                   # list releases
dncli sites rollback example.com                   # back to the previous one
dncli sites publish example.com ./dist --no-release  # back to plain mode

Every release starts from your folder alone: files the site writes into its own folder (uploads, caches) are not carried over. Switching mode changes the live site, so dncli asks first (--yes skips the question); the old mode's files stay on the server, no longer served.

Commands after the upload. --run runs a command on the server in the uploaded folder, such as composer install; repeat it for more, they run in the order given. In release mode the commands run in the new release before it goes live, so a failing command stops the publish and the site keeps serving the previous release. --run-once is for what must happen only once, like a database migration: on a site with several hosts it runs on the first host only, after all --run commands:

dncli sites publish example.com . --exclude vendor/ \
  --run 'composer install --no-dev --optimize-autoloader' \
  --run-once 'php artisan migrate --force'

Sites on several hosts. A site that runs on several hosts (an HA cluster) gets every publish on all of them: dncli uploads to and runs the commands on every host first, and only then switches them, so the hosts serve different releases only for the moment the switches take. rollback switches every host too. --host limits a command to one of them.

From a CI pipeline. A pipeline has no terminal, so ssh cannot ask for a password or whether to trust a host it has not seen before. Give the pipeline an SSH key that is attached to the site (attach it once with dncli sites keys attach-local example.com --key deploy.pub), the hosts' keys in known_hosts and the API key in DN_API_KEY:

mkdir -p ~/.ssh && ssh-keyscan web01.example.com >> ~/.ssh/known_hosts
dncli sites publish example.com . --run 'composer install --no-dev'

Managing DNS

dncli dns zones list
dncli dns zones show example.com
dncli dns records list example.com
dncli dns records set example.com www A 192.0.2.1 --ttl 3600
dncli dns records delete example.com www A

Anywhere a zone is expected you may pass the service id of a domain instead of its name, so the ids from dncli domains list work here too:

dncli dns records list 42

An id always means that domain's own zone. A delegated subzone such as foo.example.com has no domain service of its own, so address it by name.

Moving a zone from another provider

dncli dns transfer copies a zone from your current DNS provider into DevNomads. It reads the records at the source (never writes there), shows you the changes, and applies them after confirmation:

dncli configure --provider transip       # store source credentials
dncli dns transfer --from transip --zone example.com --dry-run
dncli dns transfer --from transip --zone example.com

Supported source providers: TransIP and AuroraDNS. The zone must already exist at DevNomads; register or transfer the domain in the portal first.

Multiple accounts

Store each account as a named profile and select it per command or per shell:

dncli configure --profile acme
dncli services list --profile acme
export DN_PROFILE=acme

Manage stored profiles:

dncli configure list                 # profiles, with keys masked
dncli configure set-key acme         # replace a profile's API key
dncli configure delete acme          # remove a profile

set-key --stdin reads the new key from standard input, and delete --yes skips the question, for use in scripts.

Scripting

Output is a human-readable table on a terminal and JSON when piped, so pipelines get parseable output without any flags; --out table|json|csv|tsv forces a specific format. Data goes to stdout, everything else (warnings, prompts, status messages) to stderr, so dncli ... | jq . is always safe.

The csv and tsv formats use the same columns as the table view, so dncli servers list --out csv is ready for a spreadsheet.

List tables show a focused set of columns: fields that are empty for every row, and nested collections (a server's IPs, a container's instances, a mailbox list) are left out of the overview. Use <group> show <id> or --out json for the complete record.

To pick exactly the columns you want, pass --columns (-c) a comma-separated list, e.g. dncli services list -c entity,started_at. It applies to every format, projecting json and csv/tsv to just those fields, and reports an error on an unknown column name.

Commands that take a service id also accept a unique entity name and resolve it for you, so dncli domains show example.com works as well as dncli domains show 1234. Clients, SSH keys, clusters, nameserver groups, hypervisors, database users and volumes take a name too, as an argument or an option: dncli databases permissions create stelling_bg25 --user-id stelling. The help of each such option says which field it matches. Names match regardless of case. A purely numeric value is always treated as an id; a name that matches more than one entity is rejected, so pass the id when a name is not unique.

Every command that changes something takes --dry-run: it resolves names to ids and prints the request it would send, without sending it (secrets masked).

Passwords stay off the command line with --password -, which reads the password from stdin, or --generate-password, which creates a strong one and prints it once on stderr.

List options on update commands (--alias, --backend) replace the whole list; --add-alias and --remove-alias change one entry and keep the rest.

Some changes run in the background: creating a site, server, proxy or domain, for example, queues one or more jobs in a batch. Such a command prints the queued jobs and returns right away; add --wait to follow the batch until every job has finished and see how each one ended. With --wait the exit status is 0 only when every job completed (1 when a job failed, 7 when --timeout ran out). You can look a batch up later with dncli jobs batches show <batch_id>.

The exit status is 0 when the API accepted the request, so dncli ... && next-step is safe in scripts. A failure says what kind it is:

Exit Meaning
1 other errors, e.g. a background job failed
2 wrong command, option or value, or --yes needed
3 not found (404, or no entity with that name)
4 API key missing or rejected, or no permission
5 the API rejected the request (validation), or a name is ambiguous
6 rate limited, server error or network failure: retry later
7 --wait timed out; the jobs keep running

When output is JSON and stderr is not a terminal, the error is one JSON line on stderr, e.g. {"error": {"message": "...", "kind": "invalid", "exit": 5, "status": 422}}; option parsing errors (exit 2) stay plain text. Every command takes --timeout <seconds> (default 300) for how long to wait for the API, including the time spent waiting on --wait.

In CI and pipelines, skip the credentials file and pass the key via the environment:

export DN_API_KEY=...        # beats any stored profile
dncli services list | jq -r '.[].entity'

AI agents

dncli ships with a skill that teaches AI coding agents how to use it safely: where ids come from, what costs money or deletes data, and to ask before changing anything. It works with Claude Code, Codex, Gemini CLI, GitHub Copilot, Cursor and OpenCode:

dncli skill install                      # every agent found on this machine
dncli skill install --agent codex        # a specific agent; repeat for more
dncli skill install --project            # into the current project instead

Run it again after upgrading dncli to update the skill; dncli skill show prints it. A copy an older dncli installed is replaced without asking; a copy someone edited is replaced only after one confirmation for all of them. When an installed copy is older than your dncli, dncli says so (at a terminal, at most once a day, like the update notice).

Certificates

dncli issues Let's Encrypt certificates using the DNS-01 challenge:

dncli certs issue example.com -d www.example.com --wildcard

The first argument is the primary domain (the certificate CN); add extra names (SANs) by repeating --san/-d. --wildcard/-w is a shortcut that adds *.<domain> as a SAN - a wildcard is never accepted as the CN itself. Every name must live in one of your DevNomads DNS zones, and that zone must be delegated to the DevNomads nameservers (one.dns.infrapod.nl, two.dns.infrapod.nl, three.dns.infrapod.eu) - otherwise issuance is refused, since the DNS-01 challenge records would not be visible to the CA.

The certificate is always written to ~/.config/dncli/certs/<domain>/ as cert.pem, fullchain.pem, chain.pem, and privkey.pem (0600). Pass --out <file> to additionally export a single PEM bundle of the key, the certificate, and the full chain (intermediate plus any cross-signed roots), in that order. Add -v/--verbose for detailed ACME progress.

Keys are ECDSA P-384 by default. Pick another with --key-type (ecdsa256, ecdsa384, ecdsa521, rsa2048, rsa4096).

Let's Encrypt is the certificate authority by default. Pass --provider zerossl to use ZeroSSL instead. ZeroSSL requires External Account Binding credentials (create an EAB key pair in the ZeroSSL dashboard under Developer > EAB Credentials), supplied with --eab-kid and --eab-hmac-key or the DN_ZEROSSL_EAB_KID and DN_ZEROSSL_EAB_HMAC_KEY environment variables:

dncli certs issue example.com --provider zerossl \
  --eab-kid <kid> --eab-hmac-key <hmac>

--staging (the Let's Encrypt staging CA) applies only to the letsencrypt provider. certs renew takes the same --provider and EAB options.

Each CA gets its own ACME account: the key lives in ~/.config/dncli/acme/ as account.pem for Let's Encrypt production and account-<provider>.pem for ZeroSSL and the staging CA.

Re-running certs issue is a no-op while the existing certificate is still valid for more than 21 days; pass --force to re-issue anyway.

List what you have issued and re-export any of them - as a PEM bundle or a PKCS#12 (.pfx) file - without re-issuing. certs list includes a provider column showing the issuing CA (recorded at issue time, or inferred from the certificate's issuer for older certificates):

dncli certs list
dncli certs export example.com --out bundle.pem    # omit --out to print
dncli certs export example.com --format pfx --out bundle.pfx
dncli certs export example.com --format pfx --out bundle.pfx --passphrase secret

The .pfx is unencrypted unless you pass --passphrase (alias --password). Both bundle formats carry the same items: key, certificate, and the full chain. The chain includes the cross-signs: with Let's Encrypt's current hierarchy the path to a trusted root runs through the intermediate (e.g. YE2), Root YE (cross-signed by ISRG Root X2) and ISRG Root X2 (cross-signed by ISRG Root X1).

dncli certs delete <domain> removes a stored certificate and its private key from disk (after confirmation; --yes skips it). By default it only deletes the local files; add --revoke to also revoke the certificate at the CA that issued it (the files are kept if revocation fails).

A dehydrated-compatible DNS-01 hook ships as dncli-dns-hook:

# dehydrated/config
CHALLENGETYPE="dns-01"
HOOK="dncli-dns-hook"

License

MIT.

Metadata

Release files for devnomads-cli 0.17.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for devnomads-cli 0.17.4
File Size Uploaded Provenance Actions
devnomads_cli-0.17.4.tar.gz 134.1 kB Without provenance Details for devnomads_cli-0.17.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for devnomads-cli 0.17.4
File Interpreter ABI Platform Actions
devnomads_cli-0.17.4-py3-none-any.whl Python 3 none any Details for devnomads_cli-0.17.4-py3-none-any.whl

Total release size: 228.0 kB

Release files / devnomads_cli-0.17.4.tar.gz

Download URL devnomads_cli-0.17.4.tar.gz
Size 134.1 kB
Tags Source
SHA-256 checksum
How to use checksums
11cb8d5fa19c7492d49bad712de85d6ef94555c716f0ef489351f3886bcbfa97
BLAKE2b-256 checksum
How to use checksums
fa0dd75470de50089306fb39a930ab17f053c6006892a67a56ba3a34da650438
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Alpine Linux","version":"3.23.6","id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / devnomads_cli-0.17.4-py3-none-any.whl

Download URL devnomads_cli-0.17.4-py3-none-any.whl
Size 93.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
33d8013d1bd4b3b30f5bcdc748cdecfc087bda9515d2dd9447578129917b3b44
BLAKE2b-256 checksum
How to use checksums
267acf2156564115220e90774dc805f8ff68d7a513ec95fbd1f89afb17ede0b6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Alpine Linux","version":"3.23.6","id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for devnomads-cli 0.17.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.17.4 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page