Skip to main content

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:

FlagTakes a valueWhat it does
--api-urlyesThe API base URL, including /api/v1 (or HOSTINGCTL_API_URL).
--tokenyesThe bearer token to authenticate with (or HOSTINGCTL_TOKEN).
--companyyesThe company a company-scoped command is about.
--client-idyesThe first-party OAuth client id login signs in with.
--profileyesThe named session to use (or HOSTINGCTL_PROFILE); the default one otherwise.
--jsonnoPrint the API's own fields as JSON.
--helpnoThis text.
--versionnoPrint the version this copy carries.
--dry-runnoDescribe the change a write would make, and send nothing.
--confirmnoMake 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​

FlagTakes a valueWhat it does
--nameyesThe company's own name, or the name an invited person is given.
--slugyesThe permanent slug a new company is created with.
--emailyesThe address an invitation is sent to.
--roleyesThe role a member holds: admin or member.
--image-fileyesThe file holding the logo or favicon to upload.
--token-fileyesThe private file holding the invitation token being accepted.
--token-stdinnoRead 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​

FlagTakes a valueWhat it does
--nameyesThe environment's own name.
--slugyesThe slug the new environment is created with.
--packageyesThe platform package the environment is created from.
--cpuyesThe CPU request every workload gets, in millicores.
--memoryyesThe memory request every workload gets, in mebibytes.
--fileyesThe file holding a configuration document or a portable pattern.
--outyesThe file a portable export is written to.
--bindingsyesThe file holding the authorized targets a portable pattern binds to.
--selectionyesThe file holding the selected source a portable pattern names.
--keyyesThe declared secret key or database configuration key.
--value-sourceyesWhere a secret value comes from: file, stdin or generate.
--value-fileyesThe private file a secret value is read from.
--value-stdinnoRead a secret value from standard input instead of a file.
--replacenoRotate a value that is already set.
--application-uuidyesThe application a configuration change is about.
--applynoApply the reviewed configuration instead of only drafting it.
--engineyesThe database engine: mariadb, postgres or mysql.
--bindyesThe comma-separated workload uuids that may consume a database.
--clear-bindingsnoTake every consumer away from a database.
--digestyesThe review digest the recorded change is made against.
--generationyesThe environment generation the change is recorded against.
--agreementyesThe agreement uuid that prices the extra retention.
--extra-daysyesHow many extra retention days are bought.
--effective-atyesThe instant the extra retention starts.
--hostnameyesThe name the environment serves.
--workloadyesThe workload the name is served by.
--intendedyesWhether the name is one the environment intends to serve: on or off.
--fall-back-to-generatedyesWhether a served name falls back to a generated one: on or off.
--targetyesWhat a redirect points at: an application or a fixed address.
--modeyesWhether the redirect is temporary or permanent.
--destinationyesThe fixed address a redirect points at.
--enabledyesWhether the tool is enabled for this environment: on or off.
--runningyesWhether the service is running: on or off.
--lockedyesWhether the service is locked against removal: on or off.
--replicasyesHow many replicas the service runs.
--sign-inyesWhether the sites require sign-in: on or off.
--audienceyesThe identity audience the sites trust.
--emailyesThe 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​

FlagTakes a valueWhat it does
--typeyesThe application recipe to run.
--nameyesThe application's own name.
--replicasyesHow many copies to run; one by default.
--cpu-requestyesThe CPU request the container is given, in millicores.
--cpu-limityesThe CPU limit the container is given, in millicores.
--memory-requestyesThe memory request the container is given, in mebibytes.
--memory-limityesThe memory limit the container is given, in mebibytes.
--labelyesThe label the application is listed and renamed under.
--hostnameyesThe name visitors should reach the application at.
--sourceyesThe workload a route is served from.
--targetyesThe workload a route is sent to.
--pathyesThe path a route answers on.
--domainyesThe domain a route is served under.
--routeyesThe route the canonical answer is read from.
--canonicalyesWhether the route is the canonical one: on or off.
--enabledyesWhether the HTTP cache is enabled: on or off.
--freshyesHow long a fresh response stays fresh, in seconds.
--backgroundyesHow long a background refresh runs, in seconds.
--browseryesHow long a browser may reuse a cached response, in seconds.
--resetyesWhether the cache is reset on every request: on or off.
--selectionyesThe selected repository a source is bound to.
--branchyesThe branch the bound source is built from.
--tagyesThe tag the bound source is built from.
--auto-deployyesWhether a new commit deploys by itself: on or off.
--idempotency-keyyesThe key a retried build is recognised by, so it is not queued twice.
--modeyesWhat the runtime should be doing: stop, start or restart.
--databaseyesThe SQL dump the staged import is built from.
--archiveyesThe site's files as one ZIP.
--directoryyesThe site's files as a directory.
--source-urlyesThe old address stored WordPress URLs are rewritten from.
--confirmationyesThe text the review asks the person to type.
--sign-inyesWhether the application requires sign-in: on or off.
--audienceyesThe identity audience the application trusts.
--emailyesThe 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​

