Skip to main content
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.
Update an ’s name, slug, GitHub repository connection, image, or delete protection. Flags you omit leave the stored value unchanged.
  • Changing the slug changes the hostnames of the app’s deployments.
  • --git with a JSON object connects or changes the repository, and --git=null disconnects it. It only works on a GitHub app.
  • --oci changes the image of an image app. It only works on an image app.
  • A request with nothing to update returns Provide at least one field to update.

​
Usage

​
Flags

​
string
required
App ID or slug.
​
boolean
Enable (--delete-protection) or disable (--delete-protection=false) delete protection. Omit the flag to leave the current setting unchanged.
​
string
GitHub repository update as a JSON object, or null to disconnect the repository.
​
string
OCI image update as a JSON object with an image field. The reference needs an explicit tag or digest.
​
string
New human-readable name, 1 to 256 characters.
​
string
required
Project ID or slug. Both forms resolve to the same project.
​
string
New app slug, 3 to 255 characters matching ^[a-zA-Z0-9_-]+$. Must stay unique in the project; a duplicate returns a 409 conflict.

​
Shared flags

Every unkey 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:
  • app.*.update_app (any app)
  • app.<app_id>.update_app (a specific app)
When you pass --git, your key also needs app.*.connect_repository or app.<app_id>.connect_repository. Without a matching permission the API answers 403 and the CLI prints Permission denied: followed by the detail. See Root key permissions for the full catalog.

​
Examples

Rename an app:
Connect a repository:
Disconnect the repository:
Point the app at a different image:
Send the request body as JSON:

​
API endpoint

The command calls POST /v2/apps.updateApp and prints its response. The request fields carry the same names as the flags in camelCase, which is the shape --body expects.
Last modified on September 29, 2026