Skip to main content
Skip to main content

Using Zerops Setup Control (zsc)

Zerops Setup Control (zsc) is a command-line utility automatically installed in all Zerops containers enabling developers to manage and control container environments directly from within both runtime and build contexts.

Zerops Setup Control provides essential capabilities for container management, including resource scaling, technology installation, and environment configuration.

Zerops Setup Control commands can be executed in two ways:

  • Manual execution:
    • From the web terminal interface in Zerops GUI
    • Using SSH connections to your containers
  • Automated execution:
    • As part of your zerops.yaml configuration file

Usage​

zsc <command> [flags]

Commands​

help​

This command lists available commands and flags on a command by placing help, -h or --help flag after the command.

zsc help
# or
zsc --help
# or
zsc -h

completion​

Generate the autocompletion script for zsc for the specified shell.

zsc completion [command]

Available sub-commands​

  • bash: Generate the autocompletion script for bash
  • fish: Generate the autocompletion script for fish
  • powershell: Generate the autocompletion script for powershell
  • zsh: Generate the autocompletion script for zsh

Available flags​

  • -h, --help: Help for the completion command

backup-create​

Creates a backup of any specified stack in your project.

zsc backup-create <stackName>

Required parameters​

  • <stackName>: Name of the stack to backup

Available flags​

  • -h, --help: Help for the backup-create command

Example​

zsc backup-create db

cdn​

Manages CDN (Content Delivery Network) operations for your Zerops services.

zsc cdn [command]

Available sub-commands​

  • purge: Invalidates cached content from the CDN for a specific domain. The purge command allows you to ensure that the most up-to-date content is being served to visitors after making updates to your site.

Available flags​

  • -h, --help: Help for the cdn command

Examples​

# Purge all CDN cache for a specific domain
zsc cdn purge example.com
# Purge all content using wildcard pattern
zsc cdn purge example.com "/*"
# Purge CDN cache for a specific file (note the $ suffix)
zsc cdn purge example.com "/path/to/my-file$"
# Purge CDN cache for a specific directory
zsc cdn purge example.com "/images/"
important
  • This command must be executed in any container within the project that has the CDN-enabled domain active
  • Currently, the purge command only works for the Static Mode CDN

crontab​

Manages scheduled tasks that are defined in your zerops.yaml configuration.

zsc crontab [command]

Available sub-commands​

  • list: List all crontabs defined in zerops.yaml
  • run: Execute crontab command defined in zerops.yaml

Available flags​

  • -h, --help: Help for the crontab command

execOnce​

Execute a command exactly once across all containers in a service, preventing duplicate execution in high-availability setups.

zsc execOnce [flags] <key> -- <command> [args...]

Required parameters​

  • <key>: A unique identifier for the execution
  • --: Standard separator indicating the end of options and beginning of the command
  • <command> [args...]: The actual command to execute and its arguments

Available flags​

  • -r, --retryUntilSuccessful: Retry command until it succeeds
  • -v, --verbose: Verbose output
  • -h, --help: Help for the execOnce command

Behavior​

  • On success: All containers proceed with their tasks
  • On failure: All containers report the command as failed
  • With --retryUntilSuccessful: The command is retried on a different container until it succeeds

Examples​

# Execute a command once for the entire service stack
zsc execOnce someStaticKey -- /var/www/myBinary some initial command --flag="value" --flag2="value2"

# Run migrations for each new app version deployed to Zerops
zsc execOnce ${ZEROPS_appVersionId} -- php /var/bin/console migrations:continue
Info

This command is ideal for database migrations, initialization scripts, and other operations that should only run once in clustered environments.

fail-me​

Deliberately fails the current container for testing purposes.

zsc fail-me

Available flags​

  • -h, --help: Help for the fail-me command

install​

Run install commands for the specified base technology in your runtime container.

zsc install <baseName> [flags]

Required parameters​

  • <baseName>: The technology and version to install - see the full list of supported base environments.

Available flags​

  • --buildBase <string>: Build base (default "php@8.4")
  • --buildOs <string>: Build os (default "alpine")
  • -m, --mode <string>: Mode (default "RUNTIME")
  • --runBase <string>: Run base (default "php-nginx@8.4")
  • --runOs <string>: Run os (default "alpine")
  • -h, --help: Help for the install command

Examples​

