tencent cloud

문서Cloud Application RenderingPractical TutorialHow to Implement Application Upload and Version Update via CAR-CLI

How to Implement Application Upload and Version Update via CAR-CLI

Download
포커스 모드
폰트 크기
마지막 업데이트 시간: 2026-07-09 16:20:17
CAR-CLI is a command-line tool for application version management provided by Tencent Cloud. It enables developers to quickly perform operations such as application creation, version management, file upload, and release via the command line. This tool is suitable for managing the full lifecycle of desktop applications (Application3D, ApplicationXR, ApplicationWeb) and mobile applications (ApplicationAPK). This document introduces the basic features of CAR-CLI and explains how to use CAR-CLI to build a pipeline for automating application version updates.

1. Environment Preparation

1.1 Downloading CAR-CLI

Load the remote configuration file to the current working directory.
cd workdir

wget "your config file url"
Execute the following script to download the command-line tool.
cd workdir

mkdir pkg && cd pkg
wget https://github.com/tencentyun/car-cli/releases/download/v1.0.0/car.zip
unzip car.zip
mv ./car/linux/car ../
cd ..

chmod +x car

1.2 Configuration File Requirements

Before using CAR-CLI, place the configuration file in the same directory as the executable file and replace the following Tencent Cloud account information with actual values.
Configuration Item
Description
Obtaining Method
SecretId
TencentCloud API key ID.
Tencent Cloud Console - CAM
SecretKey
TencentCloud API key.
Tencent Cloud Console - CAM
AppId
Tencent CloudApp ID.
Tencent Cloud Console - Account Information
Attention:
Ensure that the executable file and the configuration file are located in the same directory when in use.

1.3 Basic Commands

# View help information
car help

1.4 Application Version Update Pipeline Construction

The following figure shows an example of an application version update pipeline:


2. Core Command Details

2.1 Application Management

2.1.1 Creating an Application

Create a new application, which supports multiple application types for both desktop and mobile platforms.
Command format:
car create-application --name <application_name> [--app-type <application_type>]
Parameter description:
Parameter
Required
Description
Prerequisites
--name
Yes
Application Name
16 characters or fewer, supporting only Chinese characters, letters, digits, or the hyphen -.
--app-type
No
Application Type
If not specified, a desktop Application3D is created by default.
Supported application types:
Application Type
Applicable Scenarios
Platform
Application3D
3D desktop application.
Desktop Side
ApplicationXR
Extended reality application.
Desktop Side
ApplicationWeb
Web desktop application.
Desktop Side
ApplicationAPK
Android mobile application.
Mobile Side
Use Case:
# Create a desktop application (default type)
car create-application --name my-desktop-app

# Create a mobile application
car create-application --name my-mobile-app --app-type ApplicationAPK

2.2 Version Management

2.2.1 Creating an Application Version

Create a new version for the specified application. The maximum number of versions that can be created for a single application is 5.
Command format:
car create-application-version --app-id <application_id> --name <version_name> --type <package_format> [--regions <distribution_regions>] [--update-mode <update_mode>]
Parameter description:
Parameter
Required
Description
Applicable Platform
--app-id
Yes
Application ID.
Entire platform
--name
Yes
Version naming.
Entire platform
--type
Yes
Package file type.
Entire platform
--regions
No
Distribution region list.
Desktop Side only
--update-mode
No
Update method.
Desktop Side only
Supported package file types:
Platform
Supported Format
Description
Desktop Side
zip,rar,7z
Compressed package format.
Mobile Side
apk,xapk,zip
Android installation package format.
Notes:
The operation will be rejected if a version is in the "Creating"/"Pending Release"/"Creation Failed" state.
The --regions and --update-mode parameters take effect only for desktop applications and do not need to be specified for mobile applications.
The validity of the final format is verified by the backend based on the actual type of the application.
Use Case:
# Desktop: Create a full update version and distribute it to the Chinese mainland and Tokyo.
car create-application-version --app-id app-xxx --name v1.0.0 --type zip --regions ap-chinese-mainland,ap-tokyo --update-mode FULL

# Mobile: Create a new version
car create-application-version --app-id app-xxx --name mobile-v1 --type apk

2.2.2 Uploading Application Version Files

Upload the application package file to the specified version, supporting both local file paths and URLs.
Command format:
# Upload a local file
car upload-application-version-file --app-id <application_id> --version-id <version_id> --path <local_path>

