hostingctl command reference
Generated from the CLI's own command metadata by hostingctl reference. The repository compares this
page with that output, so it is not edited by hand.
Exit status
Exit status: 0 ok, 1 refused, 2 unusable (bad usage, no token, unreachable API).
Global options
These are the entry point's own, and every command accepts them:
| Flag | Takes a value | What it does |
|---|---|---|
--api-url | yes | The API base URL, including /api/v1 (or HOSTINGCTL_API_URL). |
--token | yes | The bearer token to authenticate with (or HOSTINGCTL_TOKEN). |
--company | yes | The company a company-scoped command is about. |
--client-id | yes | The first-party OAuth client id login signs in with. |
--profile | yes | The named session to use (or HOSTINGCTL_PROFILE); the default one otherwise. |
--json | no | Print the API's own fields as JSON. |
--help | no | This text. |
--version | no | Print the version this copy carries. |
--dry-run | no | Describe the change a write would make, and send nothing. |
--confirm | no | Make the change the command described. |
Commands
whoami
Which account the token belongs to, and what it may do.
Usage: hostingctl whoami
The account the bearer token belongs to, and the capabilities the API reports for it.
The capabilities are the API's own answer; this command derives no rule about permissions.
Subcommands
This command takes no subcommand.
environments
Every environment this account can see in a company.
Usage: hostingctl environments --company <slug>
Every environment the company holds, one line each: its slug, its name and the cluster it runs on.
The API scopes environments to a company, so the company is asked for rather than guessed.
Subcommands
This command takes no subcommand.
company
The companies this account belongs to, their members, activity and brand assets.
Usage: hostingctl company list
hostingctl company show|members|activity --company <slug>
hostingctl company create --name <name> [--slug <slug>]
hostingctl company update --company <slug> --name <name>
hostingctl company member <user-uuid> --company <slug>
hostingctl company add-member --company <slug> --email <email> --name <name> --role <admin|member>
hostingctl company member-role <user-uuid> --company <slug> --role <admin|member>
hostingctl company remove-member <user-uuid> --company <slug>
hostingctl company activity [<activity-uuid>] --company <slug>
hostingctl company logo|favicon <set --image-file <path>|remove> --company <slug>
hostingctl company invitations|invite|cancel-invitation|invitation-preview|invitation-accept …
list The companies this account belongs to, with its role in each.
show One company and its brand assets.
create Create a company. Its slug is permanent.
update Rename it.
members Who belongs, with the role and the date they joined.
add-member Invite an address into the company with a role.
activity The company's retained activity log, or one entry.
The writes (create, update, add-member, member-role, remove-member and the asset and invitation
commands) need --confirm; --dry-run describes the change without sending it.
Flags
| Flag | Takes a value | What it does |
|---|---|---|
--name | yes | The company's own name, or the name an invited person is given. |
--slug | yes | The permanent slug a new company is created with. |
--email | yes | The address an invitation is sent to. |
--role | yes | The role a member holds: admin or member. |
--image-file | yes | The file holding the logo or favicon to upload. |
--token-file | yes | The private file holding the invitation token being accepted. |
--token-stdin | no | Read the invitation token from standard input instead of a file. |
Subcommands
list, show, create, update, members, member, add-member, member-role, remove-member, activity,
logo, favicon, invitations, invite, cancel-invitation, invitation-preview, invitation-accept
environment
Create an environment, or read one in detail with its profile coverage, databases and writes.
Usage: hostingctl environment create --company <slug> --name <name> [--slug <slug>] [--package <key>]
hostingctl environment show|profile <uuid> --company <slug>
hostingctl environment reconcile <uuid> --company <slug>
hostingctl environment scale <uuid> --company <slug> [--cpu <millicores>] [--memory <mib>]
hostingctl environment portable <export|preview|prepare|confirm> <uuid> --company <slug> [--file <path>]
hostingctl environment configuration <show|preview|save|apply> <uuid> --company <slug> [--file <path>]
hostingctl environment secret <write|import|local> <uuid> --company <slug> …
hostingctl environment databases|database <uuid> … --company <slug>
create Create an environment from a platform package; the platform chooses the placement.
show One environment in detail, including the status the listing does not carry.
profile Whether the shared catalog covers the profile this environment adopted, and which keys are short.
reconcile Ask the platform to apply this environment's recorded desired state again.
scale Set every workload's CPU/memory requests, keeping the existing request-to-limit headroom.
portable Export, preview, draft and confirm this environment's portable YAML pattern.
configuration Read, review, draft and apply this environment's YAML configuration.
secret Set declared configuration secret values through the write-only control, or write the
declarations' local development values for a local run.
databases List the environment-owned databases, declare one, replace who may consume it, or retire
one while retaining its data and its backups.
The writes (create, reconcile, scale, portable prepare/confirm, configuration save/apply, secret write/import,
database create/bind/retire) need --confirm; --dry-run describes the change without making it.
`secret local` is the one exception and is a read: it writes each declaration's local development value - a
development default such as `password`, not a credential - into an env file for a local run, names the declared
secrets that have none, and reads nothing from the platform's secret store. It saves to --out at mode 600 or prints
to standard output, and it changes nothing on the platform, so it needs no --confirm.
Flags
| Flag | Takes a value | What it does |
|---|---|---|
--name | yes | The environment's own name. |
--slug | yes | The slug the new environment is created with. |
--package | yes | The platform package the environment is created from. |
--cpu | yes | The CPU request every workload gets, in millicores. |
--memory | yes | The memory request every workload gets, in mebibytes. |
--file | yes | The file holding a configuration document or a portable pattern. |
--out | yes | The file a portable export is written to. |
--bindings | yes | The file holding the authorized targets a portable pattern binds to. |
--selection | yes | The file holding the selected source a portable pattern names. |
--key | yes | The declared secret key or database configuration key. |
--value-source | yes | Where a secret value comes from: file, stdin or generate. |
--value-file | yes | The private file a secret value is read from. |
--value-stdin | no | Read a secret value from standard input instead of a file. |
--replace | no | Rotate a value that is already set. |
--application-uuid | yes | The application a configuration change is about. |
--apply | no | Apply the reviewed configuration instead of only drafting it. |
--engine | yes | The database engine: mariadb, postgres or mysql. |
--bind | yes | The comma-separated workload uuids that may consume a database. |
--clear-bindings | no | Take every consumer away from a database. |
--digest | yes | The review digest the recorded change is made against. |
--generation | yes | The environment generation the change is recorded against. |
--agreement | yes | The agreement uuid that prices the extra retention. |
--extra-days | yes | How many extra retention days are bought. |
--effective-at | yes | The instant the extra retention starts. |
--hostname | yes | The name the environment serves. |
--workload | yes | The workload the name is served by. |
--intended | yes | Whether the name is one the environment intends to serve: on or off. |
--fall-back-to-generated | yes | Whether a served name falls back to a generated one: on or off. |
--target | yes | What a redirect points at: an application or a fixed address. |
--mode | yes | Whether the redirect is temporary or permanent. |
--destination | yes | The fixed address a redirect points at. |
--enabled | yes | Whether the tool is enabled for this environment: on or off. |
--running | yes | Whether the service is running: on or off. |
--locked | yes | Whether the service is locked against removal: on or off. |
--replicas | yes | How many replicas the service runs. |
--sign-in | yes | Whether the sites require sign-in: on or off. |
--audience | yes | The identity audience the sites trust. |
--email | yes | The address a site sign-in invitation is sent to. |
Subcommands
create, show, profile, reconcile, scale, portable, configuration, secret, databases, database,
retention, retention-set, database-show, database-reveal, tuning, domains, domain-add, domain-verify,
domain-check-routing, domain-intended, domain-primary, domain-remove, redirects, redirect-set,
redirect-remove, tools, shared-runtime, shared-runtime-adopt, shared-runtime-release, shared-app,
shared-app-adopt, shared-app-release, shared-adopt, database-exports, database-export-create,
database-export-download, database-export-remove, release-bundle, service-add-review, service-add,
service-runtime, service-protect, service-retirement, service-retire, site-access, site-access-set,
site-users, site-user
application
One application's build, deployment, runs, rename and removal journey.
Usage: hostingctl application list <environment-uuid> --company <slug>
hostingctl application show <environment-uuid> <workload-uuid> --company <slug>
hostingctl application deployment <environment-uuid> <workload-uuid> --company <slug>
hostingctl application build <environment-uuid> <workload-uuid> --company <slug> [--source <selection-uuid>]
[--idempotency-key <key>]
hostingctl application deploy <environment-uuid> <workload-uuid> <release-uuid> --company <slug>
hostingctl application runs <environment-uuid> <workload-uuid> --company <slug>
hostingctl application run-log <environment-uuid> <workload-uuid> <run-name> --company <slug>
hostingctl application schedule-run <environment-uuid> <workload-uuid> <schedule-key> --company <slug>
hostingctl application runtime <environment-uuid> <workload-uuid> --company <slug> --mode <stop|start|restart>
hostingctl application update <environment-uuid> <workload-uuid> --company <slug> --label <label>
hostingctl application removal <environment-uuid> <workload-uuid> --company <slug>
hostingctl application remove <environment-uuid> <workload-uuid> --company <slug>
list|show The applications in an environment, and one in detail.
deployment The running, requested and interrupted builds and releases of one application.
build Queue a build of the application's applied configuration from a source selection.
deploy Make an existing release the one the application runs.
runs|run-log The process run history, and one run's own output.
schedule-run Run a declared schedule now, beside the schedule's own runs.
runtime Stop, start or restart the application's desired runtime.
update Rename an application's label only.
removal|remove Review, then request, the withdrawal of one application and its runtime.
The writes (build, deploy, schedule-run, update, remove, runtime) need --confirm; --dry-run describes
the change without sending it. remove re-reads the removal review to send its inventory digest; the
retained-data retirement of an environment-owned database is a separate, later decision.
Flags
| Flag | Takes a value | What it does |
|---|---|---|
--type | yes | The application recipe to run. |
--name | yes | The application's own name. |
--replicas | yes | How many copies to run; one by default. |
--cpu-request | yes | The CPU request the container is given, in millicores. |
--cpu-limit | yes | The CPU limit the container is given, in millicores. |
--memory-request | yes | The memory request the container is given, in mebibytes. |
--memory-limit | yes | The memory limit the container is given, in mebibytes. |
--label | yes | The label the application is listed and renamed under. |
--hostname | yes | The name visitors should reach the application at. |
--source | yes | The workload a route is served from. |
--target | yes | The workload a route is sent to. |
--path | yes | The path a route answers on. |
--domain | yes | The domain a route is served under. |
--route | yes | The route the canonical answer is read from. |
--canonical | yes | Whether the route is the canonical one: on or off. |
--enabled | yes | Whether the HTTP cache is enabled: on or off. |
--fresh | yes | How long a fresh response stays fresh, in seconds. |
--background | yes | How long a background refresh runs, in seconds. |
--browser | yes | How long a browser may reuse a cached response, in seconds. |
--reset | yes | Whether the cache is reset on every request: on or off. |
--selection | yes | The selected repository a source is bound to. |
--branch | yes | The branch the bound source is built from. |
--tag | yes | The tag the bound source is built from. |
--auto-deploy | yes | Whether a new commit deploys by itself: on or off. |
--idempotency-key | yes | The key a retried build is recognised by, so it is not queued twice. |
--mode | yes | What the runtime should be doing: stop, start or restart. |
--database | yes | The SQL dump the staged import is built from. |
--archive | yes | The site's files as one ZIP. |
--directory | yes | The site's files as a directory. |
--source-url | yes | The old address stored WordPress URLs are rewritten from. |
--confirmation | yes | The text the review asks the person to type. |
--sign-in | yes | Whether the application requires sign-in: on or off. |
--audience | yes | The identity audience the application trusts. |
--email | yes | The address a site sign-in invitation is sent to. |
Subcommands
list, show, deployment, create, build, deploy, runs, run-log, schedule-run, schedule-suspend,
schedule-resume, runtime, update, removal, remove, routes, route-add, route-remove, build-log,
build-retry, build-cancel, source-bind, source-unbind, recovery-review, recovery-confirm, import,
import-upload, import-discard, url-repair-preview, url-repair-confirm, site-access, site-access-set,
site-access-rotate, site-users, site-user, cache, cache-set, cache-purge, canonical, updates,
updates-pause, updates-resume, administrator, administrator-reset, administrator-reveal, recovery-status,
recovery-retry, recovery-cancel
cancellation
Cancel an environment: read it, request it, withdraw it, delete now, or re-confirm its scope.
Usage: hostingctl cancellation show <environment-uuid> --company <slug>
hostingctl cancellation request <environment-uuid> --company <slug>
--reason <text> --timing <at-service-end|now> --generation <n> [--effective-at <iso>]
hostingctl cancellation withdraw <environment-uuid> <cancellation-uuid> --company <slug>
hostingctl cancellation delete-now <environment-uuid> <cancellation-uuid> --company <slug> --generation <n>
hostingctl cancellation purge <environment-uuid> <cancellation-uuid> --company <slug> --generation <n>
hostingctl cancellation reconfirm <environment-uuid> <cancellation-uuid> --company <slug>
--generation <n> --digest <review-digest>
show The recorded cancellation, the review of what deleting removes, any recorded refusal, and what this
account may do. A read.
request Ask to cancel. --timing at-service-end keeps serving until --effective-at; --timing now
DESTROYS the environment at the confirmation and takes no date.
withdraw Close the request while it can still be withdrawn; service that had ended starts again.
delete-now DESTROY the environment now, whatever date was agreed before.
purge DESTROY the environment AND its retained backups now, instead of waiting out retention.
reconfirm Replace the approved deletion scope with the scope as it now stands; deletion continues.
--generation is the environment's CURRENT generation, from `environment show` — service end advances it,
so a value read from the cancellation would be stale. --digest is the review's inventoryDigest.
Every write needs --confirm; --dry-run describes the change and sends nothing at all.
delete-now, and request with --timing now, destroy the environment, its applications, its databases and its
volumes; the retained restore points are the only way back. purge destroys those too, so nothing survives.
Flags
| Flag | Takes a value | What it does |
|---|---|---|
--reason | yes | The reason the cancellation is requested with. |
--timing | yes | When the service ends: at-service-end, or now to destroy at the confirmation. |
--effective-at | yes | The ISO-8601 date service ends, when the timing is at-service-end. |
--generation | yes | The environment's current generation, as environment show prints it. |
--digest | yes | The review's inventory digest, which approves the scope being confirmed. |
Subcommands
show, request, withdraw, delete-now, purge, reconfirm
system
Ask this system what it sees left on the cluster it manages.
Usage: hostingctl system orphans
hostingctl system version
orphans What this system sees left on the cluster it manages, and whether cleanup is allowed.
version The API's own root answer, which is the cheapest way to prove it is reachable.
Subcommands
orphans, version
deletion-lock
Arm or clear the client's deletion lock on an environment, or on one application.
Usage: hostingctl deletion-lock environment <environment-uuid> --company <slug> --generation <n> [--unlock]
hostingctl deletion-lock service <environment-uuid> <workload-uuid> --company <slug> --generation <n> [--unlock]
environment Arm the lock that stops this environment being deleted; --unlock clears it again.
service The same lock for one application, addressed by its workload uuid because a type slug
cannot tell two applications of one type apart.
The lock stops a deletion being accepted, and it stops a teardown that has not started. It cannot undo
work already executing: a teardown in progress, or a retirement already recorded, finishes. It deletes
nothing by itself, it is not consent or a safety review, and it does not expire. The environment lock
stops every delete inside it too, including an application that carries its own lock.
--generation is the environment generation `environment show` prints; the API refuses one that has moved.
Both directions are company.update — the lock is the client's own, and no platform permission is involved.
Arming or clearing it queues no reconcile and advances no generation.
Reading whether a lock is armed needs no command of its own: `cancellation show` lists a locked
environment, and each locked application inside it, as a blocker with the path whose control clears it.
Both commands are writes: --confirm is required, and --dry-run describes the change and sends nothing.
Flags
| Flag | Takes a value | What it does |
|---|---|---|
--generation | yes | The environment generation the lock is recorded against. |
--unlock | no | Clear the lock instead of arming it. |
Subcommands
environment, service
access
Who may reach one environment, and the writes that change it.
Usage: hostingctl access <users|logins|recover|user> <environment-uuid> --company <slug>
users Who may reach the environment, their state and their key counts.
logins Recent logins, as the platform read them from the environment.
recover Reconcile this environment's access from its recorded intent.
user add <uuid> --username <login> --name <name> --public-key-file <path> [--key-name <name>]
user remove <uuid> --access-user <uuid>
Every write needs --confirm; --dry-run describes the change without sending it.
Flags
| Flag | Takes a value | What it does |
|---|---|---|
--username | yes | The login name the environment's user signs in with. |
--name | yes | The display name of the login or key being changed. |
--key-name | yes | The key's own label, when the key is not named after the login. |
--public-key-file | yes | The file holding the public key to add; it is read, never printed. |
--access-user | yes | The environment's own access user the change is about. |
--user | yes | The platform user a grant is given to. |
--password | yes | Whether password sign-in is offered: on or off. |
--sftp-only | yes | Whether the logins are restricted to SFTP: on or off. |
--enabled | yes | Whether the login may sign in: on or off. |
--read-only | yes | Whether the login is read-only: on or off. |
--password-file | yes | The private file holding the login's new password. |
--password-stdin | no | Read the login's new password from standard input instead of a file. |
Subcommands
users, logins, recover, user, settings, settings-set, grants, grant, un-grant, key, password,
user-show, user-set, received
secret-connection
An environment's connections to a customer's own secret manager.
Usage: hostingctl secret-connection <command> <environment-uuid> [arguments] --company <slug>
list <env> The environment's connections and the providers it may use.
show <env> <connection> One connection as it stands.
add <env> Connect a secret manager. Needs --provider, --endpoint,
--project-id, --remote-environment, --client-id and
(--client-secret-file <path>|--client-secret-stdin).
test <env> <connection> Prove the identity can reach the folder and read its keys.
preview <env> <connection> Which mapped names a refresh would reach, and from where.
link <env> <connection> Map a remote key onto a declared secret name.
Needs --name, --remote-path and --remote-key.
unlink <env> <connection> <ref> Stop supplying one mapped name.
sync <env> <connection> Refresh every mapping now.
rotate <env> <connection> Replace the machine identity. Needs --client-id and
(--client-secret-file <path>|--client-secret-stdin).
revoke <env> <connection> Stop serving new values. Loaded values are retained.
remove <env> <connection> Delete the connection, its mappings and our copy of the identity.
A client secret comes from a private file or stdin and is never taken from an argument or printed.
Every write needs --confirm; --dry-run describes the change without sending it.
Flags
| Flag | Takes a value | What it does |
|---|---|---|
--provider | yes | The secret manager kind. Infisical is supported. |
--endpoint | yes | The provider's API base address. HTTPS only. |
--project-id | yes | The provider project the values live in. |
--remote-environment | yes | The provider's own environment slug, such as production. |
--client-id | yes | The machine identity's client id. |
--client-secret-file | yes | The private file holding the machine identity's client secret. |
--client-secret-stdin | no | Read the client secret from standard input instead of a file. |
--ca-file | yes | A public CA certificate for a customer-hosted instance. |
--name | yes | The declared secret name a mapped key supplies. |
--remote-path | yes | The folder inside the provider holding the key. |
--remote-key | yes | The key's own name inside that folder. |
Subcommands
list, show, add, test, preview, link, unlink, sync, rotate, revoke, remove
keys
The account's personal SSH keys and where each is granted.
Usage: hostingctl keys
hostingctl keys add --name <name> --public-key-file <path> (--current-password-file
<path>|--current-password-stdin)
hostingctl keys remove <key-uuid>
(no arguments) The account's personal SSH keys and where each is granted.
add Add one public key to the account, which needs the current password.
remove Remove it. The grants that used it stop resolving.
A public key is read from a file; the account password comes from a private file or stdin and is never
printed. Both writes need --confirm; --dry-run describes the change without sending it.
Flags
| Flag | Takes a value | What it does |
|---|---|---|
--name | yes | The label the key is listed under. |
--public-key-file | yes | The file holding the public key to add; it is read, never printed. |
--current-password-file | yes | The private file holding the account password the change is made with. |
--current-password-stdin | no | Read the account password from standard input instead of a file. |
Subcommands
add, remove
mailbox
Mail-client setup, fallback recovery address and reset links for one mailbox.
Usage: hostingctl mailbox <setup|instructions|fallback|recovery-link> <email-domain-uuid> <mailbox-uuid> --company
<slug>
hostingctl mailbox recovery <request|verify|reset> [options]
hostingctl mailbox import <preview|confirm> <email-domain-uuid> --company <slug> --format <csv|yaml> --file
<path> [--confirm|--dry-run]
setup Show one mailbox's mail-client settings (IMAP/SMTP, webmail).
instructions Email its setup details to --recipient, or its stored fallback address.
fallback set|remove Set (--address) or remove the mailbox's recovery address.
recovery-link email|copy Issue a reset link; email sends it, copy returns it once to share.
recovery request|verify|reset The public, sign-in-free recovery journey (see below).
Every write needs --confirm; --dry-run describes the change without sending it.
The public recovery token and a new password are read from --<name>-file <path> (mode 600) or
--<name>-stdin, never from an argument, and are never printed.
Flags
| Flag | Takes a value | What it does |
|---|---|---|
--address | yes | The address the fallback is set to, or the address being recovered. |
--recipient | yes | Where the mail-client instructions are sent. |
--destination | yes | The address a copied message is sent to. |
--file | yes | The file holding the mailboxes to create; it is read bounded and never printed. |
--format | yes | The format the import file is written in: csv or yaml. |
--token-file | yes | The private file holding the recovery token being verified or reset. |
--token-stdin | no | Read the recovery token from standard input instead of a file. |
--password-file | yes | The private file holding the new password a recovery sets. |
--password-stdin | no | Read the new password from standard input instead of a file. |
Subcommands
setup, instructions, fallback, recovery-link, recovery, import
email
A company's email service, its attached names, their mailboxes and aliases.
Usage: hostingctl email <show|names> --company <slug>
hostingctl email <mailboxes|aliases> <email-domain-uuid> --company <slug>
hostingctl email mailbox <email-domain-uuid> <mailbox-uuid> --company <slug>
show The service state and whether enrollment is available.
names The attached names with their observed readiness checks.
mailboxes Every mailbox attached to one name.
mailbox One mailbox record.
aliases Every alias attached to one name, with its destinations.
Every read follows every page the API reports. Bulk mailbox creation from a CSV or YAML file is its
own command: hostingctl mailbox-import.
Flags
| Flag | Takes a value | What it does |
|---|---|---|
--address | yes | The granted address one mailbox record is about. |
--local | yes | The local part of the address or alias being created. |
--label | yes | The label an address is listed under. |
--destinations | yes | The comma-separated addresses an alias or mailbox forwards to. |
--hostname | yes | The name to attach to the service. |
--term | yes | The package term uuid the enrolment agrees to. |
--status | yes | The mailbox's own status: enabled or suspended. |
--quota | yes | The mailbox's own quota size. |
--reason | yes | Why the hold is placed: compromise, abuse or operator. |
--mailbox | yes | The one mailbox a hold or a sync account is about. |
--spam-mark-read | yes | Whether junk is marked as read: on or off. |
--spam-threshold | yes | The score above which mail is treated as junk. |
--vacation | yes | Whether the out-of-office reply is on: on or off. |
--vacation-subject | yes | The subject the out-of-office reply carries. |
--vacation-body | yes | The body the out-of-office reply carries. |
--vacation-start | yes | The instant the out-of-office reply starts. |
--vacation-end | yes | The instant the out-of-office reply ends. |
--enabled | yes | Whether the service is enabled: on or off. |
--ends-at | yes | The instant a cancellation takes effect. |
--version | yes | The service version the change is made against. |
--host | yes | The IMAP or SMTP host a sync account reaches. |
--port | yes | The port a sync account reaches. |
--encryption | yes | The transport a sync account uses: tls or starttls. |
--username | yes | The login a sync account connects with. |
--recurrence | yes | How often a sync account syncs: once or until. |
--password-file | yes | The private file holding a sync account's password. |
--password-stdin | no | Read a sync account's password from standard input instead of a file. |
--file | yes | The file holding the sync accounts to add; it is read bounded and never printed. |
Subcommands
show, names, mailboxes, mailbox, aliases, offer, enroll, agree, provision, domain, catch-all,
alias, app-token, send-as, service, dmarc, dmarc-set, blocklist, blocklist-set, import-schema, sync,
hold, add, change, remove, forward, preferences, preferences-set, credential, reset-credential
dns
A managed name's zone, its zone-file export, and the reviewed import write.
Usage: hostingctl dns <zone|export> <domain-uuid> --company <slug>
hostingctl dns import <preview|apply> <domain-uuid> --company <slug> --file <path> [--confirm]
hostingctl dns enable <domain-uuid> --company <slug>
hostingctl dns record <set|remove> <domain-uuid> --company <slug> --file <path>
hostingctl dns dnssec <signed|unsigned> <domain-uuid> --company <slug>
hostingctl dns handover <domain-uuid> --company <slug>
hostingctl dns template <list|show|save|delete|from-zone|preview|apply> … --company <slug>
zone The managed zone and the record sets it publishes.
export The zone as a standard zone file.
import preview Classify the record sets in --file against the served zone; writes nothing.
import apply Preview --file, then record the reviewed sets and queue the apply pass.
enable, record, dnssec, handover The zone's own writes.
template Recorded record-set patterns, and applying one to a zone through its review.
The --file holds one set per line as `name TTL type value`; blank lines and `#` comments are
skipped. The file is read from disk and never printed. Every write needs --confirm; --dry-run
describes the change without sending it.
Flags
| Flag | Takes a value | What it does |
|---|---|---|
--file | yes | The file holding the record sets; it is read bounded and never printed. |
--name | yes | The relative name of one record set. |
--type | yes | The record type of one record set: A, AAAA, CNAME, MX, TXT or SRV. |
--description | yes | What a recorded template is for. |
Subcommands
zone, export, import, template, enable, record, dnssec, handover
domain
The names a company holds: reserve one, read its proof, verify it, or release it.
Usage: hostingctl domain list --company <slug>
hostingctl domain reserve --company <slug> --hostname <hostname>
hostingctl domain show|verify|challenge|release <domain-uuid> --company <slug>
list The names this company holds, with their readiness.
reserve Reserve a name and get the ownership record to publish.
show One name in detail, including its proof and what this account may do with it.
verify Ask the platform to check the ownership proof now.
challenge Re-issue the proof to publish.
release Give the name back, dropping what the platform holds for it.
reserve, verify, challenge and release are writes: they need --confirm, and --dry-run describes the change
without sending it. A reserve or release that costs money is a registrar operation, not this one.
Flags
| Flag | Takes a value | What it does |
|---|---|---|
--hostname | yes | The name to reserve, lower-cased before it is sent. |
Subcommands
list, reserve, show, verify, challenge, release
diagnostics
The platform's own health answer.
Usage: hostingctl diagnostics
The platform's own health: unready environments, incomplete profiles, failed stages and the
environment backups whose captures are not succeeding.
Subcommands
This command takes no subcommand.
backups
Backup states and the newest restore point for one environment.
Usage: hostingctl backups <environment-uuid> --company <slug>
The state of each backup track and when it last succeeded, with the newest restore point across them.
The company's own bucket is reported separately: it is a second copy, written after ours.
Subcommands
This command takes no subcommand.
backup-destination
The company's own bucket that also receives its backups: read it, set it, or remove it.
Usage: hostingctl backup-destination [show] --company <slug>
hostingctl backup-destination set --company <slug> --endpoint <url> --bucket <name> --region <region>
--access-key-id <id> (--secret-key-file <path>|--secret-key-stdin) [--prefix <folder>] [--arm]
hostingctl backup-destination remove --company <slug>
show The company's own destination, and whether copies are being written to it. This is the default.
set Record or replace it. The secret key is read from a private file or stdin, never an argument.
remove Stop using it. Copies already written there are the company's to keep or expire.
The destination is a second copy: the platform's own backup stays authoritative, and our retention promises
cover our copy only. A recorded destination stays disarmed until --arm is passed, so a bucket that is still
being set up never starts receiving copies. Writing needs --confirm; --dry-run describes the change.
Flags
| Flag | Takes a value | What it does |
|---|---|---|
--endpoint | yes | The S3 endpoint the bucket is reached at. |
--bucket | yes | The bucket the copies are written to. |
--region | yes | The region the bucket lives in. |
--access-key-id | yes | The access key id the copies are written with. |
--secret-key-file | yes | The private file holding the secret key, which is never printed. |
--secret-key-stdin | no | Read the secret key from standard input instead of a file. |
--prefix | yes | The folder inside the bucket the copies are written under. |
--arm | no | Start writing copies to the recorded destination. |
Subcommands
show, set, remove
logs
Bounded retained log history for one environment, DNS domain or mail domain.
Usage: hostingctl logs environment|dns|mail|live <uuid> --company <slug>
[--start <iso>] [--end <iso>] [--limit <1..200>]
environment Retained container output for one environment's own workloads.
live The same environment's current container output, as the platform reads it now.
dns Retained operational DNS events for one owned zone.
mail Retained Postfix delivery attempts for one owned mail domain.
Without --start/--end the API answers the most recent default window. The server enforces the
bounded window (at most 6 hours within the last 24) and the 1..200 entry limit; the CLI only
refuses a malformed --limit before asking.
Flags
| Flag | Takes a value | What it does |
|---|---|---|
--start | yes | The ISO-8601 instant the window starts at. |
--end | yes | The ISO-8601 instant the window ends at. |
--limit | yes | How many entries one answer holds, from 1 to 200. |
Subcommands
environment, live, dns, mail
purchases
The company's own purchase record: what it was sold, at what size, and for how long.
Usage: hostingctl purchases --company <slug> --from <iso> --to <iso> [--limit <n>] [--cursor <token>]
The company's own purchase record: what each environment was sold, at what size, and for how long.
--from and --to are the window's instants, ISO-8601, and the window is half-open: --from is included and
--to is not. There is no default window, because a default would be an invented invoice period.
--limit is how many periods one page holds (at most 500). --cursor continues from the nextCursor the
previous page ended with.
The record holds no amounts: a price is a price list times a period, and rating is not this platform's.
Flags
| Flag | Takes a value | What it does |
|---|---|---|
--from | yes | The ISO-8601 instant the window starts at; it is included. |
--to | yes | The ISO-8601 instant the window ends at; it is not included. |
--limit | yes | How many purchase periods one page holds, at most 500. |
--cursor | yes | The nextCursor the previous page ended with. |
Subcommands
This command takes no subcommand.
services
One environment's service inventory and the generation it was observed at.
Usage: hostingctl services <environment-uuid> --company <slug>
One environment's service inventory: the desired and applied generation it was read at, and one
line per service with its state, replicas, reserved allocation and consumers.
Subcommands
This command takes no subcommand.
site-user
The accounts that sign in to a company's sites: list, read, disable or enable.
Usage: hostingctl site-user list --company <slug>
hostingctl site-user show|disable|enable <site-user-uuid> --company <slug>
list The accounts that can sign in to this company's sites, with where each one is assigned.
show One account in detail, including the instances it reaches and its provider state.
disable Stop the account signing in. It stays, and can be enabled again.
enable Let it sign in again.
These are the site identities the identity provider owns; the environment's own SSH logins are `access`.
The two writes need --confirm; --dry-run describes the change without sending it.
Subcommands
list, show, disable, enable, write
login
Sign in and keep the session in a 0600 credential file.
Usage: hostingctl login --api-url <url> --client-id <id> [--profile <name>] [--no-browser]
Signs in with authorization-code/PKCE over a loopback redirect, proves the new token against the API, then
writes the session to a mode 0600 credential file under a 0700 directory. It is a credential file rather than
a keychain, so exclude it from backup and sync tools; what bounds the exposure is that the refresh token is
single-use and expires.
--profile <name> Which named session to write (default: "default", or HOSTINGCTL_PROFILE).
--no-browser Print the authorize URL and accept the callback URL pasted on stdin. For a machine with
no browser of its own: the browser runs elsewhere and cannot reach this host's loopback
listener. Only the registered redirect URI is accepted back.
Flags
| Flag | Takes a value | What it does |
|---|---|---|
--no-browser | no | Print the authorize URL and take the callback URL on stdin, for a machine with no browser. |
Subcommands
This command takes no subcommand.
auth
Who this session is, signing out, the account's own settings, and impersonation.
Usage: hostingctl auth status [--verify] [--profile <name>]
hostingctl auth logout [--profile <name>] [--local]
hostingctl auth login --api-url <url> --client-id <id> [--profile <name>] [--no-browser]
hostingctl auth profile|password|register|forgot-password|reset-password|verify-email …
hostingctl auth closure|picture|notifications …
hostingctl auth impersonate <start|status|stop|list|end> …
status Which session this profile holds, and whether the API still accepts it (--verify).
logout Revoke the session at the API, then remove it from this machine (--local skips the API).
login The same sign-in as `hostingctl login`.
impersonate Start, inspect and end an impersonation session, with its own profile when it is stored.
Everything else here acts on the signed-in account: the profile fields, the password, registration and
recovery, email verification, account closure, the profile picture and notifications.
Writes need --confirm; --dry-run describes the change without making it. Secrets come from
--<name>-file <path> or --<name>-stdin, never from an argument.
Flags
| Flag | Takes a value | What it does |
|---|---|---|
--verify | no | Ask the API whether the stored session is still accepted. |
--local | no | Forget the session on this machine without asking the API to revoke it. |
--no-browser | no | Print the authorize URL and take the callback URL on stdin, for a machine with no browser. |
--name | yes | The name on the account's own profile. |
--email | yes | The address on the account's own profile, or the one a recovery is asked about. |
--image-file | yes | The file holding the profile picture to upload. |
--reason | yes | The reason an account is closed or an impersonation is started. |
--target | yes | The account the impersonation acts as. |
--store-as | yes | The profile name an impersonation session is stored under. |
--minutes | yes | How long the impersonation lasts, in minutes. |
--current-password-file | yes | The private file holding the current account password. |
--current-password-stdin | no | Read the current account password from standard input instead of a file. |
--new-password-file | yes | The private file holding the new account password. |
--new-password-stdin | no | Read the new account password from standard input instead of a file. |
--password-file | yes | The private file holding the password an account is registered with. |
--password-stdin | no | Read the registration password from standard input instead of a file. |
--token-file | yes | The private file holding a recovery or verification token. |
--token-stdin | no | Read the recovery or verification token from standard input instead of a file. |
Subcommands
status, logout, login, profile, password, verify-email, register, forgot-password, reset-password,
closure, picture, notifications, push-token, impersonate
platform
Platform-only decisions: domain claims, the client directory, watching and schema documents.
Usage: hostingctl platform domain show|attest|revoke|transfer <claim-uuid>
hostingctl platform companies | company-add | company-closure | company-close | company-close-accept
hostingctl platform company-activity | company-activity-show
hostingctl platform users | user-closure | user-close | domain-lookup
hostingctl platform alerts | alert-add | alert | alert-test | alert-settings
hostingctl platform github-app | yahoo-feedback | yahoo-feedback-set
hostingctl platform consumer-declarations
hostingctl platform email <command> (see `platform email --help`)
hostingctl platform seed <command> (see `platform seed --help`)
hostingctl platform schema --kind <hosting|portable-site> [--version <v>]
hostingctl platform purchases --from <iso> --to <iso> [--company <slug>] [--limit <n>] [--cursor <token>]
domain One name's claim: the live ownership decision and its recorded routing.
companies|users The client directory, and one company's audit trail with one entry's changes.
company-closure|user-closure What closing a company or an account would remove and keep.
alerts|alert-*|github-app|yahoo-feedback* Platform watching: who is told, and what is polled.
consumer-declarations What the platform composes for each consumer it serves: roles, delivered
environment names, the migration need and the consumers it cannot describe.
email Mail monitoring: deliverability, blocklists and postmaster reputation.
seed Prepared content: definitions, versions and their per-cluster placements.
schema The published documents a client authors against, by version.
purchases What every environment was sold, at what size, and for how long.
These are platform-only operations; the API refuses a company or impersonated token. Every write needs
--confirm, and --dry-run describes the change without making it.
Flags
| Flag | Takes a value | What it does |
|---|---|---|
--kind | yes | Which published document is asked for: hosting or portable-site. |
--version | yes | The document version asked for, or the seed version being changed. |
--hostname | yes | The name the claim or the company record is about. |
--reason | yes | Why the decision was taken, recorded with it. |
--state | yes | The state the client directory is filtered by. |
--search | yes | The text the directory is searched for. |
--name | yes | The name the record being created is given. |
--slug | yes | The slug the record being created is given. |
--admin-email | yes | The address the company's administrator is recorded with. |
--event | yes | The directory event kind that is asked for. |
--log | yes | The directory log entry that is asked for. |
--email | yes | The address an alert or a rule is sent to. |
--enabled | yes | Whether the alert or the consumption is enabled: on or off. |
--monitoring | yes | Whether the monitoring rule is on: on or off. |
--mailbox | yes | The postmaster mailbox the monitoring watches. |
--acknowledged | yes | Whether the incident is acknowledged: on or off. |
--mute-hours | yes | How long the postmaster stays muted, in hours. |
--workload-type | yes | The workload type the seed is prepared for. |
--scope | yes | Who the seed is prepared for: platform or company. |
--preparation-mode | yes | How the seed or its placement is prepared. |
--description | yes | What the prepared word or record is for. |
--word | yes | The word the generated hostname vocabulary holds. |
--position | yes | Where the word sits: adjective or noun. |
--source-release | yes | The release the seed version is built from. |
--source-commit | yes | The commit the seed version is built from. |
--source-checksum | yes | The checksum the source is verified against. |
--recipe-revision | yes | The recipe revision the seed version is built from. |
--runtime-image-digest | yes | The runtime image digest the seed version pins. |
--content-contract | yes | The file holding the content contract the version declares. |
--release | yes | The release the seed version is published with. |
--cluster | yes | The cluster the placement is made on. |
--storage-class | yes | The storage class the placement is adopted with. |
--backing-image | yes | The backing image the placement runs from. |
--expected-checksum | yes | The checksum the adopted placement is verified against. |
--minimum-size | yes | The smallest size the placement is prepared at, in mebibytes. |
--basis | yes | The basis the purge decision is made on. |
--evidence | yes | The evidence reference the purge decision carries. |
--expires-at | yes | The instant the recorded decision expires. |
--observed-at | yes | The instant the state was observed at. |
--parent-zone | yes | The parent zone the record sits under. |
--provider-account | yes | The provider account the record belongs to. |
--provider-zone | yes | The provider zone the record belongs to. |
--generation | yes | The generation the recorded decision is made against. |
--from | yes | The ISO-8601 instant the purchase window starts at. |
--to | yes | The ISO-8601 instant the purchase window ends at. |
--limit | yes | How many purchase periods one page holds. |
--cursor | yes | The nextCursor the previous page ended with. |
Subcommands
domain, companies, company-add, company-closure, company-close, company-close-accept, company-activity,
company-activity-show, users, user-closure, user-close, domain-lookup, alerts, alert, alert-add,
alert-test, alert-settings, github-app, yahoo-feedback, yahoo-feedback-set, consumer-declarations, email,
seed, schema, purchases
realm
One environment's deployment realm: observe it, adopt it, retry it, record an audience.
Usage: hostingctl realm show <environment-uuid> --company <slug>
hostingctl realm adopt <environment-uuid> --custd-company <uuid> --owning-user <uuid>
--registration-policy <invite_only|open> --expected-revision <n>
[--login-paused] [--audiences <path>]
hostingctl realm record <environment-uuid> --company <slug> --custd-company <uuid> --owning-user <uuid>
--registration-policy <invite_only|open> --expected-revision <n>
[--login-paused] [--audiences <path>]
hostingctl realm retry <environment-uuid> --company <slug>
hostingctl realm audience <environment-uuid> <workload-uuid> --company <slug> --audience <name>
show The environment's recorded deployment-realm convergence.
adopt Record the realm allocation intent for one environment (platform-addressed).
record Record the same intent through the company's own surface, with no staff attestation.
retry Reconcile the environment's realm from its recorded intent.
audience Record one application workload's realm audience name.
The realm state `show` prints is recorded convergence, never provider health, a working
sign-in or released routes. Every write needs --confirm; --dry-run describes the change
without sending it.
Flags
| Flag | Takes a value | What it does |
|---|---|---|
--custd-company | yes | The CustD company the environment's realm is allocated from. |
--owning-user | yes | The user the recorded realm intent is owned by. |
--registration-policy | yes | The registration policy to record: invite_only or open. |
--expected-revision | yes | The revision the record is made against, so a stale read is refused. |
--login-paused | no | Record the realm with logins paused. |
--audiences | yes | The file holding the audiences to record, as the API's own JSON array. |
--audience | yes | The audience name one workload is recorded under. |
Subcommands
show, adopt, record, retry, audience
repository
GitHub connections for application source: connect, select, resync or revoke.
Usage: hostingctl repository list --company <slug>
hostingctl repository connect --company <slug>
hostingctl repository complete (--callback-file <path>|--callback-stdin) --company <slug>
hostingctl repository repositories <connection-uuid> --company <slug>
hostingctl repository select <connection-uuid> --company <slug> --repository <id> [--branch <name>]
[--config-path <path>]
hostingctl repository resync <connection-uuid> <selection-uuid> --company <slug>
hostingctl repository revoke <connection-uuid> --company <slug>
connect Start the GitHub handoff. It prints the URL to open; nothing is stored by that call.
complete Finish it with the callback GitHub redirects to, pasted from a private file or stdin.
repositories The repositories the connection may offer.
select Choose one, which answers the selection uuid a source bind names.
resync Re-read the selected repository's source now.
The callback carries a one-time code, so it is never taken from an argument or printed.
The writes need --confirm; --dry-run describes the change without sending it.
Flags
| Flag | Takes a value | What it does |
|---|---|---|
--repository | yes | The repository the connection is asked to offer. |
--branch | yes | The branch the selected repository is bound to. |
--config-path | yes | The path inside the repository the configuration is read from. |
--callback-file | yes | The private file holding the callback URL GitHub redirected to. |
--callback-stdin | no | Read the callback URL from standard input instead of a file. |
Subcommands
list, connect, complete, repositories, select, resync, revoke
registrar
A name's registrar state, its price and the writes a customer consents to.
Usage: hostingctl registrar
<status|history|quote|register|renew|transfer|supersede-transfer|autorenew|nameservers|setup-intent|refresh>
<domain-uuid> --company <slug>
status The registrar binding, latest operation and check freshness.
history The latest retained supplier request and response traces; use --page N to continue.
quote Ask for the exact action price: --action register|renew|transfer (default register).
register Register a new name for the quote a prior `quote` answered.
renew Renew this registration for the quote a prior `quote` answered.
transfer Transfer this name to us for the quote a prior `quote` answered.
supersede-transfer --operation <uuid>: close an unknown zero-cost transfer after provider checks.
autorenew --enabled or --disabled plus --accept-terms: the supplier auto-renew intent.
nameservers --nameservers a.example,b.example: change the public delegation.
setup-intent --dns <mode> [--mail <choice>]: record the DNS and mail choice.
refresh Re-read the registrar state now (a check, never a paid retry).
Transfer preserves the current delegation unless --dns explicitly selects another mode.
Every write needs --confirm; --dry-run describes the change without making it.
A register/renew/transfer also needs --quote <uuid> --amount <decimal> --currency <code>.
Superseding needs --operation <uuid> --accept-terms; its prior outcome remains unknown.
A later transfer needs its own fresh quote and the usual current price consent.
A register/transfer needs the registrant contact; a transfer outside .za needs --epp-key.
A nameserver change needs 2 to 5 comma-separated --nameservers and --accept-terms.
A setup choice records intent only and provisions nothing; an omitted --mail leaves the
accepted mail choice unchanged.
Flags
| Flag | Takes a value | What it does |
|---|---|---|
--action | yes | The action a quote is asked about: register, renew or transfer. |
--quote | yes | The quote uuid the operation is made against. |
--amount | yes | The quoted amount the customer consents to. |
--currency | yes | The currency the quoted amount is in. |
--operation | yes | The supplier operation uuid a transfer is superseded against. |
--accept-terms | no | Accept the supplier's terms, which every paid operation needs. |
--enabled | no | Turn the auto-renew intent on. |
--disabled | no | Turn the auto-renew intent off. |
--nameservers | yes | The two to five comma-separated nameservers the delegation moves to. |
--dns | yes | The DNS choice a transfer or setup intent records. |
--mail | yes | The mail choice a setup intent records. |
--epp-key | yes | The transfer authorisation key, for a name outside .za. |
--period | yes | How many years the registration runs for. |
--page | yes | Which page of the retained request history to answer. |
--name | yes | The registrant contact's name. |
--email | yes | The registrant contact's email address. |
--contact | yes | The registrant contact's telephone number. |
--address1 | yes | The registrant contact's first address line. |
--address2 | yes | The registrant contact's second address line. |
--address3 | yes | The registrant contact's third address line. |
--city | yes | The registrant contact's city. |
--province | yes | The registrant contact's province or state. |
--postal-code | yes | The registrant contact's postal code. |
--country | yes | The registrant contact's country. |
--file | yes | The file holding the registrant contact to record. |
Subcommands
contact, status, history, quote, register, renew, transfer, supersede-transfer, autorenew,
nameservers, setup-intent, refresh
update
Update this copy of the CLI to the published version.
Usage: hostingctl update [--check] [--dry-run]
update Detect how this copy was installed, run that package manager's own update command,
then re-read the installed version and report what moved.
update --check Report the published version, this copy's version and the command an update would
run, without running anything. Exits 0 while the copy is current.
update --dry-run Print the command an update would run and send nothing.
The command is printed before it runs, and the package manager's own output is shown as it happens. A
copy that runs from a source checkout, or one this CLI cannot attribute to a package manager, is refused:
the command to run by hand is named instead. `sudo` is never used.
Flags
| Flag | Takes a value | What it does |
|---|---|---|
--check | no | Report the published version and the command an update would run, without running it. |
Subcommands
This command takes no subcommand.
completion
Print the shell completion script for this CLI.
Usage: hostingctl completion <bash|zsh|fish|powershell>
Print the shell completion script for this CLI.
bash The completion function for bash, loaded with `source`.
zsh The completion function for zsh, loaded with `source` from a file in $fpath.
fish The completion definitions for fish, loaded from a file in $fish_function_path.
powershell The argument completer for PowerShell.
The script completes the command names, the subcommands of the command that was named and the flags that
command accepts. It is generated from the command metadata, so it cannot fall behind the commands.
Subcommands
bash, zsh, fish, powershell
help
Show the help for a command, or for one of its groups.
Usage: hostingctl help [<command> [<group> …]]
Print the help for a command, or for one of its groups.
hostingctl help The whole command list.
hostingctl help environment The environment command's own help.
hostingctl help environment database The database group's help.
This is the same as `hostingctl <command> --help`. A name that is not a command exits 2.
Subcommands
This command takes no subcommand.
reference
Print the whole command reference as markdown.
Usage: hostingctl reference
Print the whole command reference as markdown: every command, its summary, its usage, its flags and
its subcommands, with the global options and the exit status contract.
The reference is generated from the command metadata, so it is the same answer the CLI gives about
itself. With --json the metadata itself is printed instead.
Subcommands
This command takes no subcommand.