zsc install rust@1.78
zsc install dotnet@8
zsc install nginx@1.22

Example usage in zerops.yaml​

zerops:
  - setup: nodejsapp
    build:
      os: ubuntu
      base:
        - nodejs@22
        - python@3.11
    run:
      os: ubuntu
      base: nodejs@22
      prepareCommands:
        - zsc install python@3.11

noop​

Keep a container alive indefinitely with a non-terminating process.

zsc noop [flags]

Available flags​

  • -s, --silent: Disables output to StdOut
  • -h, --help: Help for the noop command

Examples​

zsc noop
zsc noop --silent
Info

The noop command is especially useful for:

  • Debugging build failures by keeping containers alive for investigation
  • Supporting applications that run as background daemons
  • Keeping service containers active when your app doesn't have a foreground process
  • As a start command in zerops.yaml for services that don't have a natural blocking command

Usage in zerops.yaml​

zerops:
  - setup: myapp
    run:
      start: zsc noop
      ports:
        - port: 8080
          http: true

object-storage​

Manages object storage operations for backups and restores.

zsc object-storage [command]

Available flags​

  • -h, --help: Help for the object-storage command

When using an object storage service, the command requires the following environment variables to be defined:

  • objectstorage_apiUrl - API URL of the object storage service
  • objectstorage_accessKeyId - Access key ID for authentication
  • objectstorage_secretAccessKey - Secret access key for authentication
  • objectstorage_bucketName - Name of the bucket to use

These environment variables will be automatically available if the object storage service has envIsolation: none configured, or if the entire project has envIsolation: none set. Otherwise, you need to explicitly reference these environment variables in your zerops.yaml file.

Sub-commands​

Common parameters​

All sub-commands share these parameters:

  • --storage <string>: Name of the object storage service
  • --name <string>: Name of the backup in storage
  • --silent, -s: Suppresses command output (default: false)
  • --no-fail: Prevents command failure with exit code 1 (default: false)

list - Lists all available backups in the specified storage

zsc object-storage list --storage <storage-name> --name <backup-name>

backup - Creates a backup of specified directories to object storage

zsc object-storage backup <directory1> [<directory2>...] --storage <storage-name> --name <backup-name> [options]

Arguments:

  • <directory>: One or more directories to back up (at least one required)

Additional options:

  • --truncate-count <number>: Number of most recent backups to keep after successful backup (default: 0)
  • -C, --change-directory <directory>: Change to directory before operation

restore - Restores a backup from object storage to specified or original locations

zsc object-storage restore <directory> --storage <storage-name> --name <backup-name> [options]

Arguments:

  • <directory>: Directory to restore to. If omitted, files are restored to their original locations

Additional options:

  • --dryRun: Simulates restore operation without performing actual changes
  • --overwrite: Allows overwriting existing files during restore
  • --index <number>: Specifies which backup to restore. Non-negative values count from newest (0 = newest, 1 = second newest), negative values count from oldest (-1 = oldest, -2 = second oldest) (default: 0)
  • --ignore-non-existing: Prevents command failure if backup does not exist
  • --strip-components <number>: Strip NUMBER leading components from file names on extraction

truncate - Removes old backups, keeping only the most recent ones

zsc object-storage truncate --storage <storage-name> --name <backup-name> [options]

Additional options:

  • --dryRun: Simulates truncate operation without performing actual deletions (default: false)
  • --truncate-count <number>: Number of most recent backups to keep (default: 5)

Examples​

# List all backups
zsc object-storage list --storage objectstorage --name daily-backup

# Create a backup with retention
zsc object-storage backup /var/www --storage objectstorage --name web-backup --truncate-count 5

# Restore with dry run preview
zsc object-storage restore --storage objectstorage --name database-backup --dryRun

# Clean up old backups
zsc object-storage truncate --storage objectstorage --name logs-backup --truncate-count 3

Example usage in zerops.yaml​

zerops:
  - setup: app
    run:
      initCommands:
        - "zsc object-storage restore --storage objectstorage --name $ZEROPS_StackName --ignore-non-existing ./data/"
      crontab:
        - timing: "*/10 * * * *"
          command: "zsc object-storage backup --storage objectstorage --name $ZEROPS_StackName --truncate-count 5 ./data/"
          allContainers: false

resources​

Displays the current resource scaling configuration for the container.

