deploy create
Build and deploy an application.
Builds the application and ships the result. For an application that runs a ready-made image, this is also how a new tag reaches it.
By default it returns the moment the build is queued, which is not the moment
anything is running. --follow streams the build until it settles, --wait blocks
without the output, and deploy get answers the same question later from any
machine.
Usage
outplane deploy create [APP] [flags]Also available as outplane deploy.
Arguments
| Argument | Type | Description |
|---|---|---|
APP | string | App name or id. Defaults to the linked app. Must match ^[a-zA-Z0-9]{5,45}$. |
Flags
| Flag | Type | Description |
|---|---|---|
--image | string | Container image reference to deploy. Rejected locally for Git-sourced apps, which the server would reject anyway. |
-f, --follow | bool | Stream build logs until the deployment reaches a final state. |
--wait | bool | Block until the deployment finishes, without streaming logs. |
--timeout | duration | How long --wait and --follow will wait before giving up. Defaults to 20m. |
The global flags apply as well.
Output
| Field | Type | Description |
|---|---|---|
deploymentId | int | Identifier for deploy get and deploy logs. |
app | object | {id, name}. |
status | string | Current state. An unrecognised value is reported as-is and never interpreted, so a new server state cannot turn into a false result. One of queued, building, deploying, ready, failed, crashed, canceled. |
branch | string | null | For a Git-sourced app. |
imageRef | string | null | For a container-registry app. |
commitMessage | string | null | |
startedAt | string | RFC 3339, UTC. |
duration | string | null | The server's own figure for the build, already humanised. It excludes the release that follows, so a --wait call takes slightly longer than this reports. |
changed | bool | True whenever a build was started. |
Streams as NDJSON: one object per line, flushed as it arrives.
Examples
Deploy the linked app and wait for it to finish
outplane deploy create --waitSee what would be sent, without deploying
outplane deploy create checkout --dry-run --jsonDeploy a specific image and stream the build log as NDJSON
outplane deploy create checkout --image ghcr.io/acme/api:v1.4.0 --follow -o ndjson{
"app": {
"id": "…",
"name": "checkout"
},
"deploymentId": 4821,
"imageRef": "<IMAGE_REF>",
"status": "ready"
}What to Know
- Without --wait or --follow this command returns as soon as the build is queued. A queued build is not a finished deploy.
- To check the outcome, run: outplane deploy get <deploymentId> --json
- When a deploy fails, read the build output first: outplane deploy logs <deploymentId>
- There is no rollback command. The image registry keeps only the last three tags per repository, so older deployment images no longer exist.
- There is no way to cancel a running deployment.
Errors
Beyond 0 for success, this command exits with:
| Exit | Kind | Meaning |
|---|---|---|
2 | usage | Invalid arguments, unknown flag, or client-side validation failure. |
3 | auth | Not authenticated, token revoked or expired, or forbidden for this team. |
5 | not_found | The named resource does not exist, or is not visible to this credential. |
7 | quota | Plan limit reached or payment required. Not a rate limit; retrying will not help. |
8 | upstream | The Out Plane API returned a server error. |
124 | timeout | A client-side deadline expired. The server operation may still be running. |
The code on the error object is one of deploy.image_on_git_app, deploy.failed, deploy.timeout, app.not_found, app.ambiguous, context.no_app, usage.empty_argument, quota.limit_reached. Branch on that, or on the exit status. The message is prose and changes.