tcb integration create
Create integration instances from the integrations field of cloudbaserc.json. Without a positional argument, every configured integration is created in batch.
Usage
tcb integration create [name] [--keyid <keyId>] [--yes] [--json]
Quick Start
1. Initialize the Configuration
# Pick the integration type interactively
tcb config init integration stripe-test
# Or specify the type directly
tcb config init integration stripe-test --type stripe-pay
The positional argument can be either the instance name or the keyId: it is matched as a keyId first, then as a name. Multiple integrations sharing the same name require a keyId. tcb config init integration generates a keyId from the name and writes it to the configuration:
Integration keyId: stripe-test-a1b2c3d4 (generated, used in the callback domain, cannot be changed after creation)
2. Complete the Configuration
Edit the generated cloudbaserc.json and replace placeholders with real values:
{
"envId": "env-abc123",
"integrations": [
{
"keyId": "stripe-test-a1b2c3d4",
"name": "stripe-test",
"authTypeCode": "stripe-pay",
"description": "Stripe payments",
"envVariables": {
"stripeSecretKey": "sk_live_xxx"
}
}
]
}
3. Create the Integration
tcb integration create
keyId Rules
keyId is embedded in the callback domain {keyId}.integration-callback.tcloudbase.com, so it cannot be changed after creation.
| Item | Rule |
|---|---|
| Required | No. When omitted, it is generated from name and written back to the configuration |
| Generated format | <slug of name>-<8 random chars>, e.g. stripe-test-a1b2c3d4 |
| Slug | Keeps lowercase letters, digits and hyphens only; other characters (including Chinese) are dropped, falling back to integration; max 24 characters |
| Valid format | ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$, at most 63 characters (DNS label limit) |
| Conflicts | A generated keyId rejected as already existing is retried with a new suffix, up to 3 attempts; an explicit keyId is never retried |
⚠️ The generated keyId is written back to
cloudbaserc.json. Only JSON configuration is supported: non-JSON configuration is not rewritten, and the CLI warns with the list of keyIds to add manually.
Positional Argument
[name] is matched as a keyId first (for older scripts using create <keyId>), then as a name:
- Multiple matches by name: the command fails and lists candidate keyIds rather than guessing
- No match by keyId or name: the command fails and lists every integration in the configuration
Parameters
| Parameter | Description | Required |
|---|---|---|
<name> | Integration to create, either its keyId or its name; omit to create all integrations | No |
--keyid <keyId> | Explicitly set the instance identifier. Invalid formats fail fast; conflicting with a different keyId in the configuration also fails | No |
--yes | Skip confirmations | No |
--json | Output in JSON format | No |
Examples
Batch Create Integrations
# Interactive confirmation for batch creation
tcb integration create
# Skip confirmation, create all integrations
tcb integration create --yes
Create a Single Integration
# By name
tcb integration create stripe-test
# By keyId
tcb integration create stripe-test-a1b2c3d4
Set the keyId Explicitly
tcb integration create stripe-test --keyid stripe-test-a1b2c3d4
Output Example
✓ Integration instance created successfully: stripe-test
Next steps:
View details tcb integration get stripe-test-a1b2c3d4
Bind cloud function tcb integration bind-resource stripe-test-a1b2c3d4 --function <function-name>
Batch creation completed: 1 succeeded, 0 failed
Batch Creation
Configure multiple instances in the integrations array to create them in batch:
{
"integrations": [
{
"name": "integration-1",
"authTypeCode": "custom"
},
{
"name": "integration-2",
"authTypeCode": "wechat"
}
]
}
tcb integration create creates them concurrently (up to 5 per batch) and writes each generated keyId back to the configuration file.
Callback URL
The callback URL is generated from the integration type before submission, so third-party platforms never get the wrong address:
- If the template declares
callbackUrlParam.urlTemplate, that template wins - WeChat integrations (
weixin*/wx*) use/wechat/notify,/wechatpay/order,/wechatpay/refund stripe-payuses/stripe/webhook- Integrations without a registered callback path get no callback URL and let the cloud generate it — reusing a WeChat path makes the cloud reject it as an invalid webhook URL
Registered URLs are recomputed when the keyId changes; editing them in the configuration has no effect.
Error Handling
When the configuration is invalid, the CLI lists every error and stops:
Configuration file format error:
1. integrations[0].authTypeCode cannot be empty
2. integrations[0]: keyId allows lowercase letters, digits and hyphens (-) only, and cannot start or end with a hyphen (current value: Stripe-Test)
Notes
authTypeCodeis required; list the available values withtcb integration typesnamemay be duplicated; it defaults to the keyId when not set- Auth type cannot be modified after creation
- When
demoCodeFunctionNameis set, the instance is bound to that cloud function after creation; deploy the function withtcb fn deployfirst --verboselogs mask credential fields only; structural fields such as callback URL and type stay readable