---
title: "Rollout Application"
description: "Documentation for Rollout Application Command in ZeyOS SDK CLI"
canonical_url: "https://www.zeyos.com/sdk/application-management/zeysdk-rollout"
markdown_url: "https://www.zeyos.com/ai/guide/sdk/application-management/zeysdk-rollout.md"
section: "sdk"
authority: "guide"
language: "en"
source_repository: "zeyos/sdk-v2"
source_path: "docs/application-management/zeysdk-rollout.md"
source_revision: "a99897af74253b4dc5af6fecb9301cea0ae18e27"
---

# Rollout Application

The `rollout` command pushes your ZeyOS application to one or more linked instances sequentially.

```bash
zeysdk rollout [INSTANCE_ID...] [options]
```

**Parameters**

| Parameter | Description | Required | Example |
|-----------|-------------|----------|---------|
| `INSTANCE_ID` | Target instance IDs | No | `dev-instance prod-instance` |

**Options**

| Option | Description |
|--------|-------------|
| `-a, --all` | Rollout to all linked instances |
| `-f, --force` | Continue even if errors occur |
| `-v, --verbose` | Show detailed output |
| `--break-lock` | Remove an existing sync lock before acquiring the rollout lock |

**Interactive Features**

1. **Instance Selection**
   - If no instances specified, shows interactive checkbox list
   - Currently active instance pre-selected
   - Must select at least one instance

2. **Backup Prompt**
   - Option to create server state backup before rollout
   - Defaults to creating a backup
   - Copies the project once per valid target, switches the copy to that instance, and force-pulls its server state
   - Creates `.zeysdk/backups/server-state_<TIMESTAMP>.zip`
   - Excludes `node_modules`, `.git`, `dist`, `build`, nested backups, and snapshots from copied backup state

**Process**

1. **Validation**
   - Verifies `.zeysdk` directory exists
   - Validates instance tokens
   - Checks app identifier in `zeyos.app.json`

2. **Execution Order**
   - Active instance processed first (if included)
   - Remaining instances processed sequentially
   - Acquires one project sync lock for the rollout and passes that ownership through every internal force-push
   - Automatically switches between instances
   - Returns to original instance when complete

3. **Error Handling**
   - Stops on first error unless `--force` used
   - Creates backups before acquiring the rollout lock and before making remote changes when requested
   - Attempts to restore the original *active-instance selection* after success or failure; it does not roll back remote pushes that already succeeded
   - Continues with valid instances if token validation fails with `--force`
   - Records forced validation, backup, and rollout failures and exits nonzero after all eligible instances have been processed
   - Still aborts when the combined backup ZIP itself cannot be created

**Error Handling**

| Error | Description | Resolution |
|-------|-------------|------------|
| No instances | No valid target instances found | Specify instances or use `--all` |
| Token invalid | Instance authentication failed | Check instance credentials |
| Backup failed | Unable to create backup | Verify write permissions |
| Rollout failed | Error during deployment | Check error message or use `--force` |
| Switch failed | Unable to change instance | Manually switch using `use` command |
| Lock busy | Another sync operation owns the project lock | Wait for it to finish; use `--break-lock` only after confirming the owner is stale |

**Notes**

- `rollout` can target explicit instance IDs, selected instances, or all linked instances
- The active instance is pre-selected during interactive rollout
- The command attempts to return to the original instance when rollout completes; failure to restore it makes the command fail
- Pushes share one rollout-owned lock and run one at a time; rollout does not push to instances concurrently
- `--force` continues across eligible instances when possible, but any recorded partial failure still makes the overall command fail with a nonzero exit
- A target that fails credential validation is skipped under `--force` and included in the final failure summary
- `--break-lock` is destructive to lock coordination and must not be used while another live SDK operation is working in the same project

**Best Practices**

- Run `zeysdk compare` before rolling out to important instances
- Create backups before broad rollouts
- Keep the generated server-state ZIP until the rollout has been verified
- Roll out to staging before production
- Prefer explicit instance IDs for release scripts
- Review failures before retrying with `--force`