App Deployment

v3.0.0+

The tcb app command is available since v3.0.0.

The tcb app command is used to deploy and manage CloudBase cloud apps. Each deployment overwrites the previous one and retains deployment history (viewable via tcb app versions).

Best for: Frontend Projects with Build Pipelines

Suitable for:

• Frontend projects with install + build steps (React / Vue / Next.js / Vite / Angular / Nuxt, etc.)
• Pure static projects
• Automated deployment in CI/CD pipelines

CLI automatically handles: Install dependencies → Build → Upload artifacts → Bind routes. Each deployment overwrites the previous one. View deployment history via tcb app versions list.

---

tcb app deploy

Deploy an app. CLI automatically executes: install dependencies → build → upload build artifacts → bind routes.

The following three invocation styles are completely equivalent:

tcb app deploy [serviceName] [options]   # Full command
tcb deploy [serviceName] [options]       # Top-level alias
tcb [options]                            # Bare command (routes to app deploy when no subcommand given)

Parameters

Parameter	Description	Default
[serviceName]	App name (optional; reads from package.json or prompts interactively if omitted)	—
-e, --env-id <envId>	Target environment ID	—
--framework <type>	Framework type: react / vue / vite / next / nuxt / angular / static	—
--install-command <cmd>	Install command (leave empty to skip install)	npm install
--build-command <cmd>	Build command (leave empty to skip build, suitable for pure static projects)	—
--output-dir <dir>	Build output directory (default ./dist; use ./ when no build is needed)	Auto-detect
--deploy-path <path>	Static hosting mount path	/${serviceName}
--cwd <path>	Project directory (relative path)	Current directory
--ignore <patterns>	File patterns to ignore, comma-separated, appended after app.ignore	—
--enable-git-ignore	Merge project .gitignore rules (disabled by default)	Disabled
-f, --force	Skip confirmation and overwrite when app name already exists	—

Ignore Rule Syntax

Both the --ignore option and .gitignore merging (with --enable-git-ignore) follow glob wildcard syntax:

Syntax	Example	Description
Wildcard	*.log	Matches file names (* does not cross directory levels)
Any level	**/temp	Matches temp at any depth
Whole directory	dist/	Ignores the dist directory and all its contents
Root anchored	/build	Matches build only under the upload root
Relative path	src/test	Path anchored relative to the upload root
Single char / char class	?.log, [ab].log	Supports single-character wildcard and character classes

Negation (!): Not supported. Negation rules (e.g. !important.log) in .gitignore or --ignore take no effect; a one-time notice is printed at runtime and the rule is ignored.

Merge priority: default rules (node_modules, .git) > .gitignore (when enabled) > app.ignore > --ignore, all accumulated.

Examples

# Deploy a Vite project (run from project root)
tcb app deploy --framework vite -e my-env-id

# Using top-level alias, completely equivalent
tcb deploy --framework vite -e my-env-id

# Bare command: interactive guided deployment
tcb

# Specify a project subdirectory (monorepo scenario)
tcb app deploy --cwd ./frontend -e my-env-id

# Deploy a Next.js project with custom output directory
tcb app deploy --framework next --output-dir .next -e my-env-id

# Pure static project (skip build step)
tcb app deploy --framework static --build-command "" --output-dir ./public -e my-env-id

# CI scenario: skip confirmation, overwrite existing app
tcb app deploy --framework react --force -e my-env-id

# Append ignore patterns (comma-separated), appended after app.ignore
tcb app deploy --ignore "dist/test,.env.local"

# Merge project .gitignore rules (disabled by default, enable explicitly)
tcb app deploy --enable-git-ignore

# Use both: merge .gitignore + append CLI ignore patterns
tcb app deploy --enable-git-ignore --ignore "*.map"

Configuring Deployment via cloudbaserc.json

In addition to specifying deployment options via CLI parameters, you can configure the app field in cloudbaserc.json for a zero-parameter deployment experience.

Configuration file structure:

{
  "version": "2.0",
  "envId": "my-env-id",
  "app": {
    "serviceName": "my-app",
    "root": "./packages/web",
    "framework": "react",
    "installCommand": "npm install",
    "buildCommand": "npm run build",
    "outputDir": "build",
    "deployPath": "/my-app",
    "envVariables": {
      "API_URL": "https://api.example.com"
    }
  }
}

Configuration fields:

