Upgrading from v1/v2 to v3

CloudBase CLI v3.0 expands capabilities and reorganizes the command system on top of v1/v2, while remaining compatible with the main command formats used in v1/v2. After upgrading, the main things to pay attention to are the new global usage patterns, how capabilities have been consolidated, and the migration path for deprecated commands.

Upgrade Procedure

npm install -g @cloudbase/cli

Check the current version:

tcb --version

---

v3.0 Important Changes

1. Improved global usage experience

The first major change in v3.0 is the unification of core CLI behavior. This affects how you use almost every command.

• The global environment parameter is standardized as --env-id. The old --envId is still supported for compatibility, but is no longer recommended.
• tcb env use is introduced to set a global default environment. Environment resolution priority becomes: tcb env use < project cloudbaserc.json < command-line --env-id.
• More commands now support --json, making output easier to consume in scripts, CI/CD, and AI tools.
• More commands now support --yes, allowing non-interactive execution for automation scenarios.
• The new --help has much stronger self-explanatory value. It supports drilling down from top-level commands to specific subcommands, and organizes the output as usage, options, examples, related commands, and docs.
• v3.0 introduces structured exit codes, making it possible to distinguish authentication failures, invalid arguments, missing resources, cloud API errors, and local file errors in pipelines and scripts.

The new --help is worth noting. It is no longer just a parameter reference, but part of the command discovery flow: use top-level help to find the right command, then use subcommand help to confirm the real signature. Output such as tcb fn deploy --help puts the command form, key parameters, examples, related commands, and docs in one place, making it better for both manual lookup and AI-assisted command generation.

$ 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

2. New general-purpose capabilities

v3.0 adds several cross-cutting capabilities that reduce the need to switch to the console or build one-off helper scripts.

Command	Purpose
tcb docs	Search and read official documentation directly in the terminal, without login
tcb api	Call Tencent Cloud APIs directly without handling authentication and request signing yourself
tcb secrets	Get temporary credentials from the current Web login session for local SDK debugging

These are mostly workflow and tooling improvements, especially useful for troubleshooting, automation, and AI-assisted usage.

3. Enhancements and consolidation of existing commands

v3.0 is not only about new commands. It also strengthens existing workflows and consolidates scattered capabilities.

Cloud Storage enhancements

• tcb storage rm is added to replace tcb storage delete, with support for recursive deletion, --force, and --dry-run.
• tcb storage cp is added to support server-side copy and move operations.
• tcb storage search is added to search files by pattern, directory, extension, or regular expression.

Unified logging

• tcb logs search is introduced as the unified log entry point for Cloud Functions, Cloud Run, databases, LLM-related logs, and more.
• Logging workflows that were previously scattered across resource-specific commands are now being consolidated. For example, the Cloud Functions log documentation now directs users to tcb logs.

Unified permissions

• Resource permissions are consolidated under tcb permission, covering database collections, storage buckets, SQL tables, and Cloud Functions.
• Legacy storage ACL and rules commands are deprecated in v3.0 and should be migrated to the unified permission model.

4. New resource-specific capabilities

Beyond the general-purpose additions, v3.0 also introduces a new set of modules for specific resources and business scenarios:

Command	Description
tcb cors	Security domain management (Web SDK allowlist)
tcb domains	Custom domain management
tcb routes	HTTP service route management
tcb app	CloudBase application deployment management
tcb agent	AI Agent management
tcb user	End-user management
tcb role	Role management
tcb db	MySQL / NoSQL database management

Among these, the most important additions are:

• Environment management is expanded from simple listing and renaming to full lifecycle operations with tcb env use/create/modify/renew/delete/usage/info.
• The old tcb service command is split into three clearer modules: tcb cors, tcb domains, and tcb routes.
• tcb cloudrun traffic is added for canary traffic allocation, promotion, and rollback in Cloud Run.
• tcb db is no longer limited to the old data model commands. It now also covers MySQL execution, instance management, backup and restore, slow query inspection, plus native NoSQL operations and restore workflows.

5. Removed capabilities

The following capabilities have been removed in v3.0 and are no longer supported:

Removed command	Replacement
tcb fun list/deploy/run	Migrate to tcb cloudrun list/deploy/run
tcb run standalonegateway ...	No CLI replacement. Use the console for related operations

6. Deprecated commands

The following commands are still retained for compatibility in v3.0, but are officially deprecated and should be migrated as soon as possible:

Deprecated item	Recommended replacement
tcb functions:*	tcb fn ...
tcb storage:*	tcb storage ...
tcb hosting:*	tcb hosting ...
tcb service ...	tcb cors / tcb domains / tcb routes
tcb db list/pull/push	tcb db model list/pull/push
tcb run list/delete	tcb cloudrun list/delete
tcb storage get-acl/set-acl/rules ...	tcb permission