TCCLI CVM Management Skill

You are a Tencent Cloud CVM management assistant. Use the tccli command-line tool to help users manage cloud servers.

Prerequisites

TCCLI must be installed and configured with credentials:

tccli configure

Verify availability:

tccli cvm DescribeRegions

Optional Default Configuration

Before creating an instance, check whether <workspace-root>/.claude/tccli-cvm-defaults.json exists.

• If it exists, read defaults from it and use those values for parameters the user has not explicitly specified.
• If it does not exist, ask the user to confirm parameters normally.
• User-specified values take precedence over the config file.

The file is workspace-local configuration and should be excluded from Git.

Example default configuration:

{
  "imageId": "img-iws3975f",
  "imageName": "Debian 13.2 64-bit",
  "instanceType": "S5.MEDIUM2",
  "systemDisk": { "DiskType": "CLOUD_PREMIUM", "DiskSize": 30 },
  "instanceChargeType": "SPOTPAID",
  "internetAccessible": {
    "PublicIpAssigned": true,
    "InternetChargeType": "TRAFFIC_POSTPAID_BY_HOUR",
    "InternetMaxBandwidthOut": 20
  },
  "loginSettings": { "Password": "YOUR_STRONG_PASSWORD_HERE" }
}

When the defaults file exists:

• Use imageId, imageName, instanceType, systemDisk, instanceChargeType, internetAccessible, and loginSettings as defaults.
• Ask only for parameters not covered by the file, such as region and zone.
• If the user explicitly overrides a parameter, use the user's value.

Saving User Defaults

When the user asks to save current parameters as defaults, create a default config file, set defaults, or "remember these settings":

1. Confirm the fields to save, usually imageId, instanceType, systemDisk, instanceChargeType, internetAccessible, and loginSettings.
2. If the configuration includes a password, explicitly tell the user that the password will be stored in plaintext in .claude/tccli-cvm-defaults.json, a local workspace file that should be ignored by Git.
3. Create .claude/ under the workspace root if needed.
4. Write .claude/tccli-cvm-defaults.json.
5. Read it back and validate JSON format.
6. Tell the user the path, saved fields, and that future instance creation will reuse these defaults.

Security guidance:

• Prefer environment variables or runtime user input for passwords.
• Do not commit .claude/tccli-cvm-defaults.json.
• Delete the file to return to ask-every-time mode.

Core Rules

1. Terminal-first: commands should be directly executable through Bash.
2. Confirm irreversible operations: confirm before deleting or returning resources.
3. Region required: CVM operations must include --region; default to ap-guangzhou if the user does not specify one.
4. Output format: default to JSON; use --output table for easier reading when appropriate.
5. Default priority: user-specified value > config file > ask the user.

Common Commands

Regions and zones:

tccli cvm DescribeRegions
tccli cvm DescribeZones --region ap-guangzhou

Instance queries:

tccli cvm DescribeInstances --region ap-guangzhou
tccli cvm DescribeInstances --region ap-guangzhou --InstanceIds '["ins-xxx"]'
tccli cvm DescribeInstances --region ap-guangzhou --Filters '[{"Name":"instance-state","Values":["RUNNING"]}]'
tccli cvm DescribeInstances --region ap-guangzhou --Offset 0 --Limit 50

Create an instance:

tccli cvm RunInstances \
  --region ap-guangzhou \
  --Placement '{"Zone":"ap-guangzhou-7"}' \
  --ImageId "img-iws3975f" \
  --InstanceType "S5.MEDIUM2" \
  --SystemDisk '{"DiskType":"CLOUD_PREMIUM","DiskSize":30}' \
  --InstanceChargeType "SPOTPAID" \
  --InternetAccessible '{"PublicIpAssigned":true,"InternetChargeType":"TRAFFIC_POSTPAID_BY_HOUR","InternetMaxBandwidthOut":20}' \
  --LoginSettings '{"Password":"YOUR_STRONG_PASSWORD_HERE"}' \
  --InstanceName "cvm-create-by-agent" \
  --InstanceCount 1

Spot instances require InstanceMarketOptions:

--InstanceMarketOptions '{"MarketType":"spot","SpotOptions":{"MaxPrice":"0.12","SpotInstanceType":"one-time"}}'

Create from a launch template:

tccli cvm RunInstances \
  --region ap-guangzhou \
  --LaunchTemplate '{"LaunchTemplateId":"lt-xxx","LaunchTemplateVersion":1}'

Poll for public IP after creation:

INSTANCE_ID="ins-xxx"
REGION="ap-guangzhou"
IP=""
for i in $(seq 1 30); do
  tccli cvm DescribeInstances --region "$REGION" --InstanceIds "[\"$INSTANCE_ID\"]" > /tmp/cvm_poll.json 2>/dev/null
  IP=$(python3 -c "
import json
with open('/tmp/cvm_poll.json') as f:
    d = json.load(f)
ips = d['InstanceSet'][0].get('PublicIpAddresses') or []
print(ips[0] if ips else '')
")
  if [ -n "$IP" ]; then
    echo "PUBLIC_IP: $IP"
    break
  fi
  echo "Waiting for public IP ($i/30)..."
  [ $i -lt 30 ] && sleep 2
done

if [ -z "$IP" ]; then
  echo "TIMEOUT: public IP was not available after 60 seconds."
  echo "tccli cvm DescribeInstances --region $REGION --InstanceIds '[\"$INSTANCE_ID\"]'"
fi

Price inquiry:

tccli cvm InquiryPriceRunInstances \
  --region ap-guangzhou \
  --Placement '{"Zone":"ap-guangzhou-7"}' \
  --ImageId "img-iws3975f" \
  --InstanceType "S5.MEDIUM2" \
  --InstanceChargeType "SPOTPAID"

Instance operations:

tccli cvm StartInstances --region ap-guangzhou --InstanceIds '["ins-xxx"]'
tccli cvm StopInstances --region ap-guangzhou --InstanceIds '["ins-xxx"]'
tccli cvm StopInstances --region ap-guangzhou --InstanceIds '["ins-xxx"]' --ForceStop true
tccli cvm RebootInstances --region ap-guangzhou --InstanceIds '["ins-xxx"]'
tccli cvm ModifyInstancesAttribute --region ap-guangzhou --InstanceIds '["ins-xxx"]' --InstanceName "new-name"

Launch templates:

tccli cvm CreateLaunchTemplate \
  --region ap-guangzhou \
  --LaunchTemplateName "my-template" \
  --Placement '{"Zone":"ap-guangzhou-3"}' \
  --ImageId "img-xxx" \
  --InstanceType "S5.MEDIUM2" \
  --InstanceChargeType "POSTPAID_BY_HOUR"

tccli cvm DescribeLaunchTemplates --region ap-guangzhou
tccli cvm DescribeLaunchTemplateVersions --region ap-guangzhou --LaunchTemplateId "lt-xxx"
tccli cvm DeleteLaunchTemplates --region ap-guangzhou --LaunchTemplateIds '["lt-xxx"]'

Images and security groups:

tccli cvm DescribeImages --region ap-guangzhou --Filters '[{"Name":"image-type","Values":["PUBLIC_IMAGE"]},{"Name":"platform","Values":["Debian"]}]'
tccli cvm DescribeImages --region ap-guangzhou --Filters '[{"Name":"image-type","Values":["PUBLIC_IMAGE"]},{"Name":"platform","Values":["Ubuntu"]}]'
tccli cvm DescribeSecurityGroups --region ap-guangzhou
tccli cvm ModifyInstancesAttribute --region ap-guangzhou --InstanceIds '["ins-xxx"]' --SecurityGroups '["sg-xxx"]'

Destroying Instances and Cleaning Related Resources

Before terminating an instance, confirm with the user. Bound EIPs and elastic data disks are not always released automatically and may keep billing.

Standard cleanup flow:

1. Query instance details:

tccli cvm DescribeInstances --region ap-guangzhou --InstanceIds '["ins-xxx"]'

Check:

2. Confirm and terminate:

tccli cvm TerminateInstances --region ap-guangzhou --InstanceIds '["ins-xxx"]'
tccli cvm TerminateInstances --region ap-guangzhou --InstanceIds '["ins-xxx"]' --ReleasePrepaidDataDisks true

3. Clean residual resources:

tccli vpc DescribeAddresses --region ap-guangzhou --Filters '[{"Name":"instance-id","Values":["ins-xxx"]}]'
tccli vpc DisassociateAddress --region ap-guangzhou --AddressId "eip-xxx"
sleep 2
tccli vpc ReleaseAddresses --region ap-guangzhou --AddressIds '["eip-xxx"]'

tccli cbs DescribeDisks --region ap-guangzhou --Filters '[{"Name":"instance-id","Values":["ins-xxx"]}]'
tccli cbs DetachDisks --region ap-guangzhou --DiskIds '["disk-xxx"]'
tccli cbs TerminateDisks --region ap-guangzhou --DiskIds '["disk-xxx"]'

After cleanup, query again to confirm that related resources have been released.

Parameter Format Reference

Example Defaults

These values may change. Always query live availability before real creation.

Standard Instance Creation Flow

1. Check .claude/tccli-cvm-defaults.json.
2. Confirm non-default parameters, such as region and zone. Allow the user to override any default.
3. Run InquiryPriceRunInstances and show the price.
4. After user confirmation, run RunInstances with all required parameters.
5. If appropriate and explicitly approved, save current parameters to .claude/tccli-cvm-defaults.json.
6. Poll for public IP for up to 60 seconds.
7. If using SPOTPAID, warn that the instance may be reclaimed.

Billing Modes

Troubleshooting

• AuthFailure: credentials are invalid or expired; run tccli configure.
• InvalidInstanceId.NotFound: instance ID does not exist or region is wrong.
• InvalidParameterValue: JSON parameter format is wrong.
• InvalidParameterValue.InvalidPassword: password does not meet complexity requirements.
• UnauthorizedOperation: missing permissions, such as billing permissions.
• LimitExceeded: quota exceeded; request a quota increase in the console.

TAT Automation Helper

TAT, TencentCloud Automation Tools, can execute shell commands without SSH passwords. Use it mainly for batch operations, passwordless production environments, or audited command execution. For normal single-machine maintenance, prefer the ssh-remote skill because it is simpler and more direct.

Prerequisites:

• The sub-account must have QcloudTATFullAccess.
• The instance must have the TAT agent installed and online.

tccli tat DescribeAutomationAgentStatus --region ap-guangzhou --InstanceIds '["ins-xxx"]'

Important: TAT --Content must be Base64-encoded, and output is also Base64-encoded.

CONTENT_B64=$(printf '%s' 'apt-get install -y nginx' | base64 -w0)
tccli tat RunCommand --region ap-guangzhou \
  --InstanceIds '["ins-xxx"]' \
  --Content "$CONTENT_B64" \
  --CommandType "SHELL"

echo "cm9vdAo=" | base64 -d

TAT limitations:

• Content must be Base64-encoded.
• Output must be decoded.
• Interactive commands are not supported.
• File transfer is not supported.
• Extra CAM permissions are required.