FlagTakes a valueWhat it does
--reasonyesThe reason the cancellation is requested with.
--timingyesWhen the service ends: at-service-end, or now to destroy at the confirmation.
--effective-atyesThe ISO-8601 date service ends, when the timing is at-service-end.
--generationyesThe environment's current generation, as environment show prints it.
--digestyesThe 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​

FlagTakes a valueWhat it does
--generationyesThe environment generation the lock is recorded against.
--unlocknoClear 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​

FlagTakes a valueWhat it does
--usernameyesThe login name the environment's user signs in with.
--nameyesThe display name of the login or key being changed.
--key-nameyesThe key's own label, when the key is not named after the login.
--public-key-fileyesThe file holding the public key to add; it is read, never printed.
--access-useryesThe environment's own access user the change is about.
--useryesThe platform user a grant is given to.
--passwordyesWhether password sign-in is offered: on or off.
--sftp-onlyyesWhether the logins are restricted to SFTP: on or off.
--enabledyesWhether the login may sign in: on or off.
--read-onlyyesWhether the login is read-only: on or off.
--password-fileyesThe private file holding the login's new password.
--password-stdinnoRead 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​

FlagTakes a valueWhat it does
--provideryesThe secret manager kind. Infisical is supported.
--endpointyesThe provider's API base address. HTTPS only.
--project-idyesThe provider project the values live in.
--remote-environmentyesThe provider's own environment slug, such as production.
--client-idyesThe machine identity's client id.
--client-secret-fileyesThe private file holding the machine identity's client secret.
--client-secret-stdinnoRead the client secret from standard input instead of a file.
--ca-fileyesA public CA certificate for a customer-hosted instance.
--nameyesThe declared secret name a mapped key supplies.
--remote-pathyesThe folder inside the provider holding the key.
--remote-keyyesThe 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​

FlagTakes a valueWhat it does
--nameyesThe label the key is listed under.
--public-key-fileyesThe file holding the public key to add; it is read, never printed.
--current-password-fileyesThe private file holding the account password the change is made with.
--current-password-stdinnoRead 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​

FlagTakes a valueWhat it does
--addressyesThe address the fallback is set to, or the address being recovered.
--recipientyesWhere the mail-client instructions are sent.
--destinationyesThe address a copied message is sent to.
--fileyesThe file holding the mailboxes to create; it is read bounded and never printed.
--formatyesThe format the import file is written in: csv or yaml.
--token-fileyesThe private file holding the recovery token being verified or reset.
--token-stdinnoRead the recovery token from standard input instead of a file.
--password-fileyesThe private file holding the new password a recovery sets.
--password-stdinnoRead 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​

