tcb fn deploy

Deploy a cloud function to a CloudBase environment. The function is created on first deployment.

Usage

tcb fn deploy [options] [name]

Flags

Flag	Required	Description	Default
[name]	No	Function name; every function in the configuration file when omitted	—
-e, --env-id <envId>	No	Environment ID	Current default environment
--dir <dir>	No	Function directory path	—
--cwd <dir>	No	Function code directory, for deploying from another directory	Current directory
--all	No	Deploy every function in the configuration file	—
--deployMode <deployMode>	No	Upload mode: cos, zip (1.5 MB limit), image	cos
--install-dependency <boolean>	No	Install dependencies in the cloud, overriding the configuration file	Configuration file value
--httpFn	No	Deploy as an HTTP function	—
--ws	No	Enable WebSocket for an HTTP function	—
--path <path>	No	Create an HTTP gateway access path automatically	—
--code-secret <codeSecret>	No	Encrypt code; 36 letters and digits	—
--force	No	Overwrite an existing function with the same name, including configuration and triggers	—
--yes	No	Skip interactive confirmation	—
--metadata-file <path>	No	Write deployment resource metadata to a JSON file	—

Deployment types

Type	Use case	Entry point
Code package	Regular and HTTP functions with simple dependencies	Default, see Examples
HTTP function	Web services that need scf_bootstrap	--httpFn or type: HTTP, see HTTP function deployment
Image	Custom runtimes, languages other than Node.js and Python, system libraries	--deployMode image, see Image deployment

Examples

With the configuration file

Run in the project directory that contains cloudbaserc.json:

# Deploy a specific function
tcb fn deploy <functionName>

# Deploy every function in the configuration file
tcb fn deploy --all

# Disable cloud dependency installation and upload local node_modules
tcb fn deploy <functionName> --install-dependency false

# Overwrite and skip confirmation, suitable for CI/CD
tcb fn deploy <functionName> --force --yes

# Encrypt code
tcb fn deploy app --code-secret 7sGLwMnhgEfKmkqg2dMjB6xWk2hCxsAgGR6w

After encryption is enabled, function code and information cannot be viewed in the Mini Program IDE or the Tencent Cloud console.

From the current directory

When the function directory contains package.json, the CLI reads the function name from it and deploys with default configuration, without a configuration file.

cd my-function
tcb fn deploy

# Or keep the current directory and point --cwd at the function
tcb fn deploy --cwd ./my-function

Specify the code directory

Override the configuration file path for one invocation:

tcb fn deploy hello --dir ./my-custom-path/hello

For the full precedence rules, see Path resolution.

Path resolution

The CLI resolves the code path in the following order and stops at the first match:

1. --dir (command line)
2. functions[].dir (configuration file)
3. functionRoot + function name (functionRoot defaults to ./functions)
4. Project directory (fallback without a configuration file)

--dir is resolved relative to the current directory. functions[].dir and functionRoot are resolved relative to the project directory. See Global options.

Scenario	Final path
Configuration file, no directory set	functionRoot/function name
functions[].dir set	functions.dir
--dir passed on the command line	--dir
No configuration file	Project directory

For batch deployment (--all or no function name), --dir is ignored.

Batch deployment

With --all or without a function name, the CLI deploys functions with a fixed concurrency of 5:

• Up to 5 functions deploy at the same time, covering code updates, configuration updates, and trigger creation.
• A failed function does not stop the others. The CLI finishes all functions, reports failures, and exits with a non-zero code.
• After each function finishes, the CLI polls cloud status every second until it is ready.

Cloud function APIs have per-account rate limits. Deploying many functions, or running several pipelines against one account, may trigger RequestLimitExceeded. Rate-limited failures are not retried and require a new deployment.

Differences from declarative deployment:

Behavior	tcb fn deploy --all	tcb deploy
Concurrency	Fixed at 5	1 by default, --concurrency up to 20
Failure handling	Continue, then report failures	Stop immediately; --continue-on-error continues
Use case	Bulk function deployment	Multi-resource orchestration