# Upload from a URL
car upload-application-version-file --app-id <application_id> --url <file_url>
Parameter description:
Parameter
Required
Description
Must-Knows
--app-id
Yes
Application ID.
Must match the value used at creation.
--version-id
Yes
Application version ID.
Required for local upload.
--path
Yes (local)
Local file path.
Note the differences between Windows and Linux path formats.
--url
Yes (URL)
File download URL.
Only this parameter is required for URL upload.
Path format example:
Operating system
Path Format Example
Windows
C:\\data\\myapp.zip
Linux/macOS
/data/myapp.apk
Use Case:
# Upload a local file on Windows
car upload-application-version-file --app-id app-xxx --path C:\\data\\xxx.zip --version-id ver-xxx

# Upload a local file on Linux
car upload-application-version-file --app-id app-xxx --path /data/xxx.apk --version-id ver-xxx

# Upload from a URL
car upload-application-version-file --app-id app-xxx --url https://example.com/app.zip
Attention:
After a successful upload, the version name and package format are replaced with the name and format of the uploaded file.

2.2.3 Publishing an Application Version

Publish the specified version to make it visible to users.
Command format:
car set-version-online --app-id <application_id> --version-id <version_id>
Parameter description:
Parameter
Required
Description
--app-id
Yes
Application ID.
--version-id
Yes
Application version ID.
Platform differences:
Platform
Pre-release Verification
Description
Desktop Side
Verify the startup path.
Ensure the startup path is correctly configured.
Mobile Side
Skip verification automatically.
No additional configuration required.
Use Case:
car set-version-online --app-id app-xxx --version-id ver-xxx

2.2.4 Deleting an Application Version

Asynchronously delete the specified version. After deletion, you can confirm the status by querying the version list.
Command format:
car delete-application-version --app-id <application_id> --version-id <version_id>
Parameter description:
Parameter
Required
Description
--app-id
Yes
Application ID.
--version-id
Yes
Application version ID.
Use Case:
car delete-application-version --app-id app-xxx --version-id ver-xxx

2.2.5 Querying Application Version List

Display all version information for the specified application, including the version ID and version status.
Command format:
car describe-application-version --app-id <application_id>
Parameter description:
Parameter
Required
Description
--app-id
Yes
Application ID.
Advanced Usage: Combine the grep and awk commands to obtain the oldest version.
# Obtain the oldest version (excluding the version currently in use)
car describe-application-version --app-id app-xxx | grep -v "Inuse" | awk '{print $1}' | head -n 1
Use Case:
# Query all versions
car describe-application-version --app-id app-xxx

# Obtain the oldest version ID
car describe-application-version --app-id app-xxx | grep -v "Inuse" | awk '{print $1}' | head -n 1

3. Desktop and Mobile Differences

3.1 Feature Differences Overview

Feature Module
Desktop Side
Mobile Side
Description
Application Type
Application3D
ApplicationXR
ApplicationWeb
ApplicationAPK
Must be specified during creation.
Package Format
zip,rar,7z
apk,xapk,zip
Validated by the backend.
Distribution Region
Supported
Not supported
The --regions parameter is applicable to the desktop side only.
Update Method
Full update supported
Not supported
The --update-mode parameter is applicable to the desktop side only.
Release Verification
Verify the startup path
Automatically skipped
Platform differences.

3.2 Command Parameter Differences Details

3.2.1 create-application Command

Parameter
Desktop Side
Mobile Side
Description
--name
Required
Required
Application name.
--app-type
Optional (default: Application3D)
Required ApplicationAPK
Application type.

3.2.2 create-application-version Command

Parameter
Desktop Side
Mobile Side
Description
--app-id
Required
Required
Application ID.
--name
Required
Required
Version name.
--type
Required
Required
Package format.
--regions
Optional
Not supported
Distribution region.
--update-mode
Optional
Not supported
Update method.

3.2.3 set-version-online Command

Verification Item
Desktop Side
Mobile Side
Startup path
Mandatory validation.
Skipped automatically.

4. Version Distribution Regions

4.1 Region List