FlagTakes a valueWhat it does
--addressyesThe granted address one mailbox record is about.
--localyesThe local part of the address or alias being created.
--labelyesThe label an address is listed under.
--destinationsyesThe comma-separated addresses an alias or mailbox forwards to.
--hostnameyesThe name to attach to the service.
--termyesThe package term uuid the enrolment agrees to.
--statusyesThe mailbox's own status: enabled or suspended.
--quotayesThe mailbox's own quota size.
--reasonyesWhy the hold is placed: compromise, abuse or operator.
--mailboxyesThe one mailbox a hold or a sync account is about.
--spam-mark-readyesWhether junk is marked as read: on or off.
--spam-thresholdyesThe score above which mail is treated as junk.
--vacationyesWhether the out-of-office reply is on: on or off.
--vacation-subjectyesThe subject the out-of-office reply carries.
--vacation-bodyyesThe body the out-of-office reply carries.
--vacation-startyesThe instant the out-of-office reply starts.
--vacation-endyesThe instant the out-of-office reply ends.
--enabledyesWhether the service is enabled: on or off.
--ends-atyesThe instant a cancellation takes effect.
--versionyesThe service version the change is made against.
--hostyesThe IMAP or SMTP host a sync account reaches.
--portyesThe port a sync account reaches.
--encryptionyesThe transport a sync account uses: tls or starttls.
--usernameyesThe login a sync account connects with.
--recurrenceyesHow often a sync account syncs: once or until.
--password-fileyesThe private file holding a sync account's password.
--password-stdinnoRead a sync account's password from standard input instead of a file.
--fileyesThe 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​

FlagTakes a valueWhat it does
--fileyesThe file holding the record sets; it is read bounded and never printed.
--nameyesThe relative name of one record set.
--typeyesThe record type of one record set: A, AAAA, CNAME, MX, TXT or SRV.
--descriptionyesWhat 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​

FlagTakes a valueWhat it does
--hostnameyesThe 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​

FlagTakes a valueWhat it does
--endpointyesThe S3 endpoint the bucket is reached at.
--bucketyesThe bucket the copies are written to.
--regionyesThe region the bucket lives in.
--access-key-idyesThe access key id the copies are written with.
--secret-key-fileyesThe private file holding the secret key, which is never printed.
--secret-key-stdinnoRead the secret key from standard input instead of a file.
--prefixyesThe folder inside the bucket the copies are written under.
--armnoStart 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​

FlagTakes a valueWhat it does
--startyesThe ISO-8601 instant the window starts at.
--endyesThe ISO-8601 instant the window ends at.
--limityesHow 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​

FlagTakes a valueWhat it does
--fromyesThe ISO-8601 instant the window starts at; it is included.
--toyesThe ISO-8601 instant the window ends at; it is not included.
--limityesHow many purchase periods one page holds, at most 500.
--cursoryesThe 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​

FlagTakes a valueWhat it does
--no-browsernoPrint 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​

FlagTakes a valueWhat it does
--verifynoAsk the API whether the stored session is still accepted.
--localnoForget the session on this machine without asking the API to revoke it.
--no-browsernoPrint the authorize URL and take the callback URL on stdin, for a machine with no browser.
--nameyesThe name on the account's own profile.
--emailyesThe address on the account's own profile, or the one a recovery is asked about.
--image-fileyesThe file holding the profile picture to upload.
--reasonyesThe reason an account is closed or an impersonation is started.
--targetyesThe account the impersonation acts as.
--store-asyesThe profile name an impersonation session is stored under.
--minutesyesHow long the impersonation lasts, in minutes.
--current-password-fileyesThe private file holding the current account password.
--current-password-stdinnoRead the current account password from standard input instead of a file.
--new-password-fileyesThe private file holding the new account password.
--new-password-stdinnoRead the new account password from standard input instead of a file.
--password-fileyesThe private file holding the password an account is registered with.
--password-stdinnoRead the registration password from standard input instead of a file.
--token-fileyesThe private file holding a recovery or verification token.
--token-stdinnoRead 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​

