Commands Reference

This page provides a comprehensive reference for all available commands in zCLI. For configuration options and environment variables, see the Configuration guide.

Basic Usage

zcli <command> [flags]

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

Command Groups

Account & VPN

Authentication and VPN connection management

Project Management

Create and manage projects

Service Operations

Deploy and manage services

Utility Commands

Helper commands and tools

Account & VPN

Logs you into Zerops using a Personal Access Token.

zcli login <token>

token

string

required

Your Personal Access Token from Access Token management

Example:

zcli login eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

logout

Disconnects from VPN and logs out from your Zerops account.

zcli logout

vpn up

Connects to the Zerops VPN, allowing secure access to your services.

zcli vpn up [project-id] [flags]

project-id

string

The ID of the project to connect to. Can also be set via configuration.

Flags:

--auto-disconnect

boolean

Automatically disconnect from VPN if already connected to another project

--mtu

integer

default:"1420"

Set custom MTU value for Wireguard interface

-P, --project-id

string

Required when you have access to multiple projects (alternative to positional argument)

Example:

# Connect using project ID
zcli vpn up abc123def456

# Connect with auto-disconnect
zcli vpn up --auto-disconnect --project-id abc123def456

# Connect with custom MTU
zcli vpn up --mtu 1380 -P abc123def456

You can set a default project ID in a .zcli.yml file or via the ZEROPS_PROJECTID environment variable to avoid specifying it each time.

vpn down

Disconnects from the Zerops VPN.

zcli vpn down

Project Management

scope project

Sets the default project scope for subsequent commands.

zcli scope project [project-id]

project-id

string

The ID of the project to set as default

Example:

zcli scope project abc123def456

scope reset

Resets the project scope.

zcli scope reset

project create

Creates a new project in your Zerops organization.

zcli project create [flags]

Flags:

--env-isolation

string

default:"service"

Environment isolation rule: service or none

--mode

string

default:"light"

Project mode: light or serious

--name

string

required

Project name

--org-id

string

Organization ID (required if you belong to multiple organizations)

--out

string

Output format using Go template syntax

--ssh-isolation

string

default:"vpn"

SSH isolation rules

--tags

string[]

Project tags (comma-separated or repeated flag)

Example:

# Create a simple project
zcli project create --name "My Project"

# Create with tags and specific mode
zcli project create --name "Production" --mode serious --tags prod,api

project delete

Deletes a project and all its services.

zcli project delete [project-id] [flags]

project-id

string

The ID of the project to delete

Flags:

--confirm

boolean

Skip confirmation prompts for destructive operations

-P, --project-id

string

Required when you have access to multiple projects

This operation is irreversible. All services and data in the project will be permanently deleted.

Example:

# Delete with confirmation prompt
zcli project delete abc123def456

# Delete without confirmation
zcli project delete --confirm --project-id abc123def456

project env

Displays environment variables for the current project scope.

zcli project env [flags]

Flags:

--export

boolean

Prepends export keyword to each environment variable in output

-P, --project-id

string

Required when you have access to multiple projects

--service

string

Service name to get environment variables in its context

--template

string

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

Output template

--user-only

boolean

Exclude all non-user environment variables

Example:

# List all environment variables
zcli project env

# Export format for shell
zcli project env --export

# User-defined variables only
zcli project env --user-only --service my-app

project list

Lists all projects you have access to.

zcli project list

Example output:

ID              NAME            STATUS
abc123def456    My Project      active
ghi789jkl012    Test Project    active

project project-import

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

zcli project project-import <importYamlPath> [flags]

importYamlPath

string

required

Path to the YAML file containing project definition

Flags:

--org-id

string

Organization ID (required if you belong to multiple organizations)

--working-dir

string

default:"./"

Sets a custom working directory

Example:

zcli project project-import ./project-definition.yml

project service-import

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

zcli project service-import <importYamlPath> [flags]

importYamlPath

string

required

Path to the YAML file containing service definitions

Flags:

-P, --project-id

string

Required when you have access to multiple projects

Example:

zcli project service-import ./services.yml --project-id abc123def456

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

Example:

zcli service list --project-id abc123def456

service create

Creates a new service in a project.

zcli service create [flags]

Flags:

--env

string[]

Environment variables to set (comma-separated or repeated flag)

--env-file

string

File containing environment variables (max 1.0 MiB)

--env-isolation

string

default:"service"

Environment isolation rule: service or none

--mode

string

default:"non_ha"

