CLI Reference - Zerops

zCLI is the official command-line tool for Zerops that allows you to manage services, deploy applications, and configure infrastructure directly from your terminal.

Installation

Linux / macOS

curl -L https://zerops.io/zcli/install.sh | sh

zCLI will be installed in /usr/bin or /usr/local/bin.

Windows

Execute the following command in PowerShell:

irm https://zerops.io/zcli/install.ps1 | iex

zCLI will be installed in C:\Program Files\ or C:\Program Files (x86)\.

Using Package Managers

npm i -g @zerops/zcli

NixOS

Make sure nix-command and flakes are enabled. Alternatively, use --extra-experimental-features 'nix-command flakes' with nix.

git clone https://github.com/zeropsio/zcli
cd zcli
nix develop
nix build

The zCLI binary will be available in result/bin.

Manual Installation

Download the latest release directly from GitHub.

Supported Platforms

Linux (x86 & x64)
macOS (x86-64 & ARM64)
Windows (x64)

Personal Access Tokens

Personal access tokens allow you to securely access Zerops from the command line.

Creating an Access Token

Go to Access Token Management in the Zerops GUI
Click Generate a new access token
Copy the generated token

Store your access token securely. You won’t be able to see it again after creation.

Using an Access Token

zcli login <token>

Managing Access Tokens

You can create multiple access tokens and manage them in the Zerops GUI. Delete tokens anytime from the Access Token Management page.

Basic Usage

zcli <command> [flags]

All commands support the -h, --help flag to display help information.

Configuration

zCLI supports configuration via:

Configuration files (.zcli.yml)
Environment variables (ZEROPS_*)
Command-line flags

For detailed configuration options, see the Configuration Guide.

Command Reference

Account & VPN

zcli login <token>

logout

Disconnect from VPN and log out from your Zerops account.

zcli logout

vpn up

Connect to the Zerops VPN for secure access to your services.

zcli vpn up [project-id] [flags]

--auto-disconnect

boolean

Automatically disconnect from VPN if already connected

--mtu

number

default:1420

Set custom MTU value for WireGuard interface

-P, --project-id

string

Project ID (required when you have access to multiple projects)

Set a default project ID in .zcli.yml or via the ZEROPS_PROJECTID environment variable. See Configuration.

vpn down

Disconnect from the Zerops VPN.

zcli vpn down

Project Management

scope project

Set the scope for a project. All commands requiring a project ID will use the selected one.

zcli scope project [project-id]

scope reset

Reset the project scope.

zcli scope reset

project create

Create a new project for a specified organization.

zcli project create [flags]

--env-isolation

string

default:"service"

Environment isolation rule: service or none

--mode

string

default:"light"

Project mode: light or serious

--name

string

Project name

--org-id

string

Organization ID to create the project for

--tags

string[]

Project tags (comma-separated or repeated flag)

project delete

Delete a project and all its services.

zcli project delete [project-id] [flags]

--confirm

boolean

Skip confirmation prompts for destructive operations

This action is irreversible. All services and data within the project will be permanently deleted.

project env

Display environment variables for the current project scope.

zcli project env [flags]

--export

boolean

Prepend export keyword to each env: export {{.Key}}={{.Value}}

--service

string

Service name in which context the environment variables are output

--template

string

default:"{{.Key}}={{.Value}}"

Output template

--user-only

boolean

Exclude all non-user environment variables

project list

List all projects you have access to.

zcli project list

project project-import

Create a new project with one or more services from a YAML definition.

zcli project project-import <importYamlPath> [flags]

--org-id

string

Organization ID (required for multiple organizations)

--working-dir

string

default:"./"

Custom working directory

Example:

zcli project project-import ./zerops-project-import.yml

See the Import YAML Reference for file format details.

project service-import

Create one or more services in an existing project from a YAML definition.

zcli project service-import <importYamlPath> [flags]

-P, --project-id

string

Project ID (required when you have access to multiple projects)

Example:

zcli project service-import ./zerops-services.yml --project-id abc123

Service Operations

service list

List all services in a project.

zcli service list [flags]

-P, --project-id

string

Project ID (required when you have access to multiple projects)

service create

Create a new service in a specified project.

