Skip to content

JSON output and errors ​

Use machine-readable output and process exit codes for automation. Human-readable messages may evolve; JSON codes and structured results are the stable integration surface.

Single-document output ​

Site, file, and download commands emit one JSON value with --json:

bash
zynohosting sites list --json
zynohosting files list example.com --json
zynohosting download example.com ./copy --yes --json

Errors are written as one JSON object:

json
{
    "type": "error",
    "code": "precondition_failed",
    "message": "file precondition failed",
    "details": {
        "code": "precondition_failed",
        "message": "file precondition failed"
    }
}

Do not assume details is always present.

Deployment event stream ​

Deploy emits newline-delimited JSON because planning and applying have multiple stages:

bash
zynohosting deploy example.com ./dist --dry-run --json

Event types are:

TypeMeaning
progressA current planning or apply stage.
planExact operations, display groups, counts, ignores, and upload bytes.
dry_run_completePlanning completed without mutation.
resultApply result with create/replace/delete counts and duration.
cancelledInteractive apply was declined.

Consume one JSON object per line rather than parsing the complete standard output as a single document.

Promotion output ​

promote --yes --json emits promotion_plan, progress events, then promotion_result only after serving reconciliation succeeds. The plan contains both URLs, the expected production deployment ID, force, and a forceWarning when --force was given. The result contains deploymentId, operationId, and status: "succeeded". promote --dry-run --json emits the plan and dry_run_complete without a mutation.

Deployment plan/result events include target (production or preview) and the URL when advertised by the manager. Preview events also include resourceNotice.

Promotion errors include preview_unavailable for an older manager, promotion_failed for a failed serving reconciliation, and promotion_pending when an accepted operation is still pending. The latter includes its operation ID and status path; inspect that operation before resubmitting.

Login output ​

zynohosting login --json writes one event per line to stdout and human text to stderr. The device code, access token and renewal token never appear.

EventWhen
{"type":"login_started","flow":"device","reason","verificationUri","verificationUriComplete","userCode","expiresAt","interval"}A code was issued. reason is explicit, ssh, no_display or loopback_unavailable.
{"type":"login_started","flow":"browser","reason","url"}The browser flow started.
{"type":"login_pending","resume":"zynohosting login --resume"}--no-wait saved a pending sign-in, or --resume timed out.
{"type":"warning","code":"api_key_in_environment|access_token_in_environment","message"}login ran while ZYNOHOSTING_API_KEY or ZYNOHOSTING_ACCESS_TOKEN is set; that credential overrides saved logins for every command.
{"type":"login_resuming","userCode"}--resume began waiting.
{"type":"result","status":"authenticated","flow","profile","loginId","accountId","tenantId","tenantName","account","renewable","permissionKeys","deniedPermissionKeys","credentialStore","accessExpiresAt","grantExpiresAt"}The login was saved. permissionKeys is what the approver granted (a subset of what was requested) and deniedPermissionKeys what was not. Times are ISO strings. accountId, tenantName, account, credentialStore (only for a renewable login) and grantExpiresAt can be absent; every other field, including deniedPermissionKeys (an empty array when nothing was denied) and accessExpiresAt, is always present.
{"type":"result","status":"api_key_saved","profile"}--api-key was saved. Only an explicit --api-key is saved; a ZYNOHOSTING_API_KEY in the environment is never written to disk.

zynohosting logins --json prints {"profile","logins":[{"loginId","kind","accountId","accountEmail","tenantId","tenantName","active","renewable","permissionKeys","deniedPermissionKeys","credentialStore","accessExpiresAt","grantExpiresAt","expired"}]}, and zynohosting whoami --json prints {"profile","login":{…}}. On logins, accountId, accountEmail, credentialStore (only when renewable), accessExpiresAt and grantExpiresAt are present only when known, permissionKeys is absent for a login saved before permissions were recorded, and deniedPermissionKeys is present only when something was denied. An API key row has only loginId, kind, tenantName, active, renewable and expired. Tokens are never listed.

Site settings output ​

sites set --yes --json emits site_settings_plan, progress events, then site_settings_result only after serving reconciliation succeeds. --dry-run --json emits the plan and dry_run_complete. Errors: not_found_handling_requires_static (exit 2, SPA on a PHP site), not_found_handling_unavailable (exit 5, older manager), reconciliation_failed and reconciliation_pending (exit 7; the latter includes the operation ID, and re-running the same command resumes waiting).

Deploy token output ​

deploy-tokens create --json writes one event per line. The deploy token and the request code never appear in any event, error, or log.

