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

env-replace​

Renders template files with environment variables. Placeholders in the form {{.VARIABLE_NAME}} are replaced with the value of the environment variable of that name and the result is written to the target. Source files are never modified.

zsc env-replace <source> <target> [flags]

envReplace is accepted as an alias. This is a different mechanism than the envReplace key in zerops.yaml, which rewrites %%VARIABLE%%-style placeholders in the deployed files in place.

Required parameters​

  • <source>: Template file or directory to read
  • <target>: File or directory to write the rendered result to

Both paths can be absolute (starting with /) or relative to the current working directory.

  • Source directory: traversed recursively, every file is rendered to the same relative path under the target directory. Missing target directories are created.
  • Source file: rendered to the target path. When the target is an existing directory, the file is written into it under its original name.

The target must not be the source itself or a path inside the source directory.

Available flags​

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

Template syntax​

Templates use Go text/template syntax. Use {{if .OPTIONAL}}...{{end}} to guard a variable that may be unset. A file name ending with a permission suffix such as script.sh.0755 is written without the suffix and with that file mode.

Examples​

# Render every template under /template/etc into /etc
zsc env-replace /template/etc /etc

# Render a single file to an explicit target path
zsc env-replace /template/etc/example.conf /etc/example.conf

# Relative paths are resolved from the current working directory
zsc env-replace templates/nginx.conf /etc/nginx/nginx.conf

Example usage in zerops.yaml​

zerops:
  - setup: app
    run:
      initCommands:
        - zsc env-replace ./templates/app.conf /etc/app/app.conf
      start: /usr/bin/app --config /etc/app/app.conf

exec-once​

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

zsc exec-once [flags] <key> -- <command> [args...]

execOnce is accepted as an alias.

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 exec-once 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 exec-once someStaticKey -- /var/www/myBinary some initial command --flag="value" --flag2="value2"

# Run migrations for each new app version deployed to Zerops
zsc exec-once ${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 shares them with your service, either with envIsolation: none or with envIsolation: service@<your-hostname> (set on the object storage service or inherited from the project). 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.

set-env​

Set or update an environment variable of the current service.

zsc set-env <key> <content> [flags]

setEnv is accepted as an alias.

Arguments​

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

Available flags​

  • --sensitive: Store the variable as a secret. When omitted, an existing variable keeps its current secret setting and a new one is created as a plain variable
  • -h, --help: Help for the set-env command

Examples​

# Set an environment variable directly
zsc set-env KEY "new_value"

# Set an environment variable from stdin (useful for multi-line values or piping)
echo "new_value" | zsc set-env KEY -

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

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

set-secret-env​

Caution

Deprecated, use set-env --sensitive instead. The command keeps working for existing scripts and recipes, setSecretEnv is accepted as an alias.

zsc set-secret-env <key> <content>

Behaves like set-env with --sensitive always on.

shared-storage​

Mounts a SeaweedFS service at /mnt/<storage-name> with weed mount. The command dates from the deprecated Shared Storage and keeps its name, it is a shortcut for running weed mount yourself: it creates the directory, hands it to the zerops user, connects to the filer of the first storage container (node-stable-1.db.<storage-name>.zerops:8888) and passes a RAM-lean tuning (-volumeServerAccess=direct -cacheCapacityMB=0 -concurrentWriters=1 -chunkSizeLimitMB=1), see Mounting from a runtime service. mount runs in the foreground, so use it as a start command. With --background it detaches the mount process and returns once the mount is ready, which is the form for init commands. Both need sudo.

zsc shared-storage [command]

Available sub-commands​

  • mount: Mounts the storage (foreground, --background detaches the mount and exits when it is ready)
  • unmount: Unmounts the storage and removes the mount directory
  • 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 SeaweedFS service at /mnt/<storage-name> (foreground, as a start command)
sudo zsc shared-storage mount <storage-name>

# Mount it in the background (in init commands), returns once the mount is ready
sudo zsc shared-storage mount <storage-name> --background

# Unmount it
sudo 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
Overview
Docs theme & components by the amazing medusajs.com
© 2026 Zerops s.r.o..