zcli yaml

apps/docs/content/features/pipeline.mdx

@@ -111,7 +111,7 @@ Trigger the build & deploy pipeline automatically with each push to the selected
 
 To start a new build & deploy pipeline manually, use the [Zerops CLI](/references/cli). zCLI is the Zerops command-line tool.
 
-The [zcli push](/references/cli/commands#push) command uploads your application code, builds and deploys your application in Zerops.
+The [zcli service push](/references/cli/commands#service-push) command uploads your application code, builds and deploys your application in Zerops.
 
 The command triggers the build pipeline defined in `zerops.yaml`. `zerops.yaml` must be in the working directory. The working directory is by default the current directory and can be changed using the `--workingDir` flag.
 

apps/docs/content/references/cli.mdx

@@ -6,7 +6,9 @@ description: Learn how to install and use zCLI, the powerful command-line tool f
 import CustomCard from '/src/components/CustomCard';
 import Image from '/src/components/Image';
 
-zCLI is the command-line tool for Zerops that allows users to manage services, simplify interactions, configure infrastructure directly from the terminal.
+zCLI is the command-line tool for Zerops that allows users to manage services, simplify interactions, and configure infrastructure directly from the terminal.
+
+For detailed information, see the [Configuration](/references/cli/configuration) and [Commands Reference](/references/cli/commands) pages.
 
 ## Platforms
 
@@ -101,8 +103,4 @@ You may use an access token to access Zerops using this command:
 
 ```sh
 zcli login <token>
-```
-
-## References
-
-[zCLI Commands and Usage](/references/cli/commands)
+```

apps/docs/content/references/cli/commands.mdx

@@ -1,18 +1,22 @@
 ---
-title: Available Commands
-description: Available commands in the Zerops command line tool (zcli)
+title: Zerops CLI Commands Reference
+description: A comprehensive reference for all available commands in the Zerops command line tool (zcli)
 ---
 
 ## Basic Usage
 
 ```sh
-zcli [command] [flags]
+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/cli/configuration) page.
+:::
+
 ## Command Groups
 - [Account & VPN](#account--vpn)
 - [Project Management](#project-management)
@@ -50,6 +54,10 @@ zcli vpn up [projectId] [flags]
 - `--mtu int` - Set custom MTU value for Wireguard interface (default: 1420)
 - `--projectId 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/cli/configuration) page for details.
+:::
+
 ### vpn down
 
 Disconnects from the Zerops VPN.
@@ -115,6 +123,10 @@ Sets the default project for commands that require a project ID.
 zcli scope project [projectId]
 ```
 
+:::tip
+Instead of using the `scope project` command, you can also set a default project ID in a `.zcli.yml` file or via the `ZEROPS_PROJECTID` environment variable. See the [Configuration](/references/cli/configuration) page for details.
+:::
+
 ### scope reset
 
 Resets the default project and service scope.
@@ -148,6 +160,7 @@ zcli service push [serviceIdOrName] [flags]
 - `--archiveFilePath string` - Creates a tar.gz archive with application code
 - `-g, --deployGitFolder` - Include the .git folder in the upload
 - `--disableLogs` - Disable logs during push
+- `-v, --verbose` - Log additional debug data to the zCLI [debug log file](/references/cli/configuration#logging-configuration)
 - `--projectId string` - Required when you have access to multiple projects
 - `--serviceId string` - Required when you have access to multiple services
 - `--setup string` - Choose setup to use from zerops.yml
@@ -161,6 +174,8 @@ zcli service push [serviceIdOrName] [flags]
 
 :::tip
 You can also use `zcli push` as a shorthand for `zcli service push`.
+
+To avoid specifying `--projectId` and `--serviceId` flags repeatedly, you can set default values in a `.zcli.yml` file or via environment variables. See the [Configuration](/references/cli/configuration) page for details.
 :::
 
 ### service deploy

apps/docs/content/references/cli/configuration.mdx

@@ -0,0 +1,113 @@
+---
+title: Zerops CLI Configuration
+description: Configuration options, environment variables, and logging capabilities for the Zerops command line tool (zcli)
+---
+
+:::tip Commands Reference
+For a comprehensive reference of all available commands, see the [Commands Reference](/references/cli/commands) page.
+:::
+
+## Configuration Overview
+
+You can configure default values for zCLI commands using the following methods (in order of increasing precedence):
+
+1. [Configuration files](#configuration-files)
+2. [Environment variables](#environment-variables)
+3. [Command-line flags](/references/cli/commands)
+
+:::note Precedence
+This precedence order means that command-line flags will override environment variables, which will override settings in configuration files.
+:::
+
+## Configuration Files
+
+zCLI supports configuration via YAML files in the following locations:
+
+1. Global config (user home): `~/.config/zerops/zcli.yaml` or `~/zerops/zcli.yaml`
+2. Project-specific config: `./.zcli.yaml` in the root of your application repository
+
+The system first loads the global config file, then merges in the project-specific config if it exists:
+- Settings unique to the global config are preserved
+- Settings in the project-specific config will override any duplicate keys from the global config
+
+### Configuration File Examples
+
+**Global config file (placed in user home directory):**
+```yaml
+# Set organization-wide defaults
+workspaceState: "all"
+```
+
+**Project-specific `.zcli.yml` file (placed in the root of your application repository):**
+```yaml
+# Set project-specific settings
+projectId: "your-project-id"
+serviceId: "your-service-id"
+
+# Override global workspace state for this project
+workspaceState: "clean"
+```
+
+## Environment Variables
+
+### Standard Environment Variables
+
+Any flag can be set via environment variables by:
+- Using the `ZEROPS_` prefix
+- Converting the flag name to uppercase
+- Using the full flag name (not shorthand)
+
+**Example:**
+```sh
+export ZEROPS_WORKSPACESTATE=clean
+export ZEROPS_PROJECTID=your-project-id
+```
+
+### Special Environment Variables
+
+zCLI also recognizes special environment variables that control its behavior:
+
+#### Terminal Mode Configuration
+
+The `ZEROPS_CLI_TERMINAL_MODE` environment variable controls the interactive mode of zCLI:
+
+```sh
+export ZEROPS_CLI_TERMINAL_MODE=<mode>
+```
+
+Available modes:
+- `auto` (default): Automatically detects if interactive mode can be used and enables it when possible
+- `enabled`: Forces interactive mode to be enabled
+- `disabled`: Forces interactive mode to be disabled
+
+This setting affects interactive prompts, progress indicators, and other terminal-based user interface elements.
+
+#### Logging Configuration
+
+zCLI maintains a debug log file for the `service push` and `service deploy` commands. This logging feature is designed specifically for debugging purposes. The log file can be found in one of these locations:
+
+**1. Default locations** (checked in this order):
+  - `/var/log/zcli.log` (if zCLI has write permissions)
+  - `~/.config/zerops/zerops.log` (as fallback)
+
+**2. Custom location** (if specified):
+  - Set with `ZEROPS_CLI_LOG_FILE_PATH` environment variable
+
+:::note
+zCLI must have write permissions for the specified log file locations.
+:::
+
+To enable verbose logging with additional debug information, use the `--verbose` flag (or its shorthand `-v`):
+```sh
+zcli service push --verbose
+zcli service push -v
+```
+
+To troubleshoot deployment issues, you can check these log files using commands like `cat` or `tail`:
+```sh
+# View the entire log file
+cat ~/.config/zerops/zerops.log
+
+# Stream new log entries
+tail -f ~/.config/zerops/zerops.log
+```

apps/docs/sidebars.js

@@ -521,16 +521,16 @@ module.exports = {
       items: [
         {
           type: 'doc',
-          id: 'references/cli/commands',
-          label: 'Available Commands',
+          id: 'references/cli/configuration',
+          label: 'Configuration',
           customProps: {
             exclude_from_doc_list: false,
           },
         },
         {
           type: 'doc',
-          id: 'references/cli/access-logs',
-          label: 'Access Logs',
+          id: 'references/cli/commands',
+          label: 'Commands',
           customProps: {
             exclude_from_doc_list: false,
           },