Skip to main content
Skip to main content

Zerops CLI Commands Reference

Basic Usage​

zcli <command> [flags]
Tip

All commands support the -h, --help flag which displays help information about the command.

Configuration

For detailed information about configuration options, environment variables, and logging, see the Zerops CLI Configuration page.

Command Groups​

Account & VPN​

login​

Logs you into Zerops using a generated token or your login credentials.

zcli login <token>

logout​

Disconnects from VPN and logs out from your Zerops account.

zcli logout

vpn up​

Connects to the Zerops VPN.

zcli vpn up [project-id] [flags]

Flags:

  • --auto-disconnect - Automatically disconnect from VPN if already connected
  • --mtu int - Set custom MTU value for Wireguard interface (default: 1420)
  • -P, --project-id string - Required when you have access to multiple projects
Note

You can set a default project ID for VPN connections in a .zcli.yml file or via the ZEROPS_PROJECTID environment variable. See the Configuration page for details.

vpn down​

Disconnects from the Zerops VPN.

zcli vpn down
Note

For more detailed information about Zerops VPN configuration and troubleshooting, visit the VPN Documentation.

Project Management​

scope project​

Sets the scope for a project. All commands that require project ID will use the selected one.

zcli scope project [project-id]

scope reset​

Resets the scope for a project.

zcli scope reset

project create​

Creates a new project for a specified organization.

zcli project create [flags]

Flags:

  • --env-isolation string - Environment isolation rule [service, none] (default: "service")
  • --mode string - Project mode [light, serious] (default: "light")
  • --name string - Project name
  • --org-id string - Organization ID to create a project for
  • --out string - Output format using Go template syntax
  • --ssh-isolation string - SSH isolation rules (default: "vpn")
  • --tags strings - Project tags (comma-separated list or repeated flag)

project delete​

Deletes a project and all its services.

zcli project delete [project-id] [flags]

Flags:

  • --confirm - Skip confirmation prompts for destructive operations
  • -P, --project-id string - Required when you have access to multiple projects

project env​

Displays environment variables for the current project scope.

zcli project env [flags]

Flags:

  • --export - Prepends export keyword to each env in output: export {{.Key}}={{.Value}}
  • -P, --project-id string - Required when you have access to multiple projects
  • --service string - Service name, in which context the environment variables are output
  • --template string - Output template (default: "{{.Key}}={{.Value}}")
  • --user-only - Exclude all non user env variables

project list​

Lists all projects you have access to.

zcli project list
Import YAML vs. zerops.yaml — two different files

Zerops uses two YAML files that serve different roles. Don't confuse them.

Import YAML — an Infrastructure-as-Code manifest used to provision infrastructure, configure routing, and seed secrets. Today it lets you create projects and services via the import and export mechanisms; routing capabilities are on the roadmap.

zerops.yaml — the application deployment description file. It tells Zerops how to build, deploy, and run a runtime application, and is typically committed to the application's source-code repository.

project project-import​

Creates a new project with one or more services from an Import YAML definition.

zcli project project-import <importYamlPath> [flags]

Flags:

  • --org-id string - Organization ID where the project should be created (required for multiple organizations)
  • --working-dir string - Sets a custom working directory (default: "./")

project service-import​

Creates one or more services in an existing project from an Import YAML definition.

zcli project service-import <importYamlPath> [flags]

Flags:

  • -P, --project-id string - Required when you have access to multiple projects

Service Operations​

service list​

Lists all services in a project.

zcli service list [flags]

Flags:

  • -P, --project-id string - Required when you have access to multiple projects

service create​

Creates a new service for a specified project.

zcli service create [flags]

Flags:

  • --env strings - Environment variables to be set as secrets (comma-separated or repeated flag)
  • --env-file string - File with environment variables (max 1.0 MiB)
  • --env-isolation string - Environment isolation rule [service, none] (default: "service")
  • --mode string - Service mode [ha, non_ha] (default: "non_ha")
  • --name string - Service name
  • --noop - Creates service only if none with the same name exists
  • --out string - Output format using Go template syntax
  • -P, --project-id string - Required when you have access to multiple projects
  • --ssh-isolation string - SSH isolation rules (default: "vpn")
  • --start-without-code - Start service immediately without deployment
  • --working-dir string - Sets custom working directory (default: "./")
  • --zerops-yaml-path string - Sets custom path to zerops.yml file

service push​

Builds your application in Zerops and deploys it. This is the recommended way to deploy your code.

zcli service push [service-id-or-name] [flags]

Flags:

  • --archive-file-path string - Creates a tar.gz archive with application code
  • -g, --deploy-git-folder - Include the .git folder in the upload
  • --disable-logs - Disable logs during push
  • --no-git - Upload entire working directory as-is (cannot be combined with --workspace-state or --deploy-git-folder)
  • -P, --project-id string - Required when you have access to multiple projects
  • -S, --service-id string - Required when you have access to multiple services
  • --setup string - Choose setup to use from zerops.yml
  • -v, --verbose - Log additional debug data to the zCLI debug log file
  • --version-name string - Adds a custom version name
  • --working-dir string - Sets a custom working directory (default: "./")
  • -w, --workspace-state string - Defines a version of workspace to push:
  • clean - pushes the HEAD without local changes
  • staged - pushes only staged files
  • all - pushes all staged and unstaged files (default)
  • --zerops-yaml-path string - Sets a custom path to the zerops.yml file
