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

# Variable Promotions

> Request, review, approve, reject, or cancel cross-environment variable promotions from the CLI.

<Card title="Need the shared environment model?" icon="circle-info" href="/fundamentals/v2/core-objects/environments">
  Read the Fundamentals page for the shared model, then use this guide for CLI promotion
  workflows.
</Card>

Variable promotion lets you move one or more variable keys from a source environment to a target
environment through an approval workflow.

This keeps environment changes auditable and reviewable while staying inside Ghostable's
zero-knowledge model.

## Create a Promotion Request

Run the guided flow:

```bash theme={null}
ghostable env promote
```

The CLI will guide you through:

* selecting source environment,
* selecting target environment,
* selecting one or more variable keys,
* choosing whether to include current values.

<Note>
  `include values` defaults to **false**. In this mode, key names are preserved while values are
  intentionally blank in the request payload.
</Note>

### Scriptable create example

```bash theme={null}
ghostable env promote \
  --source-env local \
  --target-env production \
  --keys APP_URL \
  --keys APP_DEBUG \
  --include-values \
  --yes
```

## Review Pending Requests

List pending requests in the current project:

```bash theme={null}
ghostable env promote pending
```

Use guided review:

```bash theme={null}
ghostable env promote review
```

Or review a specific request:

```bash theme={null}
ghostable env promote review <request-id>
```

Guided review lets you choose:

* **Approve**
* **Reject**
* **Cancel**

## Approve, Reject, or Cancel Directly

Approve:

```bash theme={null}
ghostable env promote approve <request-id>
```

Approve with override values:

```bash theme={null}
ghostable env promote approve <request-id> --set APP_URL=https://example.com
```

Reject:

```bash theme={null}
ghostable env promote reject <request-id> --reason "Needs updated value source."
```

Cancel:

```bash theme={null}
ghostable env promote cancel <request-id> --reason "No longer needed."
```

## Include-Values vs Blank-Values Behavior

* **include values = false**: request carries key names with blank values.
* **include values = true**: request includes encrypted payloads for current source values when
  available on your device.

If a source value cannot be decrypted on your current device, approval may require explicit override
values (`--set KEY=VALUE`).

## Recovery and Terminal States

* If create/approve fails due to key-signature access requirements, CLI performs one controlled
  key-share recovery attempt, then retries once.
* If a request is already resolved, CLI exits cleanly with explicit status instead of retrying
  destructively.

## Continue

<CardGroup>
  <Card title="Environment workflows" icon="terminal" href="/cli/v2/workflows/environments">
    Return to push, pull, sync, diff, and validation workflows.
  </Card>

  <Card title="Device and key re-share" icon="laptop" href="/cli/v2/workflows/devices">
    Review device identity and key re-sharing flows used during recovery paths.
  </Card>

  <Card title="Security controls matrix" icon="shield" href="/fundamentals/v2/security-and-operations/security-controls-matrix">
    Map promotion review controls to audit and operational evidence.
  </Card>
</CardGroup>