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

# ubx ship

> Compile .xcl files and deploy the stack (runs pulumi up / terraform apply).

`ubx ship` is the primary deploy command. It compiles XCL, builds the IR, invokes the plugin's `Compile` and `Apply` RPCs, streams progress events, and writes an apply record.

## Usage

```bash theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
ubx ship [path] [flags]
```

## Flags

| Flag                 | Description                                      |
| -------------------- | ------------------------------------------------ |
| `--yes` / `-y`       | Skip confirmation prompt (required in CI)        |
| `--all`              | Deploy all stacks in topology order              |
| `--target <binding>` | Limit to specific resource bindings (repeatable) |

## Examples

```bash theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
ubx ship                             # deploy current stack (prompts)
ubx ship --yes                       # deploy without prompting
ubx ship --all                       # deploy all stacks in order
ubx ship --target networking.vpc     # deploy only the vpc binding
ubx ship --target networking.vpc --target networking.subnet
ubx ship ./networking                # deploy a specific directory
```

## What happens

1. **Compile** — runs the XCL pipeline, generates code (`__main__.py`, etc.)
2. **Typecheck** — validates all files
3. **IR** — builds the IR JSON
4. **Plugin Compile** — invokes plugin's `Compile` RPC, gets `artifact_uri`
5. **Confirmation** — prompts unless `--yes` / `-y`
6. **Plugin Apply** — invokes plugin's `Apply` RPC, streams progress events
7. **Apply record** — writes `.ubx/last-apply.json` on success

## Progress output

```
  ◆ Compile     networking → .ubx/__main__.py
  ◆ Typecheck   2 file(s)
  ◆ IR          building…
  ◆ Compile     (plugin)
  ◆ Ship        running pulumi up…

  + aws:ec2:Vpc                 networking-vpc          (12.1s)
  + aws:ec2:Subnet              networking-public-1a    (8.2s)
  + aws:ec2:Subnet              networking-public-1b    (8.4s)

  done (28.7s)  ·  3 created  ·  0 changed  ·  0 destroyed
```

## Apply record

On success, ubx writes `.ubx/last-apply.json`:

```json theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
{
  "plugin_name": "pulumi",
  "artifact_uri": "file:///path/to/stack/.ubx",
  "stack_name": "networking",
  "timestamp": "2026-07-07T10:00:00Z"
}
```

`ubx terminate` reads this record to skip recompilation.

## Backend URL resolution

ubx resolves the backend URL in priority order:

1. `backend {}` block in the stack IR
2. `PULUMI_BACKEND_URL` environment variable
3. Default: `file://<stack-dir>/.ubx/state/`

Backend URL format per type:

* `local` → `file://<dir>/.ubx/state/`
* `s3` → `s3://bucket/key`
* `gcs` → `gs://bucket`
* `azblob` → `azblob://container`
* `pulumi` → `https://api.pulumi.com`

## Hooks

Before/after hooks run at these points:

```xcl theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
workspace {
  hooks {
    before_ship = "scripts/pre-deploy.sh"
    after_ship  = "scripts/post-deploy.sh"
  }
}
```

## Exit codes

| Code | Meaning                                             |
| ---- | --------------------------------------------------- |
| `0`  | Deploy succeeded                                    |
| `1`  | Compile, typecheck, or deploy error; user cancelled |