You need a root key with the permissions listed on this page. Create one in the dashboard under Settings > Root Keys. See Permission reference for every permission.
dockerfile, buildCommand, healthcheck, or openapiSpecPath, send null with --body, because the flags can’t send null. --regions replaces the whole region list and can’t be empty.
A value outside the limits below returns 400. --v-cpus, --memory-mib, and --storage-mib are capped by your workspace’s per-instance quota. If your workspace has no resource limits set, you get Resource limits are not configured for this workspace. Contact support@unkey.com.
Usage
Flags
string
required
App ID or slug.
boolean
Whether pushes to the connected repository deploy automatically (
--auto-deploy or --auto-deploy=false). Omit the flag to leave the current setting unchanged.string
Build command.
string[]
Comma-separated container command that overrides the image’s command. At most 10 entries, each at most 4096 characters.
string
Path of the Dockerfile inside the root directory.
string
required
Environment ID or slug.
string
Health check configuration as a JSON object, for example
{"method":"GET","path":"/health"}. method is GET or POST, and path must start with a slash. The optional fields are intervalSeconds (default 10), timeoutSeconds (default 5), failureThreshold (default 3), and initialDelaySeconds (default 0).integer
Memory allocation in MiB. At least 256, in steps of 256, up to your workspace’s per-instance quota.
string
Path of the OpenAPI specification served by the app, used by the gateway’s OpenAPI validation policy. It must start with a slash and match
^(/[\w\-]+)+(\.[\w]+)?$, for example /openapi.yaml.integer
Container port the app listens on, from 1 to 65535.
string
required
Project ID or slug. Both forms resolve to the same project.
string
Region configuration as a JSON array, for example
[{"name":"us-east-1","replicas":{"min":1,"max":2}}]. Replaces the full region list, which must hold 1 to 5 regions.string
Directory of the repository the build runs in, as a relative path. Use
. for the repository root. An absolute path is rejected with Root directory must be a relative path like 'api' or 'services/api'.enum
Signal sent to the container on shutdown. One of
SIGTERM, SIGINT, SIGQUIT, or SIGKILL.integer
Ephemeral storage allocation in MiB, in steps of 512, up to your workspace’s per-instance quota.
0 allocates none.enum
Protocol the gateway uses to reach the container. Either
http1 or h2c.float
CPU allocation in vCPUs. At least 0.25, in steps of 0.25, up to your workspace’s per-instance quota.
string[]
Comma-separated glob patterns, at most 10. A push deploys only if a changed file matches one. Use
src/** for everything under a directory and **/*.go for a file type. Don’t start a pattern with / or ./: it’s accepted but never matches.Shared flags
Everyunkey api command accepts these; CLI output and shared flags describes them in full.
string
A JSON document sent as the request body instead of building it from the flags above. It is mutually exclusive with the request-building flags, and unknown fields are rejected locally. See Send a raw body.
string
Root key for the request. Falls back to
UNKEY_ROOT_KEY, then to the config file written by unkey auth login. See CLI authentication.string
default:"https://api.unkey.com"
Base URL of the API. Falls back to
UNKEY_API_BASE_URL. You don’t normally need to set it.string
default:"~/.unkey/config.toml"
Path of the TOML file that
unkey auth login writes. Falls back to UNKEY_CONFIG.string
Output format. Falls back to
UNKEY_OUTPUT. Set json to print the full response envelope (meta and data) for piping; any other value prints the request ID followed by data.Required permissions
Your root key needs one of:environment.*.update_environment(any environment)environment.<environment_id>.update_environment(a specific environment)
Permission denied: followed by the detail. See Root key permissions for the full catalog.
Examples
Set a health check and scale a region:API endpoint
The command callsPOST /v2/environments.updateSettings and prints its response. The request fields carry the same names as the flags in camelCase, which is the shape --body expects.
Related
Runtime settings
Port, command, resources, shutdown signal, and regions.
Build settings
Dockerfile, root directory, build command, and watch paths.
Health checks
What the health check probes and how failures are handled.