Install Bundle

The bundle install command installs multiple applications from a bundle file to a ZeyOS instance.

Bash

zeysdk bundle install <BUNDLE_FILE> <INSTANCE_ID> [options]

Parameters

Parameter	Description	Required	Example
BUNDLE_FILE	Path to bundle file	Yes	my-bundle
INSTANCE_ID	Target instance ID	Yes	dev-instance

Options

Option	Description
--token <token>	Token for the target instance
--url <url>	URL for the target instance
--yes	Disable the missing-host configuration prompt; fail if a missing host has no token/URL pair
-v, --verbose	Show detailed validation and installation output
-f, --force	Continue to later apps after non-authentication failures

Process

1. Validation

   • Verifies the bundle file exists
   • Validates the target instance ID
   • Requires --token and --url together when either is supplied
   • Ignores blank lines but rejects duplicate app entries
   • Accepts only safe single-directory names and verifies both their lexical paths and resolved real paths remain below the current directory
   • Verifies every listed path is a directory before changing remote state

2. Instance Configuration

   • Prompts to configure missing instances
   • Uses --token and --url for non-interactive setup
   • With --yes, fails instead of prompting when neither a matching saved host nor a token/URL pair is available
   • Validates and stores newly supplied credentials through the first successful app link rather than saving them before authentication

3. Installation

   • Opens each application directory
   • Links the app to the target instance
   • Switches to the target instance
   • Pushes application content
   • Restores the original working directory before processing the next app

4. Results

   • Reports each successful installation
   • Reports failures with the application name
   • Stops immediately on authentication failures, even with --force
   • With --force, continues after other per-app failures where possible
   • Fails the overall command if any installation failed, including partial-success runs

Examples

Bash

zeysdk bundle install my-bundle dev-instance
zeysdk bundle install my-bundle prod-instance --token abc123 --url https://cloud.zeyos.com/prod-instance
zeysdk bundle install my-bundle prod-instance --yes --token abc123 --url https://cloud.zeyos.com/prod-instance
zeysdk bundle install my-bundle staging --force --verbose

Error Handling

Error	Description	Resolution
Bundle not found	Bundle file is missing	Check file path
Invalid bundle	Bundle path is not a file	Use a valid bundle file
Empty bundle	Bundle contains no entries	Create a new bundle
Duplicate entry	The same app directory appears more than once	Remove duplicate lines
Unsafe app path	Entry is invalid, escapes the parent, or resolves outside it	Use a direct child directory name
Invalid instance	Instance is not configured	Configure the instance or pass --token and --url
Invalid token	Authentication failed	Check instance credentials
Directory error	App directory is missing	Verify bundle contents
Push failed	App installation failed	Check app configuration

Notes

• Bundle installation expects each listed app directory to exist below the current directory
• --token and --url must be provided together for non-interactive instance setup
• --yes fails fast when the instance is missing and credentials are not provided
• Existing credentials are reused when the target instance is already configured
• Each app is pushed with force enabled during installation
• --force controls whether bundle processing continues; it does not change the internal force-push behavior
• Bundle installation is not an all-or-nothing transaction. Successfully pushed apps remain changed if a later app fails
• A partial-success installation returns a nonzero exit so automation cannot mistake it for a complete deployment

Best Practices

• Run zeysdk bundle install from the same parent directory used to create the bundle
• Verify the target instance credentials before installing production bundles
• Inspect bundle files as untrusted input before installation; path traversal, duplicate entries, and out-of-tree symlinks are rejected
• Use zeysdk bundle create --apps to keep installation scope explicit
• Use a staging instance before installing the same bundle to production