For controllable concurrency, use tcb deploy --concurrency.

Metadata file

--metadata-file <path> writes the resources changed by this deployment to a JSON file for deployment records, rollback, and visualization.

tcb fn deploy --all --metadata-file ./deploy-metadata.json

The file is written after results are collected and before --json output, so both modes produce it. A write failure does not change the deployment result; it reports an error and returns a non-zero code.

{
  "version": 1,
  "envId": "your-env-id",
  "command": "fn deploy",
  "deployTime": "2026-09-29T02:53:12.726Z",
  "resources": [
    {
      "name": "hello",
      "resourceType": "EVENT",
      "action": "create",
      "deployedRef": "$LATEST",
      "deployedAt": "2026-09-29T02:53:12.726Z",
      "deployedBy": "fn deploy"
    }
  ]
}

Field	Description
resourceType	EVENT, HTTP, or STATIC; cloud function types come from the cloud
action	create, update; image deployments may also return replace, noop; publish-version writes publish
deployedRef	Version reference: $LATEST for packages, image digest for images, null when unavailable
deployedAt / deployedBy	Last deployment time and producing command

Merge rules:

• Entries merge by field using resourceType + name as the key, never replaced wholesale, so one file can be written by several commands.
• publish does not overwrite an existing create or update.
• An existing deployedRef is never overwritten by an empty value.
• A corrupted file raises METADATA_FILE_INVALID instead of being rebuilt as empty.

HTTP function deployment

HTTP functions target web services and follow the standard HTTP request and response model. They need an scf_bootstrap script that starts the web server on port 9000; the CLI offers to generate one when missing.

Command forms

Method	Command	Description
Configuration file	tcb fn deploy webFunction	Set type: HTTP in cloudbaserc.json
Command-line flag	tcb fn deploy <name> --httpFn	Generate configuration from package.json in the current directory
Current directory	cd my-web-function && tcb fn deploy --httpFn	Read the function name from name in package.json

With the configuration file:

{
  "envId": "your-env-id",
  "functions": [
    {
      "name": "webFunction",
      "type": "HTTP",
      "runtime": "Nodejs16.13",
      "handler": "index.main",
      "installDependency": true
    }
  ]
}

Access configuration

tcb fn deploy reads functions[].public and functions[].gatewayPath and configures access after deployment.

{
  "functions": [
    {
      "name": "apiDemo",
      "type": "HTTP",
      "handler": "index.main",
      "public": true,
      "gatewayPath": "/api"
    }
  ]
}

Field	Behavior
public: true	Allow anonymous access through OPA Rego, callable by URL without login
gatewayPath	Converge the API gateway route; idempotent, repeated deployments do not duplicate routes

Both fields apply only to HTTP functions. When neither is set, no extra action is taken.

For the bootstrap script, see scf_bootstrap. For project layout, see HTTP function development guide.

Image deployment

Deploy functions from container images, for custom runtimes, non-standard languages, or complex system dependencies.

Prerequisites

1. Grant image pull permissions, once per registry type:
   • Personal: grant QcloudAccessForSCFRoleInPullImage to the function role. Grant access.
   • Enterprise: grant QcloudAccessForSCFRoleInPullImage to the function role (grant access) and QcloudAccessForTCBRoleInTCR to the CloudBase role (grant access).
2. Prepare a registry: create a repository in Container Registry TCR. See Obtain access credentials and Push images.
3. Image requirements: a Linux amd64 image listening on port 9000.
4. Create a log role: create a role in the CAM role console, select scf and cls as service principals, attach a custom policy, and record the role name.

The registry must be in the same region as the function. Only same-region private images can be pulled.

For a single tenant, the preset QcloudCLSFullAccess policy works. When several tenants share one account, use a custom policy to prevent cross-environment log access. See Log role permissions and multi-tenant isolation.

Build strategies

