CLI and Cloud API Deployment Reference

In CI/CD, scripts, or your own platform, you can trigger deployments without the console. This page lists commands, options, and API parameters. For a first deployment you want to run end to end, see Tutorial: Deploy the Sample Project.

Method	When to use	Code source
CLI	CI/CD pipelines, local scripts	Local or CI working directory
Cloud API	Self-built platforms, server-side calls	Git repository or code archive

CLI deployment reads the resources declared in cloudbaserc.json. For the configuration file, see Configuration file.

Deploy through CLI

In non-interactive environments, log in with a Cloud API key or an environment-level API Key. Store the keys in the Secrets of your CI, not in the repository.

tcb login --apiKeyId <SecretId> --apiKey <SecretKey>

For more login methods, see Login and authentication.

Declarative deployment

Run in the project root:

tcb deploy --dry-run   # Preview changes without deploying
tcb deploy --yes       # Deploy, and overwrite existing Cloud Functions directly

Common options:

Option	Description
`--dry-run`	Prints the change plan without deploying
`--yes`	Overwrites existing Cloud Functions without confirmation
`--only` / `--skip`	Deploys only, or skips, the specified resource types
`--env-id`	Specifies the target environment
`--mode`	Applies the matching environment override in `cloudbaserc.json`
`--continue-on-error`	Continues deploying the other resources after one fails

When any resource fails to deploy, the command exits with a non-zero code, which CI uses to determine the result. For all options, see Declarative deployment (tcb deploy).

Declarative deployment covers Cloud Functions, cloud apps, Static Hosting, gateway routes, and database migrations. It does not include CloudBase Run. Existing resources converge to the declaration in cloudbaserc.json: Cloud Functions are overwritten, and gateway routes with identical configuration are skipped.

For Static Hosting with a build step, run tcb app build before tcb deploy:

npm install --prefix web   # Install dependencies in the hosting[].root directory
tcb app build              # Build locally, without installing dependencies
tcb deploy --yes

If outputDir already exists, tcb deploy uploads its contents as they are. If you change the source and skip tcb app build, the previous artifacts are uploaded again.

Deploy CloudBase Run

Deploy CloudBase Run separately with tcb cloudrun deploy. The service is created if it does not exist. If it exists, it is updated and a new deployment record is generated:

tcb cloudrun deploy -s demo-run --source ./cloudrun/demo-run --port 3000 --force --yes --wait

Option	Description
`-s`	Service name
`--source`	Code directory. For container services, it must contain a `Dockerfile`
`--port`	Listening port of the container service
`--force` / `--yes`	Skips confirmation, for non-interactive environments
`--wait`	Waits for the deployment to finish before returning

For all parameters, see Code deployment.

Deployment records and status:

tcb cloudrun record list -s demo-run -e <envId>

While a new version is building, its status is creating. It receives requests only after the status becomes normal and its traffic ratio is 100. For a short time before the switch completes, requests may still reach the old version.

Cloud build deployment

For frontend projects with install and build steps, use tcb app deploy to run "install dependencies → build → upload artifacts → bind routes" in the cloud:

cd web
tcb app deploy my-app --framework vite --force -e <envId>

The result is an app in the Apps list, with its own access domain and version records. It differs from the static file directory deployed through hosting. See Two deployment forms of Static Hosting.

⚠️ Run the command inside the app directory. If you point to a subdirectory from the project root with app.root or --cwd, the CLI packages the subdirectory but submits the subdirectory path to the cloud build. The build then fails at the dependency installation step with cd: can't cd to /root/cloudbase-workspace/./web.

After the first successful deployment, the CLI writes a cloudbaserc.json into the working directory. When the app directory differs from the project root, avoid leaving two configuration files.

When a build fails, the CLI prints only generic troubleshooting hints. To see the cause:

tcb app versions list my-app -e <envId>   # Get the version name and build ID
tcb api tcb DescribeCloudBaseRunBuildLog --api-version 2018-06-08 \
  --body '{"EnvId":"<envId>","ServiceName":"my-app","ServiceVersion":"my-app-001","BuildId":<BuildId>,"Start":0}'

For API parameters, see Build logs. For command parameters, see App deployment.

Deploy through Cloud API

Call the Cloud API CreateCloudApp with DeployType set to custom. The cloud pulls the code, runs the build commands, and completes the deployment.

Item	Value
API domain	`tcb.tencentcloudapi.com`
Action	`CreateCloudApp`
Version	`2018-06-08`
Rate limit	20 requests per second

For the full API definition, see CreateCloudApp. For common parameters and signing, see Common request parameters. You can debug online and generate SDK code with API Explorer.

Call flow

When the code source is an archive, call DescribeCloudAppCosInfo to get the upload URL and upload the code. See Upload the code package. Skip this step when the code source is a Git repository.
Call CreateCloudApp with the code source and build commands. It returns BuildId and VersionName.
Call DescribeCloudAppVersion to query the build status until it is SUCCESS or FAILED.
Call DescribeCloudBaseRunBuildLog to view the build log. See Query build status and logs.