Service mode: ha (high availability) or non_ha

--name

string

required

Service name

--noop

boolean

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

default:"vpn"

SSH isolation rules

--start-without-code

boolean

Start service immediately without deployment

--working-dir

string

default:"./"

Sets custom working directory

--zerops-yaml-path

string

Sets custom path to zerops.yml file

Example:

# Create a basic service
zcli service create --name my-app --project-id abc123def456

# Create with environment variables
zcli service create --name my-app --env "DB_HOST=localhost,DB_PORT=5432" -P abc123def456

# Create high availability service
zcli service create --name my-api --mode ha --project-id abc123def456

service push

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

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

service-id-or-name

string

The service ID or name to push to

Flags:

--archive-file-path

string

Creates a tar.gz archive with application code at the specified path

-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

Required when you have access to multiple projects

-S, --service-id

string

Required when you have access to multiple services

--setup

string

Choose which setup to use from zerops.yml

-v, --verbose

boolean

Log additional debug data to the debug log file

--version-name

string

Adds a custom version name for this deployment

--working-dir

string

default:"./"

Sets a custom working directory

-w, --workspace-state

string

default:"all"

Defines which files 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

Examples:

# Simple push (uses defaults from config)
zcli push

# Push with service ID
zcli service push --service-id xyz789abc123

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

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

# Verbose push for debugging
zcli push -v

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

To avoid specifying --project-id and --service-id repeatedly, set defaults in a .zcli.yml file or via environment variables. See the Configuration guide.

service deploy

Deploys your application to Zerops (similar to push but deployment-focused).

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

Flags: Same as service push

service start / service stop

Starts or stops a Zerops service.

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

service-id-or-name

string

The service ID or name to start/stop

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

Example:

# Start a service
zcli service start my-app

# Stop a service
zcli service stop --service-id xyz789abc123

service delete

Deletes a Zerops service.

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

service-id-or-name

string

The service ID or name to delete

Flags:

--confirm

boolean

Skip confirmation prompts

-P, --project-id

string

Required when you have access to multiple projects

-S, --service-id

string

Required when you have access to multiple services

This operation is irreversible. All service data will be permanently deleted.

service enable-subdomain

Enables access to your service through a Zerops subdomain.

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

service-id-or-name

string

The service ID or name

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

Streams service runtime or build logs to stdout.

zcli service log [flags]

Flags:

--follow

boolean

Continuously poll for new log messages (like tail -f)

--format

string

default:"FULL"

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

--format-template

string

Custom log format template

--limit

integer

default:"100"

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

--message-type

string

default:"APPLICATION"

Select log type: APPLICATION or WEBSERVER

--minimum-severity

string

Filter by minimum 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

boolean

Show build logs instead of runtime logs

Examples:

# Stream logs in real-time
zcli service log --follow

# Get last 500 application logs
zcli service log --limit 500

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

# JSON format for parsing
zcli service log --format JSON --limit 100

Utility Commands

env

Displays global environment variables and their paths.

zcli env

version

Shows the current zCLI version.

zcli version

Example output:

zcli version 1.10.0

show-debug-logs

Displays debug logs for troubleshooting.

zcli show-debug-logs

This shows the contents of the zCLI debug log file. See the Configuration guide for log file locations.

support

Displays information about how to contact Zerops support.

zcli support

completion

Generates shell autocompletion scripts.

zcli completion {bash|fish|powershell|zsh}

shell

string

required

Shell type: bash, fish, powershell, or zsh

Examples:

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

Global Flags

These flags are available for most commands:

-h, --help

boolean

Display help information for the command

-P, --project-id

string

Specify project ID (can be set via config or environment variable)

-S, --service-id

string

Specify service ID (can be set via config or environment variable)

-v, --verbose

boolean

Enable verbose output with additional debug information

Next Steps

Configuration

Learn how to configure default values and environment variables

CLI Overview

Back to CLI overview and quick start

API

CLI

​Basic Usage

​Command Groups

Account & VPN

Project Management

Service Operations

Utility Commands

​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 / service stop

​service delete

​service enable-subdomain

​service log

​Utility Commands

​env

​version

​show-debug-logs

​support

​completion

​Global Flags

​Next Steps

Configuration

CLI Overview

Build docs developers (and LLMs) love

Basic Usage

Command Groups

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 / service stop

service delete

service enable-subdomain

service log

Utility Commands

env

version

show-debug-logs

support

completion

Global Flags

Next Steps