Skip to main content
Live. This area is documented as current, user-reliable behavior.

​
Goal

Reconcile an application predictably while keeping deployment and deletion explicit.

​
Prerequisites

  • An authenticated profile
  • A valid stackshift.com/v1 application manifest
  • Required secret values in the process environment or an env file

​
Workflow

1
Initialize a new file or export an existing application.
2
Validate locally and against the configured server.
3
Preview reconciliation with plan.
4
Apply the current plan without deploying.
5
Add --deploy only when the manifest services should be built and rolled out.

​
Initialize

init creates a new file with an application name and a public web service on port 3000. It uses create-only file semantics and will not overwrite an existing path.

​
Validate

Validation always performs strict local parsing and schema checks. By default, it then submits the unchanged document to the server validation contract. --local skips only the server check.

​
Plan

A plan records its ID, application, manifest checksum, live application revision, changes, warnings, and expiry. Table output marks destructive changes. JSON or YAML output includes the complete typed plan. --prune asks the server to include deletions only for resources previously recorded as owned by this manifest. It does not authorize deletion during plan.

​
Apply without deployment

apply loads the manifest, creates a fresh plan, confirms destructive changes when required, resolves secret references, and submits the plan ID, checksum, live revision, manifest, flags, and resolved secrets. Applying changes does not deploy services unless --deploy is present.

​
Apply and deploy

With --deploy, the server queues builds for every service in the manifest. The CLI follows each build log stream on standard error unless --detach is also supplied.

​
Pruning and confirmation

apply --prune is always confirmation-gated. Any plan containing a destructive change also requires confirmation. In a non-interactive process, use --yes explicitly.

​
Stale-state protection

The apply request carries the plan ID, checksum, and live revision returned by planning. The server rejects the apply if the live application or document no longer matches that plan. Re-run plan, review the new changes, and apply again.

​
Export an existing application

export resolves an application by UUID or unique name and writes its server-generated manifest. It refuses to overwrite a file unless --force is provided, and forced replacement requires confirmation.

​
Expected result

The application matches the manifest, with no deployment or pruning beyond the flags supplied.

​
Common failures

  • A generated or exported destination already exists.
  • Server validation rejects a capability not enabled for the active profile.
  • A secret referenced with fromEnv is absent from both the env file and process environment.
  • The plan is stale because the live revision or manifest checksum changed.
  • A non-interactive prune or destructive apply omits --yes.

Application manifest schema

Define one application, its services, environments, bindings, attached resources, cron jobs, and domains.

Deploy Git revisions and local directories

Deploy a branch, tag, commit, or deterministic local source archive and follow the rollout.

Output, pagination, errors, and automation

Select stable machine output, fetch paginated results, and handle documented exit codes.