Request parameters

Parameter	Type	Required	Description
`EnvId`	String	Yes	Environment ID
`ServiceName`	String	Yes	Service name, which corresponds to the pipeline name in the console
`DeployType`	String	Yes	Deployment type: `custom` for a custom pipeline, `static-hosting` for a Static Hosting app
`Source`	Object	Yes	Code source. See Source
`Commands`	Object	No	Build commands. See Commands
`CustomSteps`	Array	No	Custom steps. See CustomSteps
`Env`	Array	No	Non-sensitive environment variables, referenced as `$KEY` in the build container
`Secrets`	Array	No	Sensitive credentials. See Secrets
`NodeJsVersion`	String	No	Node.js version for the build, such as `16`, `18`, `20`, `22`, `24`
`WorkingDir`	String	No	Global working directory, such as `./`. Corresponds to "Target directory" in the console
`PreDeployCommand`	String	No	Command to run before deployment
`PostDeployCommand`	String	No	Command to run after deployment
`Runner`	Object	No	Build container configuration. `Runner.Cpus` sets the CPU count, such as `16`. Corresponds to "Container specification" in the console
`BuildType`	String	No	Build type, such as `ZIP`

Specify at least one of Commands and CustomSteps. For Docker image builds, CustomSteps is recommended.

⚠️ The CLI in the build environment is logged in but does not pick a target environment automatically. Commands such as tcb hosting deploy in the deploy command need -e <envId>. Otherwise, the deploy step fails with No valid environment ID was detected. tcb deploy reads envId from cloudbaserc.json in the project and needs no extra option.

When DeployType is custom, artifacts are deployed to a Static Hosting file directory and do not appear in the console Apps list. See Two deployment forms of Static Hosting.

The Trigger parameter (webhook trigger) is not open yet. Passing it does not cause an error, but it has no effect.

Source

Parameter	Type	Description
`Type`	String	Code source type: `git`, `zip`
`Repo`	String	HTTPS URL of the Git repository, or the full download URL of the archive
`Ref`	String	Git branch, tag, or commit. Defaults to `main`. Ignored for `zip`
`Channel`	String	Git platform: `git`, `github`, `gitlab`, `gitee`, `coding`. Required for private repositories
`IsPrivate`	Boolean	Whether the repository is private. When `true`, the platform injects an authenticated clone URL
`CodeUrlWithAuth`	String	An authenticated clone URL or a signed archive download URL that you provide. Highest priority
`CosTimestamp`	String	For `zip`. Use the `UnixTimestamp` returned by `DescribeCloudAppCosInfo`
`CosSuffix`	String	For `zip`. Archive suffix. Defaults to `.zip`
`PackageFileName`	String	Archive name, such as `package.zip`

⚠️ CodeUrlWithAuth contains an access token. Use a token with minimal permissions and a short validity period, and do not print the request content in logs.

The Repo of the git type must meet the following:

Uses the https protocol
The domain belongs to GitHub, GitLab, Gitee, Bitbucket, or Coding
Does not point to an internal IP
Contains no backticks, $, double quotes, backslashes, or line breaks

Commands

Corresponds to the "Simple commands" mode in the console. See Command mode.

Parameter	Type	Description
`InstallCmd`	String	Install command, such as `npm install`
`BuildCmd`	String	Build command, such as `npm run build`
`DeployCmd`	String	Deploy command, such as `tcb deploy --yes`

CustomSteps

Corresponds to the "Custom steps" mode in the console. Steps run in array order.

Parameter	Type	Description
`Name`	String	Step name. `kebab-case` is recommended, such as `build-image`
`Command`	String	Shell script, single-line or multi-line

When a command contains docker build or docker push, the build environment provides a Docker service.

Env

Parameter	Type	Description
`Key`	String	Variable name. Starts with a letter or underscore, and contains only letters, digits, and underscores
`Value`	String	Variable value

Secrets

Parameter	Type	Description
`Name`	String	Secret name, such as `TCR_PASSWORD`. Referenced as `$SECRET_<NAME>` in the build container
`Value`	String	Secret value

Secrets are stored encrypted, and query APIs do not return the plaintext.

Response parameters

Parameter	Type	Description
`BuildId`	String	Build ID
`VersionName`	String	Version name, such as `my-vue-app-01-001`
`ServiceName`	String	Service name
`RequestId`	String	Request ID, to provide when troubleshooting

Upload the code package

When the code source is an archive, complete it in two steps:

Call DescribeCloudAppCosInfo to get the upload URL.

Parameter Description
EnvId Environment ID
ServiceName Service name
DeployType Same as at creation
Suffix File suffix, such as .zip