zcli service create [flags]

--env

string[]

Environment variables as secrets (comma-separated or repeated flag)

--env-file

string

File with environment variables (max 1.0 MiB)

--mode

string

default:"non_ha"

Service mode: ha or non_ha

--name

string

Service name

--noop

boolean

Create service only if none with the same name exists

service push

Build and deploy your application to Zerops. This is the recommended deployment method.

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

--archive-file-path

string

Create a tar.gz archive with application code

-g, --deploy-git-folder

boolean

Include the .git folder in the upload

--disable-logs

boolean

Disable logs during push

--no-git

boolean

Upload entire working directory as-is (cannot be combined with —workspace-state or —deploy-git-folder)

-P, --project-id

string

Project ID (required when you have access to multiple projects)

-S, --service-id

string

Service ID (required when you have access to multiple services)

--setup

string

Choose setup to use from zerops.yml

-v, --verbose

boolean

Log additional debug data to the zCLI debug log file

--version-name

string

Add a custom version name

--working-dir

string

default:"./"

Custom working directory

-w, --workspace-state

string

default:"all"

Version of workspace to push:

clean - HEAD without local changes
staged - Only staged files
all - All staged and unstaged files (default)

--zerops-yaml-path

string

Custom path to the zerops.yml file

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

Examples:

# Push current directory to service
zcli push

# Push with custom version name
zcli service push --version-name "v1.2.3"

# Push only staged changes
zcli service push --workspace-state staged

# Push with verbose logging
zcli service push -v

service deploy

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

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

Accepts the same flags as service push.

service start / stop

Start or stop a Zerops service.

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

-P, --project-id

string

Project ID (required when you have access to multiple projects)

-S, --service-id

string

Service ID (required when you have access to multiple services)

service delete

Delete a Zerops service.

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

--confirm

boolean

Skip confirmation prompts

This action is irreversible. All data associated with the service will be permanently deleted.

service enable-subdomain

Enable access to your service through a Zerops subdomain.

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

Zerops subdomains are suitable for testing and development. For production, configure a custom domain.

service log

Get service runtime or build logs to stdout.

zcli service log [flags]

--follow

boolean

Continuously poll for new log messages

--format

string

default:"FULL"

Log output format: FULL, SHORT, JSON, or JSONSTREAM

--format-template

string

Custom log format template

--limit

number

default:100

Number of recent log messages to return (1-1000)

--message-type

string

default:"APPLICATION"

Select APPLICATION or WEBSERVER log messages

--minimum-severity

string

Filter by severity level

--show-build-logs

boolean

Show build logs instead of runtime logs

Examples:

# Follow application logs
zcli service log --follow

# View last 500 logs in JSON format
zcli service log --limit 500 --format JSON

# View build logs
zcli service log --show-build-logs

Utility Commands

env

Display global environment variables and their paths.

zcli env

version

Show the current zCLI version.

zcli version

show-debug-logs

Display debug logs for troubleshooting.

zcli show-debug-logs

support

Display information about contacting Zerops support.

zcli support

completion

Generate shell autocompletion scripts.

zcli completion {bash|fish|powershell|zsh}

Available shells:

bash - Bash shell
fish - Fish shell
powershell - PowerShell
zsh - Zsh shell

Example setup for Bash:

zcli completion bash > ~/.zerops-completion.bash
echo 'source ~/.zerops-completion.bash' >> ~/.bashrc
source ~/.bashrc

Example setup for Zsh:

zcli completion zsh > "${fpath[1]}/_zcli"

Common Workflows

Initial Setup

Install zCLI
Create a personal access token in the Zerops GUI
Log in with the token

zcli login <your-token>

Deploy an Application

Ensure you have a zerops.yaml in your repository root
Navigate to your project directory
Push your code

zcli push

Import a Project

Create an import YAML file (see Import YAML Reference)
Run the import command

zcli project project-import ./my-project.yml

Connect via VPN

Connect to the VPN
Access your services using their internal hostnames

zcli vpn up
# Now you can access services like: psql -h db ...

View Logs

# Follow application logs
zcli service log --follow

# View recent build logs
zcli service log --show-build-logs --limit 200

Configuration Best Practices