Region Code
Region Name
Type
ap-chinese-mainland
Chinese mainland
Mainland default
ap-tokyo
Tokyo Standard Region
International default
ap-tokyo-fusion
Tokyo Fusion Region
Fusion Region
ap-seoul
Seoul Standard Region
Standard Region
ap-seoul-fusion
Seoul Fusion Region
Fusion Region
ap-singapore
Singapore Standard Region
Standard Region
ap-singapore-fusion
Singapore Fusion Region
Fusion Region
eu-frankfurt
Frankfurt Standard Region
Standard Region
eu-frankfurt-fusion
Frankfurt Fusion Region
Fusion Region
na-north-america
North America Standard Region
Standard Region
na-north-america-fusion
North America Fusion Region
Fusion Region
me-middle-east-fusion
Middle East Fusion Region
Fusion Region
sa-south-america-fusion
South America Fusion Region
Fusion Region

4.2 Region Selection Recommendations

For users in the Chinese mainland: Select ap-chinese-mainland.
For international users: Select a nearby standard zone or fusion zone.
Multi-region distribution: Multiple region codes can be passed in, separated by commas.

5. Complete Usage Process Example

5.1 Desktop Application Complete Process

# 1. Create a desktop application
car create-application --name my-desktop-app

# 2. Create a new version (full update, distributed to the Chinese mainland and Tokyo)
car create-application-version --app-id app-xxx --name v1.0.0 --type zip --regions ap-chinese-mainland,ap-tokyo --update-mode FULL

# 3. Upload the application package
car upload-application-version-file --app-id app-xxx --version-id ver-xxx --path /data/myapp.zip

# 4. Release and go live
car set-version-online --app-id app-xxx --version-id ver-xxx

5.2 Mobile Application Complete Process

# 1. Create a mobile application
car create-application --name my-mobile-app --app-type ApplicationAPK

# 2. Create a new version (regions and update-mode are not required)
car create-application-version --app-id app-xxx --name v1.0.0 --type apk

# 3. Upload the application package
car upload-application-version-file --app-id app-xxx --version-id ver-xxx --path /data/myapp.apk

# 4. Release and go live
car set-version-online --app-id app-xxx --version-id ver-xxx

5.3 Version Management Automation Script


cd workdir

# Query the version list for the corresponding application
output=$(./car describe-application-version --app-id $ApplicationID) # The ApplicationID is configured as a pipeline environment variable.
lineCount=$(echo "$output" | wc -l)

# If the number of versions exceeds 5, delete the old versions.
if [ $lineCount -ge 5 ];then
versionID=$(echo "$output" | grep -v "Inuse" | awk '{print $1}' | head -n 1)
./car delete-application-version --app-id $ApplicationID --version-id $versionID
fi

# Because deleting an application version is an asynchronous operation, periodically query whether the version has been deleted successfully.
waitTimes=0
while [ $lineCount -ge 5 ]
do
output=$(./car describe-application-version --app-id $ApplicationID) # Replace with your own ApplicationID
lineCount=$(echo "$output" | wc -l)
waitTimes=$((waitTimes+1))
if [ $waitTimes -gt 20 ]
then
echo "Error: Waiting too long to delete application version."
exit 1
fi
sleep 1
done

# Query the package name and package type based on the PackageURL
fileName=$(basename $PackageURL) # The PackageURL is configured as a pipeline environment variable.
echo $fileName
fileType="${PackageURL##*.}"
echo $fileType

# Create a new version
output=$(./car create-application-version --app-id $ApplicationID --name $fileName --type $fileType)

# Upload the new version of the application to the cloud
./car upload-application-version-file --app-id $ApplicationID --version-id $output --path $fileName

# Release the new version
./car set-version-online --app-id $ApplicationID --version-id $output

6. FAQs and Precautions

6.1 Version Quantity Limit

The maximum number of versions that can be created for a single application is 5.
If a version is in the "Creating"/"Pending Release"/"Creation Failed" state, the new creation operation will be rejected.
It is recommended to periodically clean up old versions to keep the version list tidy.

6.2 Path Format Precautions

Windows: Use a backslash \\, for example, C:\\data\\app.zip.
Linux/macOS: Use a forward slash /, for example, /data/app.zip.
It is recommended that the script automatically adapts the path format based on the operating system.

6.3 Version Information Changes After Upload

After the application package is uploaded successfully:
The version name is replaced with the file name of the uploaded file.
The package format is replaced with the actual format of the uploaded file.
Confirm that the version information is correct before release.

6.4 Asynchronous Operation Description

Deleting a version is an asynchronous operation. After execution, you need to confirm the deletion status by querying the version list.
It is recommended to add polling check logic to the script to ensure that subsequent steps are executed only after the operation is completed.

도움말 및 지원

문제 해결에 도움이 되었나요?

피드백