Field	Type	Required	Default	Description
serviceName	String	No	package.json name or directory name	Cloud app service name
root	String	No	Current directory	App project root directory (relative to cloudbaserc.json), for specifying sub-project paths in monorepo scenarios
framework	String	No	Auto-detect	Frontend framework type, supported values: react, vue, vite, next, nuxt, angular, static
installCommand	String	No	npm install	Install dependencies command, empty string to skip the install step
buildCommand	String	No	Auto-detect based on framework	Build command, empty string to skip the build step (for pure static projects)
outputDir	String	No	./dist (./ when no build command)	Build output directory
deployPath	String	No	/${serviceName}	Deployment path (static hosting mount path), must start with /
envVariables	Object	No	—	Environment variables (non-sensitive), key-value pairs, injected during cloud build
ignore	String/Array	No	—	Glob patterns for files/directories to ignore during packaging and upload. To merge the project .gitignore rules, run tcb app deploy --enable-git-ignore to enable explicitly (disabled by default)

General Priority Rule: Explicit specification > Declarative configuration > Auto-inference > Interactive prompt

⚠️ Note: Some parameters have special rules (e.g., envVariables has no CLI parameter, buildCommand has framework defaults), see the table below for details.

Priority for each parameter:

Parameter	Priority
serviceName	CLI positional argument > cloudbaserc.json configuration > Interactive selection > Auto-infer (package.json or directory name)
root	--cwd option > cloudbaserc.json configuration > Current directory
framework	--framework option > cloudbaserc.json configuration > Auto-detect (package.json dependencies) > Undefined
installCommand	--install-command option > cloudbaserc.json configuration > Auto-infer (npm install or empty) > Interactive input
buildCommand	--build-command option > cloudbaserc.json configuration > Auto-detect (framework defaults or package.json scripts) > Interactive input > Empty string
outputDir	--output-dir option > cloudbaserc.json configuration > Auto-detect (framework defaults) > Interactive input > ./dist (with build) or ./ (without build)
deployPath	--deploy-path option > cloudbaserc.json configuration > Interactive input (default: /{serviceName})
envVariables	Only read from cloudbaserc.json (no CLI parameter)
ignore	Default rules (node_modules, .git) > .gitignore (with --enable-git-ignore) > cloudbaserc.json app.ignore > --ignore option, all accumulated

Special Notes:

• Both --cwd and config.app.root specify the project working directory; --cwd has higher priority
• envVariables has no corresponding CLI parameter; can only be configured in cloudbaserc.json
• When --yes or --json is specified, all interactive input is skipped and auto-inferred values are used instead
• Framework auto-detection follows this priority: Next.js > Nuxt > Angular > Vite > Vue CLI > React (CRA) > Static HTML

Auto-save: After the first successful deployment, if no app configuration exists in cloudbaserc.json, CLI automatically saves the deployment parameters to the config file. Subsequent deployments require no repeated input.

For more details on configuration fields, see Configuration File documentation.

---

tcb app list

List all apps in the current environment.

tcb app list [options]

Parameters

Parameter	Description	Default
-e, --env-id <envId>	Environment ID	—
-l, --limit <n>	Number of results	20
-o, --offset <n>	Offset	0
--json	Output JSON	—

Example

tcb app list -e my-env-id

---

tcb app info

View details of a specific app (status, version, access domain, etc.).

tcb app info <serviceName> [options]

Example

tcb app info my-app -e my-env-id

# JSON output (for scripts to read the access domain)
tcb app info my-app --json -e my-env-id

---

tcb app versions list

List the version history of an app.

tcb app versions list <serviceName> [options]

Parameters

Parameter	Description	Default
<serviceName>	App name (required)	—
-l, --limit <n>	Number of results	20
-o, --offset <n>	Offset	0
-e, --env-id <envId>	Environment ID	—

Example

tcb app versions list my-app -e my-env-id

---

tcb app versions detail

View detailed information of a specific app version. Defaults to the latest version.

tcb app versions detail <serviceName> [options]

Parameters

Parameter	Description	Default
<serviceName>	App name (required)	—
--version-name <name>	Version name (latest version if omitted)	—
-e, --env-id <envId>	Environment ID	—

Example

# View latest version details
tcb app versions detail my-app -e my-env-id

# View a specific version
tcb app versions detail my-app --version-name my-app-001 --env-id env-xxx

---

tcb app delete

Delete an app record. Does not delete the underlying app resource files.

tcb app delete <serviceName> [options]

Parameters

Parameter	Description	Default
<serviceName>	App name (required)	—
-e, --env-id <envId>	Environment ID	—
--dry-run	Preview the delete operation without executing	—

Example

tcb app delete my-app -e my-env-id

# Preview delete (dry run)
tcb app delete my-app -e my-env-id --dry-run

Warning

This operation deletes all versions and resources of the app and is irreversible. Project resource files must be manually cleaned up in the static hosting bucket.