EventMeaning
{"type":"prompt","site","environments","userCode","verificationUri","verificationUriComplete","expiresAt","permissions","destination"}The approval link and code. Show them to the person.
{"type":"warning","code":"deploy_token_file_in_worktree","message"}A --file destination is in a git worktree and not ignored.
{"type":"result","status":"pending",...}--no-wait saved the request. Finish it with --resume.
{"type":"result","status":"created","site","siteId","environments","keyId","preview","permissionKeys","expiresAt","destination","warnings"}The token was approved and handed off.

sites runtime --yes --json emits runtime_plan, progress events, then runtime_result.

With CI=true and ZYNOHOSTING_API_KEY set, commands also emit {"type":"warning","code":"api_key_in_ci","message"} (stderr text without --json). Use a deploy token instead.

Exit codes ​

Exit codeCategory
0Success.
1Unexpected CLI or runtime failure.
2Invalid local input, unsafe path, configuration, or missing confirmation.
3Authentication or authorization failure, including expired login.
4Remote API failure or failed ETag/create-only precondition.
5Invalid, incompatible, or unsafe manager/agent response.
6Unknown or expired plan/session, or a stated precondition no longer holds.
7The node agent could not apply a deployment, or a promotion or site-settings reconciliation failed or is pending.
8Mutation applied, but cache invalidation could not be queued.

Exit code 8

The remote mutation already succeeded. Do not blindly retry the deployment as though nothing changed; inspect the site and retry cache invalidation through an approved operational path.

Common error codes ​

CodeTypical resolution
missing_configRun zynohosting login or provide an API key.
login_expiredLog in again, or use --renewable for a long-running client.
renewal_invalidThe one-time renewal token is invalid/used; log in again.
renewal_forbiddenTenant policy prohibits renewal; contact a tenant administrator.
renewal_missingThe OS credential entry is unavailable; log in again.
credential_store_failedUnlock or repair the operating system credential store.
credential_store_unavailableNo system credential service. Use a non-renewable login, or on a computer only you use, --credential-store file.
credential_store_insecureThe token file is a symlink or readable by others; fix or delete it, then log in again.
invalid_credential_storeUse system or file, and only with --renewable.
invalid_lifetimeUse 1h, 1d, 7d or 30d; anything above 1h needs --renewable.
grant_expiredThe approved lifetime ended (exit 3). Log in again.
login_deniedThe person denied the sign-in (exit 3).
device_code_expiredThe code ran out or was already used (exit 3). Log in again.
device_credential_lostThe connection dropped while the approval was delivered (exit 3). Log in again.
login_pendinglogin --resume timed out with nobody approving (exit 3). Run it again.
no_pending_loginlogin --resume with nothing started (exit 2). Start with --device --no-wait.
device_flow_unavailableThe server does not offer the link-and-code sign-in (exit 4). Use the browser flow.
unsupported_nodeNode.js is older than 24 (exit 1). Install Node.js 24.
login_selection_requiredSeveral logins and none is the default (exit 2). Pass --tenant.
login_not_foundNo saved login matches --tenant (exit 2). See zynohosting logins.
login_ambiguousSeveral logins match, for example two accounts in one tenant (exit 2). The message lists each login id with its account and tenant; pass --account or the full login id.
deploy_token_not_allowedA deploy token cannot run this command (exit 3). See Deploy tokens.
conflicting_credentialsA deploy token was set with an API key or access token (exit 2).
deploy_token_requires_productionA site that runs PHP needs a deploy token that includes production.
php_unavailableThe platform has no default PHP version; name one with php@<version> (exit 5).
unsupported_php_versionsites runtime named a PHP version the platform does not support (exit 2).
invalid_environmentUse production, alpha, or dev.
confirmation_requiredUse a terminal, --dry-run, or reviewed --yes.
precondition_failedRefresh the file listing and review the new ETag/content.
plan_expiredCreate and review a new plan.
unsafe_local_pathChoose an absolute destination inside an allowed MCP root.
unsupported_protocolUpgrade the CLI or resolve cluster version skew.
cache_invalidation_failedTreat the mutation as applied and investigate cache invalidation.

Shell example ​

bash
set +e
zynohosting files put example.com ./index.html index.html --json >result.json
status=$?
set -e

if [ "${status}" -ne 0 ]; then
  echo "ZynoHosting operation failed with exit code ${status}" >&2
  exit "${status}"
fi

When file content is streamed with files get --output -, standard output contains bytes and cannot also contain JSON.

Documentation for the ZynoHosting CLI and local MCP server.