> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Initialize, validate, plan, apply, and export

> Use the application manifest lifecycle with stale-plan protection, explicit pruning, and optional deployment.

<Tip>
  **Live.** This area is documented as current, user-reliable behavior.
</Tip>

## 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

<Steps>
  <Step>
    Initialize a new file or export an existing application.
  </Step>

  <Step>
    Validate locally and against the configured server.
  </Step>

  <Step>
    Preview reconciliation with `plan`.
  </Step>

  <Step>
    Apply the current plan without deploying.
  </Step>

  <Step>
    Add `--deploy` only when the manifest services should be built and rolled out.
  </Step>
</Steps>

## 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.

```bash theme={null}
stackshift init --name storefront
stackshift init --name storefront --file deploy/stackshift.yaml
```

## 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.

```bash theme={null}
stackshift validate
stackshift validate --file deploy/stackshift.yaml
stackshift validate --local
```

## 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`.

```bash theme={null}
stackshift plan
stackshift plan --prune
stackshift plan -o json > plan.json
```

## 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.

```bash theme={null}
stackshift apply
stackshift apply --env-file .env.stackshift
stackshift apply --yes
```

## 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.

```bash theme={null}
stackshift apply --deploy
stackshift apply --deploy --detach -o json
```

## 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.

```bash theme={null}
stackshift apply --prune --yes
```

## 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.

```bash theme={null}
stackshift export storefront
stackshift export storefront --file deploy/stackshift.yaml
stackshift export storefront --force --yes
```

## Expected result

<Check>
  The application matches the manifest, with no deployment or pruning beyond the flags supplied.
</Check>

## Common failures

<Warning>
  * 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`.
</Warning>

## Related guides

<CardGroup cols={2}>
  <Card title="Application manifest schema" href="/cli/application-manifest">
    Define one application, its services, environments, bindings, attached resources, cron jobs, and domains.
  </Card>

  <Card title="Deploy Git revisions and local directories" href="/cli/deployments">
    Deploy a branch, tag, commit, or deterministic local source archive and follow the rollout.
  </Card>

  <Card title="Output, pagination, errors, and automation" href="/cli/output-and-automation">
    Select stable machine output, fetch paginated results, and handle documented exit codes.
  </Card>
</CardGroup>