How the CLI works

The Coolify CLI translates terminal commands into requests to the Coolify REST API. It selects a saved Coolify connection, sends the request with an API token, and formats the response for a person or automation workflow.

The same process applies to Coolify Cloud and self-hosted Coolify. The selected URL, token permissions, and self-hosted API controls determine which resources and operations are available.

From a command to a response

When you run a resource command, the CLI follows this sequence:

Loads the CLI configuration file.
Selects the context named by --context, or the default context when the flag is absent.
Uses the token supplied by --token, or the token saved in the selected context when the flag is absent.
Adds /api/v1/ and the command's endpoint path to the context URL.
Sends the token in the Authorization: Bearer <api-token> header.
Checks the HTTP response and formats successful response data for the terminal.

For example, a context URL of https://coolify.example.com and an operation that uses resources produce a request to:

https://coolify.example.com/api/v1/resources

The CLI does not connect directly to the Docker engine for resource commands. Coolify receives the API request and performs the requested operation on the relevant resource or server.

Context and token precedence

The CLI resolves connection details in this order:

Setting	First choice	Fallback
Coolify URL	Context selected with `--context`	Default context
API token	Token supplied with `--token`	Token saved in the selected context

The --token flag changes only the token used for that command. It does not modify the saved context. Follow Contexts to change a saved URL or token.

Access boundaries

Each API token belongs to the Coolify user and team that created it. The CLI can access only the resources and operations allowed by that token's team and permissions.

Coolify Cloud keeps API access enabled. On self-hosted Coolify, API Access and the optional IP allowlist are checked before the token's permissions. Read API permissions for token scope and IP Allowlist for self-hosted controls.

Request failures and retries

Each API request has a 30-second timeout. When a request fails because of a network error, server error, or 429 Too Many Requests response, the CLI retries up to three times with waits of 1, 2, and 4 seconds.

The CLI does not retry other 4xx responses. Correct the URL, token, permissions, command arguments, or requested resource before running the command again.

If every attempt fails, the command returns an error and exits with a nonzero status. This lets shell scripts and CI jobs stop when a Coolify operation fails.

Response formats

The CLI supports three global output formats:

Format	Intended use
`table`	Default human-readable terminal output.
`json`	Compact output for scripts and automation.
`pretty`	Indented JSON for inspection and debugging.

Select a format for one command:

coolify --format json resource list

Sensitive values remain hidden unless the API token can read them and --show-sensitive is supplied. Avoid --show-sensitive in shared terminals and CI logs.

Follow Deploy applications, Automate with the CLI, or Manage database backups for operational examples. Open Commands in the sidebar for operation-level syntax and options.