The command line: `hostbrid`

What you get: doing what the panel does by typing one line. Create a site, change its PHP, add a DNS record or list your mailboxes without opening the browser — and, above all, put that inside a script or a pipeline.

It is a single file and there is nothing to install: if you have Python 3, it works.

Before you start

You need an API key. You create it in the panel, under Account ‣ AI keys, and it is shown only once. If you do not have one yet, see The API, for automating your account — the first part explains how it is created and what permissions it carries.

Getting it onto your machine

curl -o ~/bin/hostbrid https://my.hostbrid.com/cli/hostbrid.py
chmod +x ~/bin/hostbrid

Check that it responds:

hostbrid --version

Log in

hostbrid login

It asks you for the key and checks it before saving it, so if it tells you the key is ready, it is ready. It is stored in ~/.config/hostbrid/config.json, with permissions so that only you can read it.

To log out, hostbrid logout. Careful: that deletes it from this machine, but the key is still valid. To really kill it you have to revoke it in the panel.

What you will use most

hostbrid whoami                 # de qué cuenta es esta clave
hostbrid sites list             # tus sitios
hostbrid sites show 12          # uno, con todo su detalle
hostbrid dns-zones list         # tus zonas de DNS
hostbrid mailboxes list         # tus buzones

Every command follows the same pattern:

hostbrid <recurso> <acción> [id] [campo=valor ...]

The actions are list, show, create, update and delete. The resources are the same ones you see in the API reference: sites, domains, databases, dns-zones, dns-records, mailboxes, mail-aliases, ftp-accounts, ssl-certificates and a few more. You see them all with hostbrid --help.

Creating things

Data goes in as campo=valor, with no quotes and no braces:

hostbrid sites create domain=ejemplo.com php_version=8.3
hostbrid dns-records create zone=4 name=www type=A value=203.0.113.10

To change something, pass only the field that changes — everything else stays as it is:

hostbrid sites update 12 php_version=8.4

Note

Creating, changing and deleting need your key to hold those permissions, and a newly created key only reads. If it replies that a permission is missing, the reply tells you which one: ask for it in a ticket.

Delete

hostbrid sites delete 12

Before deleting, it shows you what you are about to delete and asks you to type the exact name. It is not a ¿seguro? [s/N]: that one gets a yes without anybody reading it.

There are three things you cannot delete from here, not even with confirmation — your customer record, your plan and your white label. That deletion cannot be undone with another command, so you do it in the panel, with your eyes on it.

Inside a script or a pipeline

Two things make this work well under automation:

The key is passed in an environment variable, with no configuration file:

export HOSTBRID_TOKEN=nxp_tu_clave
hostbrid sites list

Standard output carries the data and nothing else. Warnings and errors go to standard error, so you can pipe straight through without filtering anything:

hostbrid sites list --json | jq -r '.results[].domain'

And to delete without being asked — because in a pipeline there is nobody to answer — you have to say so explicitly:

hostbrid sites delete 12 --si

If you forget the --si, it does not delete and it tells you so. That is deliberate: we would rather a script failed than deleted something nobody was going to look at.

When the command does not exist yet

If the API has something this program does not know how to call yet:

hostbrid api GET sites/12/
hostbrid api POST databases/ name=mitienda site=12

That way you are not left waiting for a new version.

What this program does not do

It does not deploy from git, it does not build anything and it has no “projects” or “environments”. It is a thin lid on top of the API for your sites: everything it does can be done with curl, and everything the API learns, it inherits.

Frequent problems

“The key is not valid (401)”: Either you revoked it, or it was copied wrong. Run hostbrid login again.
“Insufficient permission (403)”: Your key is missing a permission, and the message says which one. You ask for them in a ticket.
“It does not exist, or it is not yours (404)”: The identifier is wrong, or it belongs to another account. The API answers the same way in both cases on purpose: telling them apart would confirm which identifiers exist.
“You have gone over the limit (429)”: Too many requests per minute with that key. Wait and retry.
«command not found: hostbrid» after downloading it: The file is downloaded but it is not executable, or it is not in your PATH. Give it execute permission and call it with its full path the first time.
I don’t want to save the key on the computer: Don’t save it: put it in the HOSTBRID_TOKEN environment variable and skip the login. That’s what you do in a pipeline.
The script is waiting for me when I delete it: The –yes is missing. Without it, it asks for confirmation by keyboard, and in a pipeline there is no one to give it to you.
My jq doesn’t receive anything and the command does work: You are capturing the error output instead of the data. The standard output only goes the data; the warnings go separately, just so this works.
I want to delete my customer profile or my plan and it won’t let me: Those three deletions - customer card, plan and white label - are not made from the terminal on purpose: they are not undone, so they are made in the panel, looking at it.
The command I need does not exist: Use hostbrid api with the method and the path, and you call anything from the API without waiting for a new version of the program.

The command line: hostbrid