Skip to main content
zCLI supports multiple configuration methods to streamline your workflow. You can set default values for commands using configuration files, environment variables, or command-line flags.

​
Configuration Precedence

Configuration options are applied in the following order (later sources override earlier ones):
1

Configuration Files

Global (~/.config/zerops/zcli.yaml) and project-specific (./.zcli.yaml) files
2

Environment Variables

Variables prefixed with ZEROPS_
3

Command-line Flags

Flags passed directly to commands (highest precedence)
This precedence order means command-line flags will always override environment variables, which will override settings in configuration files.

​
Configuration Files

zCLI supports YAML configuration files in two locations:

​
Global Configuration

Stored in your home directory:
  • ~/.config/zerops/zcli.yaml (preferred)
  • ~/zerops/zcli.yaml (alternative)
Use this for organization-wide or user-wide defaults.

​
Project-specific Configuration

Stored in your project root:
  • ./.zcli.yaml
Use this for project-specific settings that should be shared with your team.

​
How Configuration Files Are Merged

  1. zCLI first loads the global config file
  2. Then merges in the project-specific config if it exists
  3. Settings unique to the global config are preserved
  4. Settings in the project-specific config override duplicate keys from global config

​
Configuration File Examples

# Set organization-wide defaults
workspaceState: "all"

# Default logging preferences
verbose: false

​
Supported Configuration Keys

​
projectId
string
Default project ID for commands
​
serviceId
string
Default service ID for commands
​
workspaceState
string
Default workspace state for push/deploy: clean, staged, or all
​
zeropsYamlPath
string
Custom path to zerops.yml file
​
workingDir
string
Default working directory
​
verbose
boolean
Enable verbose logging
​
mtu
integer
MTU value for VPN connections
​
autoDisconnect
boolean
Auto-disconnect from VPN when connecting to a new project

​
Environment Variables

​
Standard Environment Variables

Any command-line flag can be set via environment variables by:
  1. Using the ZEROPS_ prefix
  2. Converting the flag name to UPPERCASE
  3. Using the full flag name (not shorthand)
# Set default project and service
export ZEROPS_PROJECTID=abc123def456
export ZEROPS_SERVICEID=xyz789

# Set workspace state
export ZEROPS_WORKSPACESTATE=clean

# Enable verbose logging
export ZEROPS_VERBOSE=true

# Custom zerops.yml path
export ZEROPS_ZEROPSYAMLPATH=./config/zerops.yml

​
Special Environment Variables

zCLI recognizes special environment variables that control its behavior:

​
ZEROPS_CLI_TERMINAL_MODE

Controls the interactive mode of zCLI: 
export ZEROPS_CLI_TERMINAL_MODE=<mode>
​
mode
string
default:"auto"
Terminal mode:
  • auto - Automatically detect if interactive mode can be used (default)
  • enabled - Force interactive mode
  • disabled - Disable interactive mode (useful in CI/CD)
Use cases:
  • Set to disabled in CI/CD pipelines
  • Set to enabled for rich terminal UI
  • Leave as auto for normal usage
Example: 
# In CI/CD pipeline
export ZEROPS_CLI_TERMINAL_MODE=disabled
zcli push

​
ZEROPS_CLI_LOG_FILE_PATH

Sets a custom location for the debug log file: 
export ZEROPS_CLI_LOG_FILE_PATH=/path/to/custom/zcli.log
zCLI must have write permissions for the specified log file location.

​
Logging Configuration

zCLI maintains debug logs for the service push and service deploy commands to help with troubleshooting.

​
Log File Locations

​
Default Locations

zCLI tries these locations in order:
  1. /var/log/zcli.log (if zCLI has write permissions)
  2. ~/.config/zerops/zerops.log (fallback)

​
Custom Location

Set a custom log location using the environment variable: 
export ZEROPS_CLI_LOG_FILE_PATH=/path/to/my/zcli.log

​
Verbose Logging

Enable additional debug information using the --verbose flag (or -v): 
zcli service push --verbose
zcli push -v
You can also enable verbose logging by default: 
verbose: true

​
Viewing Logs

To troubleshoot deployment issues, check the log files: 
# View the entire log file
cat ~/.config/zerops/zerops.log

# Stream new log entries in real-time
tail -f ~/.config/zerops/zerops.log

# View last 50 lines
tail -n 50 ~/.config/zerops/zerops.log

# Search for errors
grep -i error ~/.config/zerops/zerops.log
Or use the built-in command: 
zcli show-debug-logs

​
Configuration Examples

Here are some common configuration scenarios:

​
Development Team Setup

# Shared team configuration
projectId: "team-project-123"
workspaceState: "all"  # Include all local changes
zeropsYamlPath: "./zerops.yml"

​
CI/CD Pipeline

# In your CI/CD configuration
export ZEROPS_CLI_TERMINAL_MODE=disabled
export ZEROPS_PROJECTID=${CI_PROJECT_ID}
export ZEROPS_SERVICEID=${CI_SERVICE_ID}
export ZEROPS_WORKSPACESTATE=clean

# Login and deploy
zcli login ${ZEROPS_TOKEN}
zcli push

​
Multiple Projects

~/.config/zerops/zcli.yaml
# Global defaults
workspaceState: "staged"
verbose: false
autoDisconnect: true
Then use project-specific .zcli.yaml files in each project directory:
project-a/.zcli.yaml
projectId: "project-a-id"
serviceId: "service-a-id"
project-b/.zcli.yaml
projectId: "project-b-id"
serviceId: "service-b-id"
workspaceState: "clean"  # Override global setting

​
Best Practices

Store .zcli.yaml in your project repository so all team members use the same defaults. Add it to version control.
.zcli.yaml
projectId: "shared-project-id"
serviceId: "main-service-id"
workspaceState: "staged"
Store personal preferences like verbose logging in your global config file.
~/.config/zerops/zcli.yaml
verbose: true
autoDisconnect: true
Environment variables are perfect for CI/CD pipelines where you need to inject configuration dynamically.
export ZEROPS_PROJECTID=${CI_PROJECT_ID}
export ZEROPS_CLI_TERMINAL_MODE=disabled
Never store access tokens in configuration files. Always pass them securely via environment variables or CI/CD secrets.
# Good: Use environment variable
zcli login ${ZEROPS_TOKEN}

# Bad: Don't hardcode tokens
zcli login abc123...  # Never do this!
When debugging deployment issues, enable verbose logging to get detailed information in the log files.
zcli push --verbose

​
Troubleshooting Configuration

​
Check Current Configuration

View environment variables and their values: 
zcli env

​
Configuration Not Working

1

Check file location

Ensure your config file is in the correct location:
  • Global: ~/.config/zerops/zcli.yaml or ~/zerops/zcli.yaml
  • Project: ./.zcli.yaml in project root
2

Check YAML syntax

Make sure your YAML file is valid. Use a YAML validator if needed.
3

Check precedence

Remember: command-line flags > environment variables > config filesA command-line flag will always override config file settings.
4

Check environment variables

Verify environment variables are set:
echo $ZEROPS_PROJECTID  # Linux/macOS
echo $env:ZEROPS_PROJECTID  # Windows PowerShell

​
Next Steps

Commands Reference

Explore all available zCLI commands

CLI Overview

Back to CLI overview and quick start

Build docs developers (and LLMs) love

Get started for freeTalk to us