Skip to main content

Global Options

Global options apply to all CloudBase CLI commands, are registered in bin/tcb.js via program.option(), and do not need to be repeatedly declared in each command.

List of Options​

Environment ID​

-e, --env-id <envId>

Specify the TCB environment ID.

Priority (from highest to lowest):

  1. Command-line parameter --env-id
  2. The envId field in the cloudbaserc.json configuration file
  3. Interactive selection (if applicable)

Example:

# Deploying Functions to Specified Environments
tcb fn deploy app --env-id my-env-123

# Querying Database Collections in an Environment
tcb db list --env-id my-env-123
Compatibility Notes

The legacy parameter --envId is deprecated but still usable (hidden in help). It is recommended to use --env-id.

Region​

-r, --region <region>

Specify the region where the environment is located. Supported regions: ap-shanghai, ap-beijing, ap-guangzhou, ap-singapore.

Example:

# Querying Environment List in Guangzhou
tcb env list --region ap-guangzhou

# Deploying Functions to Beijing Region Environment
tcb fn deploy app --region ap-beijing --env-id bj-env-123

Multi-region Error Message:
When the environment is not in the default region (Shanghai), the CLI will prompt to switch the region and automatically retry.

JSON Output​

--json

Output the result in JSON format to facilitate parsing by scripts and AI.

Behavior:

  • Suppress all non-JSON content (version prompts, progress bars, colored output, etc.)
  • Ensure stdout only contains parsable JSON
  • Error messages are also output in JSON format: { "error": { "code": "...", "message": "...", "exit_code": N } }

Example:

# Obtain Function List (JSON Format)
tcb fn list --json

# Query Environment Information and Parse with jq
tcb env list --json | jq '.data[0].EnvId'

Non-interactive Mode​

-y, --yes

Skip all confirmation prompts and automatically select the default option (usually "yes") for all queries.

Applicable Scenarios:

  • CI/CD Pipeline
  • Automated Script
  • Batch Operations

Example:

# Force Delete Function, Skip Confirmation
tcb fn delete app --yes

# Batch Deployment Without Confirmation
tcb fn deploy --yes

Detailed Output​

--verbose

Print internal runtime information, including:

  • Detailed error stack
  • API Request Parameters
  • Intermediate steps logs

Purpose:

  • Debugging CLI behavior
  • Troubleshooting unexpected errors
  • Submit Bug reports

Example:

# Debug the causes of function deployment failure
tcb fn deploy app --verbose

Config File Path​

--config-file <path>

Specify the configuration file path, which defaults to cloudbaserc.json in the current directory.

Example:

# Using Custom Configuration File
tcb fn deploy --config-file ./configs/prod.json

# Use Configuration from Parent Directory
tcb hosting deploy --config-file ../cloudbaserc.json

Environment Mode​

--mode <mode>

Specify the environment mode for loading the .env file (such as development, production).

Purpose:

  • Load different configurations based on the environment
  • Integrate with frontend build tools (Vite, Next.js, etc.)

Example:

# Development Mode Deployment
tcb app deploy --mode development

# Production Mode Deployment
tcb app deploy --mode production

Combined Usage​

Global Options can be freely combined:

# Non-interactive + JSON Output (Suitable for CI/CD)
tcb fn list --yes --json --env-id my-env

# Detailed Logs + Specified Region (Troubleshooting)
tcb fn deploy app --verbose --region ap-guangzhou --env-id gz-env-123

# Custom Configuration + Environment Mode (Local Development)
tcb app deploy --config-file ./dev-config.json --mode development

CI/CD Best Practices​

1. Use --json + --yes to ensure idempotence​

# GitHub Actions Sample
- name: Deploy function
  run: |
    tcb fn deploy app --env-id ${{ secrets.ENV_ID }} --json --yes

2. Parse JSON Output to Extract Information​

# Extract the first function name from the function list
FUNC_NAME=$(tcb fn list --json | jq -r '.data[0].FunctionName')
echo "Latest function: $FUNC_NAME"

3. Error Handling​

# Capture error codes
tcb fn deploy app --json || EXIT_CODE=$?
if [ $EXIT_CODE -ne 0 ]; then
  echo "Deployment failed with exit code $EXIT_CODE"
  exit $EXIT_CODE
fi

Frequently Asked Questions​

Q: What is the difference between --env-id and --envId?​

A: The feature is identical. --envId is a legacy parameter that is deprecated but still usable. It is recommended to use --env-id (conforms to the kebab-case naming convention).

Q: How to avoid interactive prompts in CI/CD pipelines​

A: Use the --yes parameter to skip all confirmation prompts:

tcb fn delete old-func --yes

Q: What is the error format for --json output?​

A: Error messages are output in JSON format:

{
  "error": {
    "code": "FUNCTION_NOT_FOUND",
    "message": "Function app does not exist",
    "exit_code": 4
  }
}

Q: How to specify multiple global options​

A: The order of global options does not matter; they can be combined in any order:

tcb fn deploy app --json --yes --verbose --env-id my-env --region ap-guangzhou

References​