HTTP function image deployment supports three buildStrategy values and also requires type: HTTP.

Strategy	Description	Key configuration
cloud	The cloud pipeline builds and pushes the image; no local Docker needed	buildStrategy: "cloud"
local	The CLI runs docker build and docker push; Docker required	buildStrategy: "local" + imageConfig.build.dockerfile
image	Build and push manually, then set imageUri	buildStrategy: "image" + imageConfig.imageUri

The deploy command is the same for all three:

tcb fn deploy webFunction --deployMode image

Configuration examples

Personal

cloudbaserc.json

{
  "$schema": "https://static.cloudbase.net/cli/cloudbaserc.schema.json",
  "envId": "{{env.ENV_ID}}",
  "functionRoot": "functions",
  "functions": [
    {
      "name": "hello-cloud",
      "type": "HTTP",
      "protocolType": "HTTP",
      "runtime": "CustomImage",
      "buildStrategy": "cloud",
      "timeout": 15,
      "memorySize": 256,
      "imageConfig": {
        "imageType": "personal",
        "imagePort": 9000,
        "build": {
          "dockerfile": "Dockerfile",
          "namespace": "{{env.TCB_TCR_NAMESPACE}}",
          "registryCredential": {
            "username": "{{env.TCB_TCR_USERNAME}}",
            "password": "{{env.TCB_TCR_PASSWORD}}"
          }
        }
      }
    }
  ]
}

Enterprise

cloudbaserc.json

{
  "$schema": "https://static.cloudbase.net/cli/cloudbaserc.schema.json",
  "envId": "{{env.ENV_ID}}",
  "functionRoot": "functions",
  "functions": [
    {
      "name": "hello-world",
      "type": "HTTP",
      "runtime": "CustomImage",
      "buildStrategy": "cloud",
      "timeout": 15,
      "memorySize": 256,
      "imageConfig": {
        "imageType": "enterprise",
        "registryId": "{{env.REGISTRY_ID}}",
        "imagePort": 9000,
        "containerImageAccelerate": true,
        "build": {
          "dockerfile": "Dockerfile",
          "repository": "{{env.REPOSITORY}}"
        }
      }
    }
  ]
}

For all fields, see Image configuration.

Manual build and push

Only buildStrategy: "image" requires manual steps. The cloud and local strategies are handled by the cloud or the CLI.

Build the image with the required platform:

cd /path/to/your-function
docker build --platform linux/amd64 -t your-function:v1 .

On ARM machines such as M1 or M2 Macs, --platform linux/amd64 is required, otherwise the image cannot run in the cloud function environment.

Push the image:

# Tag the image
docker tag [imageId] <registry-domain>/your-namespace/your-function:[tag]

# Push the image
docker push <registry-domain>/your-namespace/your-function:[tag]

Configure imageConfig and deploy:

{
  "envId": "your-env-id",
  "functions": [
    {
      "name": "your-function",
      "imageConfig": {
        "imageType": "personal",
        "imageUri": "<registry-domain>/your-namespace/your-function:v1"
      },
      "role": "SCF_CLSFullAccess",
      "clsLogsetId": "your-logset-id",
      "clsTopicId": "your-topic-id"
    }
  ]
}

tcb fn deploy <functionName> --deployMode image

Image-deployed functions need manual log delivery configuration. Create a logset and log topic in the CLS console, fill in clsLogsetId and clsTopicId, and set role to the log role from the prerequisites.

Notes

• The deployed function type (event or HTTP) cannot be changed. Delete the function and redeploy to change it.
• CLI 2.12.0 and later can merge or replace environment variables during deployment.
• Before CLI 2.12.0, environment variables in the configuration file fully replace those in the cloud. Projects with variables configured in the console must mirror them in the configuration file, otherwise they are lost on deployment.

Related

• Function code: use tcb fn code update to update code only
• Version management: publish immutable versions
• Declarative deployment: orchestrate multiple resources
• Function configuration: configuration file fields
• Access Token