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

Instance Selection
- If no instances specified, shows interactive checkbox list
- Currently active instance pre-selected
- Must select at least one instance
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

Validation
- Verifies .zeysdk directory exists
- Validates instance tokens
- Checks app identifier in zeyos.app.json
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
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