# Zerops CLI Commands Reference


## Basic Usage

```sh
zcli <command> [flags]
```

:::note Tip
All commands support the `-h, --help` flag which displays help information about the command.
:::

:::tip Configuration
For detailed information about configuration options, environment variables, and logging, see the [Zerops CLI Configuration](/references/zcli/configuration) page.
:::

## Command Groups
- [Account & VPN](#account--vpn)
- [Project Management](#project-management)
- [Service Operations](#service-operations)
- [Utility Commands](#utility-commands)

## Account & VPN

### login

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

```sh
zcli login <token>
```

### logout

Disconnects from VPN and logs out from your Zerops account.

```sh
zcli logout
```

### vpn up

Connects to the Zerops VPN.

```sh
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](/references/zcli/configuration) page for details.
:::

### vpn down

Disconnects from the Zerops VPN.

```sh
zcli vpn down
```

:::note
For more detailed information about Zerops VPN configuration and troubleshooting, visit the [VPN Documentation](/references/networking/vpn).
:::

## Project Management

### scope project

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

```sh
zcli scope project [project-id]
```

### scope reset

Resets the scope for a project.

```sh
zcli scope reset
```

### project create

Creates a new project for a specified organization.

```sh
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.

```sh
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.

```sh
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.

```sh
zcli project list
```

### project project-import

Creates a new project with one or more services from an [Import YAML](/references/import) definition.

```sh
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](/references/import) definition.

```sh
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.

```sh
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.

```sh
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.

```sh
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](/references/zcli/configuration#logging-configuration)
- `--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](/references/zcli/configuration) page for details.
:::

### service deploy

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

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

**Flags:**
Same as [`service push`](#service-push) command.

### service start/stop

Commands to start or stop a Zerops service.

```sh
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.

```sh
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.

```sh
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.

```sh
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.

```sh
zcli env
```

### version

Shows the current zCLI version.

```sh
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.

:::note Availability
The `upgrade` command is available in zCLI `v1.1.0` and later. On earlier versions, install the newer release via [install.sh](#downgrading-below-v110) (or your package manager) first.
:::

```sh
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:**
```sh
# 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:

```sh
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.

```sh
zcli show-debug-logs
```

### support

Displays information about how to contact Zerops support.

```sh
zcli support
```

### completion

Generates shell autocompletion scripts.

```sh
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:**
```sh
zcli completion bash > ~/.zerops-completion.bash
echo 'source ~/.zerops-completion.bash' >> ~/.bashrc
```