FlagTakes a valueWhat it does
--kindyesWhich published document is asked for: hosting or portable-site.
--versionyesThe document version asked for, or the seed version being changed.
--hostnameyesThe name the claim or the company record is about.
--reasonyesWhy the decision was taken, recorded with it.
--stateyesThe state the client directory is filtered by.
--searchyesThe text the directory is searched for.
--nameyesThe name the record being created is given.
--slugyesThe slug the record being created is given.
--admin-emailyesThe address the company's administrator is recorded with.
--eventyesThe directory event kind that is asked for.
--logyesThe directory log entry that is asked for.
--emailyesThe address an alert or a rule is sent to.
--enabledyesWhether the alert or the consumption is enabled: on or off.
--monitoringyesWhether the monitoring rule is on: on or off.
--mailboxyesThe postmaster mailbox the monitoring watches.
--acknowledgedyesWhether the incident is acknowledged: on or off.
--mute-hoursyesHow long the postmaster stays muted, in hours.
--workload-typeyesThe workload type the seed is prepared for.
--scopeyesWho the seed is prepared for: platform or company.
--preparation-modeyesHow the seed or its placement is prepared.
--descriptionyesWhat the prepared word or record is for.
--wordyesThe word the generated hostname vocabulary holds.
--positionyesWhere the word sits: adjective or noun.
--source-releaseyesThe release the seed version is built from.
--source-commityesThe commit the seed version is built from.
--source-checksumyesThe checksum the source is verified against.
--recipe-revisionyesThe recipe revision the seed version is built from.
--runtime-image-digestyesThe runtime image digest the seed version pins.
--content-contractyesThe file holding the content contract the version declares.
--releaseyesThe release the seed version is published with.
--clusteryesThe cluster the placement is made on.
--storage-classyesThe storage class the placement is adopted with.
--backing-imageyesThe backing image the placement runs from.
--expected-checksumyesThe checksum the adopted placement is verified against.
--minimum-sizeyesThe smallest size the placement is prepared at, in mebibytes.
--basisyesThe basis the purge decision is made on.
--evidenceyesThe evidence reference the purge decision carries.
--expires-atyesThe instant the recorded decision expires.
--observed-atyesThe instant the state was observed at.
--parent-zoneyesThe parent zone the record sits under.
--provider-accountyesThe provider account the record belongs to.
--provider-zoneyesThe provider zone the record belongs to.
--generationyesThe generation the recorded decision is made against.
--fromyesThe ISO-8601 instant the purchase window starts at.
--toyesThe ISO-8601 instant the purchase window ends at.
--limityesHow many purchase periods one page holds.
--cursoryesThe 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​

FlagTakes a valueWhat it does
--custd-companyyesThe CustD company the environment's realm is allocated from.
--owning-useryesThe user the recorded realm intent is owned by.
--registration-policyyesThe registration policy to record: invite_only or open.
--expected-revisionyesThe revision the record is made against, so a stale read is refused.
--login-pausednoRecord the realm with logins paused.
--audiencesyesThe file holding the audiences to record, as the API's own JSON array.
--audienceyesThe 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​

FlagTakes a valueWhat it does
--repositoryyesThe repository the connection is asked to offer.
--branchyesThe branch the selected repository is bound to.
--config-pathyesThe path inside the repository the configuration is read from.
--callback-fileyesThe private file holding the callback URL GitHub redirected to.
--callback-stdinnoRead 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​

FlagTakes a valueWhat it does
--actionyesThe action a quote is asked about: register, renew or transfer.
--quoteyesThe quote uuid the operation is made against.
--amountyesThe quoted amount the customer consents to.
--currencyyesThe currency the quoted amount is in.
--operationyesThe supplier operation uuid a transfer is superseded against.
--accept-termsnoAccept the supplier's terms, which every paid operation needs.
--enablednoTurn the auto-renew intent on.
--disablednoTurn the auto-renew intent off.
--nameserversyesThe two to five comma-separated nameservers the delegation moves to.
--dnsyesThe DNS choice a transfer or setup intent records.
--mailyesThe mail choice a setup intent records.
--epp-keyyesThe transfer authorisation key, for a name outside .za.
--periodyesHow many years the registration runs for.
--pageyesWhich page of the retained request history to answer.
--nameyesThe registrant contact's name.
--emailyesThe registrant contact's email address.
--contactyesThe registrant contact's telephone number.
--address1yesThe registrant contact's first address line.
--address2yesThe registrant contact's second address line.
--address3yesThe registrant contact's third address line.
--cityyesThe registrant contact's city.
--provinceyesThe registrant contact's province or state.
--postal-codeyesThe registrant contact's postal code.
--countryyesThe registrant contact's country.
--fileyesThe 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​

FlagTakes a valueWhat it does
--checknoReport 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.