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

Help Information

-h, --help

Show the help information for the current command.

In v3, --help output is much more complete than before and works better as a command discovery entry point. In practice, you can usually drill down step by step through “top-level command → subcommand → concrete action” to confirm the real command structure before running anything.

From a structural perspective, the new help output typically includes several kinds of key information at the same time:

• Usage
• Options
• Examples
• Related Commands
• Docs

This means --help is no longer just a parameter reference. It is closer to a self-explanatory guide for the command itself. Its value is not only that it contains more information, but that the output order is also instructional: it first tells you how to write the command, then how to choose key parameters, and then supplements that with examples, related commands, and documentation. This reduces the need to switch back and forth between help output, docs, and search results. It is especially useful in the following scenarios:

• Quickly confirming the correct syntax when using a command for the first time
• Looking up examples directly in the terminal instead of jumping back to docs
• Confirming the real parameter signature before writing scripts or CI jobs
• Letting AI read the actual help output before generating commands, reducing hallucinated command forms

Examples:

# Start from the top-level command structure
tcb --help

# Then drill down into a specific subcommand
tcb fn deploy --help

# Finally inspect parameters and examples for a concrete action
tcb logs search --help

For example, output like tcb fn deploy --help puts the command form, key parameters, examples, related commands, and docs in one place. Developers can confirm how to write the command directly, and AI can read the real help output before generating a command, reducing guesswork and trial-and-error.

$ tcb fn deploy --help
Usage: tcb fn deploy [options] [name]

Options:
  --force
  --dir <dir>
  --runtime <runtime>
  --json

Examples:
  tcb fn deploy hello
  tcb fn deploy hello --force
  tcb fn deploy --all

Related Commands:
  tcb fn invoke
  tcb fn log

Docs:
  https://docs.cloudbase.net/cli-v1/functions/deploy

AI Collaboration Tip

If you use an LLM to help generate tcb commands, it is recommended to run the corresponding --help first, or combine it with tcb docs. Compared with relying only on model memory, reading live help output is much more reliable.

---

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

• CLI Installation and Quick Start
• Exit Code
• Multi-region Usage
• Configuration File