Skip to main content

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.

ItemRule
RequiredNo. 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
SlugKeeps 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)
ConflictsA 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​

ParameterDescriptionRequired
<name>Integration to create, either its keyId or its name; omit to create all integrationsNo
--keyid <keyId>Explicitly set the instance identifier. Invalid formats fail fast; conflicting with a different keyId in the configuration also failsNo
--yesSkip confirmationsNo
--jsonOutput in JSON formatNo

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-pay uses /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​

  • authTypeCode is required; list the available values with tcb integration types
  • name may be duplicated; it defaults to the keyId when not set
  • Auth type cannot be modified after creation
  • When demoCodeFunctionName is set, the instance is bound to that cloud function after creation; deploy the function with tcb fn deploy first
  • --verbose logs mask credential fields only; structural fields such as callback URL and type stay readable