It returns UploadUrl, UploadHeaders, and UnixTimestamp.
Upload the archive to UploadUrl with the UploadHeaders request headers. The upload URL is signed and valid for a limited time. Get a new one after it expires.

Parameter	Description
`EnvId`	Environment ID
`ServiceName`	Service name
`DeployType`	Same as at creation
`Suffix`	File suffix, such as `.zip`

When you call CreateCloudApp, set Source.Type to zip and Source.CosTimestamp to the UnixTimestamp returned in step 1.

Query build status and logs

Build status

Call DescribeCloudAppVersion with BuildId or VersionName.

Parameter	Required	Description
`EnvId`	Yes	Environment ID
`ServiceName`	Yes	Service name
`DeployType`	Yes	Deployment type
`BuildId`	No	Build ID
`VersionName`	No	Version name

Status in the response is the build status, and Steps is the execution status of each step. Resources lists the resources involved in this deployment.

Build logs

Call DescribeCloudBaseRunBuildLog.

Parameter	Type	Description
`EnvId`	String	Environment ID
`ServiceName`	String	Service name
`ServiceVersion`	String	Version name
`BuildId`	Integer	Build ID
`Start`	Integer	Log offset, for fetching in segments

For the API definition, see Query build logs.

Examples

Three-step build

{
  "EnvId": "your-env-id",
  "ServiceName": "my-vue-app",
  "DeployType": "custom",
  "Source": {
    "Type": "git",
    "Repo": "https://github.com/my-org/my-vue-app.git",
    "Ref": "main",
    "Channel": "github"
  },
  "Commands": {
    "InstallCmd": "npm install",
    "BuildCmd": "npm run build",
    "DeployCmd": "tcb hosting deploy ./dist / -e your-env-id"
  },
  "NodeJsVersion": "22",
  "Env": [
    { "Key": "NODE_ENV", "Value": "production" }
  ]
}

Private repository

{
  "EnvId": "your-env-id",
  "ServiceName": "private-service",
  "DeployType": "custom",
  "Source": {
    "Type": "git",
    "Repo": "https://github.com/my-org/private-service.git",
    "Ref": "release/v2.0",
    "Channel": "github",
    "IsPrivate": true
  },
  "Commands": {
    "InstallCmd": "pnpm install --frozen-lockfile",
    "BuildCmd": "pnpm run build",
    "DeployCmd": "tcb deploy --yes"
  }
}

Custom steps: build and push an image

{
  "EnvId": "your-env-id",
  "ServiceName": "go-api-service",
  "DeployType": "custom",
  "Source": {
    "Type": "git",
    "Repo": "https://gitlab.com/my-org/go-api.git",
    "Ref": "master",
    "Channel": "gitlab"
  },
  "CustomSteps": [
    { "Name": "build-binary", "Command": "go build -o bin/api ./cmd/api" },
    { "Name": "build-image", "Command": "docker build -t my-registry.com/go-api:latest ." },
    { "Name": "push-image", "Command": "docker login -u $REGISTRY_USER -p $SECRET_REGISTRY_PASSWORD my-registry.com && docker push my-registry.com/go-api:latest" }
  ],
  "Env": [
    { "Key": "CGO_ENABLED", "Value": "0" },
    { "Key": "REGISTRY_USER", "Value": "myuser" }
  ],
  "Secrets": [
    { "Name": "REGISTRY_PASSWORD", "Value": "<registry-password>" }
  ]
}

Pre- and post-deploy commands

{
  "EnvId": "your-env-id",
  "ServiceName": "my-vue-app",
  "DeployType": "custom",
  "Source": {
    "Type": "git",
    "Repo": "https://github.com/my-org/my-vue-app.git",
    "Ref": "main",
    "Channel": "github"
  },
  "CustomSteps": [
    { "Name": "check-node", "Command": "node -v" }
  ],
  "NodeJsVersion": "22",
  "PreDeployCommand": "echo pre-deploy",
  "PostDeployCommand": "echo post-deploy"
}

Error codes

Error code	Description
`InvalidParameter`	Invalid parameter format or type, such as a missing or invalid `EnvId`
`LimitExceeded.ErrNamespaceMaxLimit`	Namespace quota exceeded
`LimitExceeded.ErrRepoMaxLimit`	Image repository quota exceeded
`ResourceNotFound`	Resource does not exist
`FailedOperation`	Operation failed
`InternalError`	Internal error

For other common error codes, see Common error codes.

Deploy through CLI​

Log in​

Declarative deployment​

Deploy CloudBase Run​

Cloud build deployment​

Deploy through Cloud API​

Call flow​

Request parameters​

Source​

Commands​

CustomSteps​

Env​

Secrets​

Response parameters​

Upload the code package​

Query build status and logs​

Build status​

Build logs​

Examples​

Three-step build​

Private repository​

Custom steps: build and push an image​

Pre- and post-deploy commands​

Error codes​