Create Integration

Use the tcb integration create [keyId] command to create integration instances through configuration files. When a keyId positional argument is provided, only the matching integration is created; otherwise all integrations in the configuration file are created in batch.

Quick Start

1. Initialize Integration Configuration

Different integrations have different environment variable requirements. It is recommended to use the tcb config init integration command to generate a configuration template:

# Interactive initialization (will automatically fetch available integration types for selection)
tcb config init integration <keyId>

# Directly specify integration type
tcb config init integration <keyId> --type weixinpaydc

After execution, the CLI will:

1. Select environment (if not specified via -e)
2. Select integration type (fetch available integration type templates from CMS)
3. Enter integration name (optional, defaults to keyId)
4. Fetch template field definitions, generate envVariables configuration template (including field descriptions and required markers)
5. Generate cloudbaserc.json configuration file

Example output:

? Select integration type WeChat Pay (weixinpaydc)
? Enter integration name my-pay

Configuration saved to /path/to/cloudbaserc.json

📝 Next steps:
  1. Edit the cloudbaserc.json file to complete integration configuration parameters
  2. Run tcb integration create to create integration instances

📋 Field descriptions:
  - mch_id (required) - Merchant ID
  - api_key (required) - Sensitive field

2. Complete Configuration

Edit the generated cloudbaserc.json file and replace placeholders with actual values:

{
  "envId": "env-abc123",
  "integrations": [
    {
      "name": "my-pay",
      "authTypeCode": "weixinpaydc",
      "description": "WeChat Pay integration",
      "envVariables": {
        "mch_id": "your-mch-id",
        "api_key": "your-api-key"
      }
    }
  ]
}

3. Create Integration

tcb integration create

Configuration File Mode

tcb integration create reads the integrations field from the cloudbaserc.json configuration file to create integration instances. You need to configure the integrations field in the configuration file first, then execute the command to create.

Configuration File Format

Add the integrations field in cloudbaserc.json:

{
  "integrations": [
    {
      "name": "my-integration",
      "authTypeCode": "custom",
      "description": "My integration",
      "envVariables": {
        "AppId": "your-app-id",
        "AppSecret": "your-app-secret"
      },
      "demoCodeFunctionName": "my-function"
    }
  ]
}

Configuration Fields

Field	Type	Required	Description
name	string	Yes	Integration instance name (duplicates allowed, Key ID is the unique identifier)
authTypeCode	string	Yes	Auth type code, such as custom, wechat, etc.
description	string	No	Integration instance description
envVariables	object	No	Environment variable configuration (key-value pairs)
demoCodeFunctionName	string	No	Cloud function name to bind

Tip: Optional values for authTypeCode can be queried using the tcb integration types command.

Read Field Values from a File (@ File Reference Syntax)

Some fields (such as WeChat Pay's privateKey, apiV3Key, etc.) are usually multi-line text or long sensitive content (e.g., PEM-format private keys). Writing them directly into JSON requires manually escaping line breaks as \n, which is tedious and error-prone.

The CLI supports using the @ prefix in envVariables values to reference a file directly. The file content is automatically read as the field value when creating:

{
  "integrations": [
    {
      "keyId": "key-abc123",
      "name": "key-abc123",
      "authTypeCode": "weixinpaydc",
      "description": "WeChat Pay integration",
      "envVariables": {
        "appId": "wx1234567890",
        "apiV3Key": "@./secrets/apiv3key.txt",
        "privateKey": "@./secrets/apiclient_key.pem"
      }
    }
  ]
}

File reference syntax:

Syntax	Meaning
@./certs/key.pem	Relative path (relative to the directory where cloudbaserc.json is located)
@/absolute/path/key.pem	Absolute path
A plain string not starting with @	Treated as a literal value (you must escape line breaks as \n yourself)

Notes:

• BOM and leading/trailing whitespace are automatically stripped when reading file content, keeping formats like PEM clean.
• If the referenced file does not exist or cannot be read, the CLI will report an error and abort creation. Please check that the path is correct.
• This syntax can be used in both tcb integration create and tcb config update integration.
• It is recommended to add key files to .gitignore to avoid committing sensitive credentials to the repository.

Command Parameters

Parameter	Description	Required
<keyId>	Integration instance identifier to create (positional, matches the keyId in cloudbaserc.json); if not specified, all integrations are created in batch	No
--yes	Skip all confirmations (batch creation)	No

Tips:

• When <keyId> is not specified, you will be prompted whether to batch create all integrations in the configuration file
• When <keyId> is specified, only the matching integration will be created

Usage Examples

Create Single Integration

If multiple integrations are configured in the configuration file, you can pass the keyId positional argument to create only one of them:

# Create only the integration with keyId key-abc123
tcb integration create key-abc123

Batch Create Integrations

If multiple integrations are configured in the configuration file, you will be prompted whether to batch create when keyId is not specified:

# Interactive confirmation for batch creation
tcb integration create

# Skip confirmation, batch create all integrations directly
tcb integration create --yes

Output Example

✓ Integration instance created successfully: my-integration

Next steps:
  View details    tcb integration get <key-id>
  Bind cloud function  tcb integration bind-resource <key-id> --function <function-name>

Batch creation completed: 1 succeeded, 0 failed

Batch Creation

You can configure multiple integration instances in the integrations array to create in batch:

{
  "integrations": [
    {
      "name": "integration-1",
      "authTypeCode": "custom"
    },
    {
      "name": "integration-2",
      "authTypeCode": "wechat"
    }
  ]
}

After executing tcb integration create, the CLI will concurrently create these integration instances (up to 5 per batch) and output the creation results.

Error Handling

If the configuration file format is incorrect, the CLI will report an error and list all error messages:

Configuration file format error:
1. integrations[0].name cannot be empty
2. integrations[0].authTypeCode cannot be empty

Please fix the configuration file and re-execute.

Notes

• Integration name allows duplicates, Key ID is the unique identifier
• Auth type cannot be modified after creation
• Key ID will be automatically generated after successful creation (format: key-[32-bit hexadecimal])
• If demoCodeFunctionName is configured, it will be automatically bound to the specified cloud function after successful creation

Related Documentation

• Query Integration List
• Query Integration Details
• Bind to Cloud Function
• Configuration File - Initialize Configuration