zsc resources

Available flags​

  • -h, --help: Help for the resources command

Example output​

{
    "cpuCoreCount": 1,
    "memoryGBytes": 0.25,
    "diskGBytes": 1
}
  • zsc scale: Dynamically adjust resource allocations

scale​

Dynamically adjust CPU or memory resources for the current container for a specified duration.

zsc scale {cpu|ram} {<value> <duration>|auto}

Required parameters​

  • cpu|ram: Resource type to scale (either CPU cores or RAM)
  • <value> <duration> or auto: Scale value and duration, or "auto" to disable custom scaling

Available flags​

  • -h, --help: Help for the scale command

Supported values​

  • For RAM: Value must be suffixed by a unit (KiB, MiB, GiB); number may be a float.
  • For CPU: Value must not be suffixed; number must be an integer.
  • "auto": Disables any custom scaling set via this command and must be used without the duration parameter.
  • "min" and "max": Set the container to its CURRENT min and max values.
  • Numeric values can be prefixed with "+" for relative scaling, adding the requested value to currently used resources.
  • Duration must be suffixed by a unit (s = seconds, m = minutes, h = hours, d = days) and cannot be less than 10 minutes.

Examples​

zsc scale cpu auto
zsc scale cpu 5 1h
zsc scale cpu +2 30m
zsc scale cpu min 10m
zsc scale ram auto
zsc scale ram 5GB 1h
zsc scale ram +2.5GB 600s
zsc scale ram max 10m
Info
  • Resource adjustments take effect within approximately 10 seconds
  • The container cannot be scaled above or below its max/min resources set in the vertical autoscaling configuration
  • If you scale to a value that exceeds the maximum set limit (e.g., 10GB RAM when max is 5GB), the container will only receive the maximum allowed resources
  • If service limits are changed while custom scaling is active, the container will automatically adjust to the new boundaries
  • If the service auto-scaling configuration is updated, you must call the scale command again to apply custom scaling
Caution

If there are insufficient resources on the current server, the container might be moved to another node with available resources, which will reset the scale duration. The container will scale down automatically if resources are not utilized, or if the scale command duration expires.

setSecretEnv​

Securely update environment variables containing sensitive information.

zsc setSecretEnv <key> <content>

Arguments​

  • <key>: The name of the environment variable to set
  • <content>: The new value for the variable, or - to read from stdin

Available flags​

  • -h, --help: Help for the setSecretEnv command

Examples​

# Set a secret environment variable directly
zsc setSecretEnv SECRET_KEY "new_value"

# Set a secret environment variable from stdin (useful for multi-line values or piping)
echo "new_value" | zsc setSecretEnv SECRET_KEY -

# Set a secret API key from a file
cat api_key.txt | zsc setSecretEnv API_KEY -
Info

Secret environment variables are encrypted at rest and securely distributed to your containers. Use this command for storing sensitive configuration like API keys, tokens, and passwords.

shared-storage​

Manages shared storage volumes for persistent data storage.

zsc shared-storage [command]

Available sub-commands​

  • mount: Mounts the shared storage
  • unmount: Unmounts the shared storage
  • wait: Waits for readiness of the storage mount

Available flags​

  • -h, --help: Help for the shared-storage command

Examples​

# View shared-storage help
zsc shared-storage --help

# Mount a shared storage volume
zsc shared-storage mount <storage-name>

# Unmount a shared storage volume
zsc shared-storage unmount <storage-name>

# Wait for a storage mount to be ready
zsc shared-storage wait <storage-name>

test​

Run diagnostic tests to verify connectivity and service availability.

zsc test tcp <host>:<port> [flags]

Required parameters​

  • <host>:<port>: Host and port to test connectivity to

Available flags​

  • --timeout <duration>: Maximum test duration (default: 30s)
  • --dialTimeout <duration>: Single attempt timeout (default: 2s)
  • -4: Force IPv4
  • -6: Force IPv6
  • -h, --help: Help for the test tcp command

Example​

# Test TCP connection to a host
zsc test tcp api.zerops:80
zsc test tcp database:5432 --timeout 1m

version​

Displays the current version of Zsc CLI.

zsc version

Available flags​

  • -h, --help: Help for the version command
Previous
Commands
Next
Public Access
Docs theme & components by the amazing medusajs.com
© 2025 Zerops s.r.o..