Tip

You can also use zcli push as shorthand for zcli service push.

To avoid specifying --project-id and --service-id flags repeatedly, you can set default values in a .zcli.yml file or via environment variables. See the Configuration page for details.

service deploy​

Deploys your application to Zerops. Similar to push but focuses on deployment only.

zcli service deploy [service-id-or-name]

Flags: Same as service push command.

service start/stop​

Commands to start or stop a Zerops service.

zcli service start [service-id-or-name] [flags]
zcli service stop [service-id-or-name] [flags]

Flags for both commands:

  • -P, --project-id string - Required when you have access to multiple projects
  • -S, --service-id string - Required when you have access to multiple services

service delete​

Deletes a Zerops service.

zcli service delete [service-id-or-name] [flags]

Flags:

  • --confirm - Skip confirmation prompts for destructive operations
  • -P, --project-id string - Required when you have access to multiple projects
  • -S, --service-id string - Required when you have access to multiple services

service enable-subdomain​

Enables access to your service through a Zerops subdomain.

zcli service enable-subdomain [service-id-or-name] [flags]

Flags:

  • -P, --project-id string - Required when you have access to multiple projects
  • -S, --service-id string - Required when you have access to multiple services

service log​

Gets service runtime or build logs to stdout.

zcli service log [flags]

Flags:

  • --follow - Continuously poll for new log messages
  • --format string - Log output format (FULL, SHORT, JSON, JSONSTREAM) (default: "FULL")
  • --format-template string - Custom log format
  • --limit int - Number of recent log messages to return (1–1000, default: 100)
  • --message-type string - Select APPLICATION or WEBSERVER log messages (default: "APPLICATION")
  • --minimum-severity string - Filter by severity level
  • -P, --project-id string - Required when you have access to multiple projects
  • -S, --service-id string - Required when you have access to multiple services
  • --show-build-logs - Show build logs instead of runtime logs

Utility Commands​

env​

Displays global environment variables and their paths.

zcli env

version​

Shows the current zCLI version.

zcli version

upgrade​

Replaces the running zCLI binary in place with a newer release. Downloads the matching asset from GitHub Releases, verifies it against the release's checksums.txt, then atomically swaps the binary.

Availability

The upgrade command is available in zCLI v1.1.0 and later. On earlier versions, install the newer release via install.sh (or your package manager) first.

zcli upgrade [flags]

Flags:

  • --check - Print the current and latest version, then exit without installing. Intended for scripts and package managers.
  • --yes - Skip the confirmation prompt.
  • --version string - Install a specific release tag (e.g. v1.1.0) instead of the latest. Allows downgrades.
  • --pick-version - Open an interactive picker listing every release. Mutually exclusive with --version.
  • --include-pre-release - Include pre-release and -rc tags in the --pick-version picker. Stable releases only by default.
  • --no-cache - Bypass the on-disk version cache and resolve latest directly from the release API. Useful right after a release goes out, before the local cache refreshes.
  • --download-timeout string - Overall timeout for the binary download as a Go duration (e.g. 5m, 90s). 0 disables the timeout. Default 2m.

Examples:

# Interactive upgrade to the latest release
zcli upgrade

# Unattended upgrade, suitable for scripts
zcli upgrade --yes

# Install a specific tag (and accept downgrade)
zcli upgrade --version v1.1.0 --yes

# Pick from a table of every release
zcli upgrade --pick-version

Exit codes for --check​

zcli upgrade --check is designed for scripting. It prints Current:, Latest: (and Target: when --version is set) on stdout and exits with:

  • 0 - up to date.
  • 1 - a newer release is available.
  • 2 - lookup failed (network, invalid --version tag, etc.); the error is on stderr.
  • 3 - the resolved target predates v1.1.0 (the first release that ships checksums.txt) and cannot be installed by zcli upgrade. Use the install script instead - see below.

Package-manager installs​

When zCLI is installed through a package manager (npm, Homebrew, nix, .deb), zcli upgrade refuses to swap the binary and prints the channel-appropriate command instead - for example npm install -g @zerops/zcli or brew upgrade zcli. --check still works against any install.

Downgrading below v1.1.0​

Releases before v1.1.0 don't ship the checksums.txt asset that zcli upgrade verifies against, so they can only be installed via the install script:

curl -fsSL https://raw.githubusercontent.com/zeropsio/zcli/main/install.sh | sh -s -- v1.0.67

zcli upgrade --version <old-tag> and --pick-version will print this hint when the chosen target requires the install script.

show-debug-logs​

Displays debug logs for troubleshooting.

zcli show-debug-logs

support​

Displays information about how to contact Zerops support.

zcli support

completion​

Generates shell autocompletion scripts.

zcli completion {bash|fish|powershell|zsh}

Available Shells:

  • bash - Generate an autocompletion script for Bash
  • fish - Generate an autocompletion script for Fish
  • powershell - Generate autocompletion script for PowerShell
  • zsh - Generate an autocompletion script for Zsh

Example:

zcli completion bash > ~/.zerops-completion.bash
echo 'source ~/.zerops-completion.bash' >> ~/.bashrc
Previous
Configuration
Next
zsc
Docs theme & components by the amazing medusajs.com
© 2026 Zerops s.r.o..