Use Configuration Files

Create a .zcli.yml in your project root:

projectId: your-project-id
serviceId: your-service-id
workspaceState: all

Use Environment Variables

For CI/CD pipelines:

export ZEROPS_TOKEN=<your-token>
export ZEROPS_PROJECTID=<project-id>
export ZEROPS_SERVICEID=<service-id>

zcli login $ZEROPS_TOKEN
zcli service push

Version Control

Add to .gitignore:

.zcli.yml
*.log

Commit a template instead:

# .zcli.yml.example
projectId: ""
serviceId: ""

Troubleshooting

Enable Verbose Logging

zcli service push --verbose

View Debug Logs

zcli show-debug-logs

# Or directly
cat ~/.config/zerops/zerops.log

VPN Connection Issues

Check the MTU setting:

zcli vpn up --mtu 1280

See the VPN Documentation for more troubleshooting steps.

Permission Errors

Ensure you have the necessary permissions in your Zerops account. Contact your project administrator if needed.

CI/CD Integration

GitHub Actions

name: Deploy to Zerops

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install zCLI
        run: curl -L https://zerops.io/zcli/install.sh | sh
      
      - name: Deploy to Zerops
        env:
          ZEROPS_TOKEN: ${{ secrets.ZEROPS_TOKEN }}
          ZEROPS_PROJECTID: ${{ secrets.ZEROPS_PROJECTID }}
          ZEROPS_SERVICEID: ${{ secrets.ZEROPS_SERVICEID }}
        run: |
          zcli login $ZEROPS_TOKEN
          zcli service push

GitLab CI

deploy:
  stage: deploy
  image: node:20
  script:
    - curl -L https://zerops.io/zcli/install.sh | sh
    - zcli login $ZEROPS_TOKEN
    - zcli service push
  only:
    - main

CLI Configuration

Detailed configuration options and environment variables

CLI Commands

Complete command reference

Import YAML

Learn about project and service import format

zerops.yaml

Build and runtime configuration

Need help? Join our Discord community.

Get Started

Core Concepts

Configuration

​Installation

​Linux / macOS

​Windows

​Using Package Managers

​NixOS

​Manual Installation

​Supported Platforms

​Personal Access Tokens

​Creating an Access Token

​Using an Access Token

​Managing Access Tokens

​Basic Usage

​Configuration

​Command Reference

​Account & VPN

​login

​logout

​vpn up

​vpn down

​Project Management

​scope project

​scope reset

​project create

​project delete

​project env

​project list

​project project-import

​project service-import

​Service Operations

​service list

​service create

​service push

​service deploy

​service start / stop

​service delete

​service enable-subdomain

​service log

​Utility Commands

​env

​version

​show-debug-logs

​support

​completion

​Common Workflows

​Initial Setup

​Deploy an Application

​Import a Project

​Connect via VPN

​View Logs

​Configuration Best Practices

​Use Configuration Files

​Use Environment Variables

​Version Control

​Troubleshooting

​Enable Verbose Logging

​View Debug Logs

​VPN Connection Issues

​Permission Errors

​CI/CD Integration

​GitHub Actions

​GitLab CI

​Related Resources

CLI Configuration

CLI Commands

Import YAML

zerops.yaml

Build docs developers (and LLMs) love

Installation

Linux / macOS

Windows

Using Package Managers

NixOS

Manual Installation

Supported Platforms

Personal Access Tokens

Creating an Access Token

Using an Access Token

Managing Access Tokens

Basic Usage

Configuration

Command Reference

Account & VPN

login

logout

vpn up

vpn down

Project Management

scope project

scope reset

project create

project delete

project env

project list

project project-import

project service-import

Service Operations

service list

service create

service push

service deploy

service start / stop

service delete

service enable-subdomain

service log

Utility Commands

env

version

show-debug-logs

support

completion

Common Workflows

Initial Setup

Deploy an Application

Import a Project

Connect via VPN

View Logs

Configuration Best Practices

Use Configuration Files

Use Environment Variables

Version Control

Troubleshooting

Enable Verbose Logging

View Debug Logs

VPN Connection Issues

Permission Errors

CI/CD Integration

GitHub Actions

GitLab CI

Related Resources