BytePlus CDN Skill

Installation and Configuration

Before using the BytePlus CDN Skill, please configure your environment following these steps.

1. Install Dependencies

Before using this skill, you need to install Python dependencies first. Please run the following command in the terminal:

cd /path/to/byteplus-cdn
pip3 install -r reference/requirements.txt

2. Configure Authentication (Credentials)

Before executing any commands, you need to set the environment variables BYTEPLUS_AK and BYTEPLUS_SK for secure authentication. This is a prerequisite for calling BytePlus OpenAPI.

Security Best Practices:

• Create a .env file only in the project root directory
• Restrict BytePlus API keys to only the CDN permissions needed (least privilege principle)
• Never commit .env file to version control

You can create a .env file in the project root directory to store the AK and SK environment variables:

BYTEPLUS_AK=YourAccessKey
BYTEPLUS_SK=YourSecretKey

Windows PowerShell

$env:BYTEPLUS_AK="YourAccessKey"
$env:BYTEPLUS_SK="YourSecretKey"

Linux / macOS

export BYTEPLUS_AK="YourAccessKey"
export BYTEPLUS_SK="YourSecretKey"

3. Verify Installation

After configuration, you can try running the CLI tool's help command to verify if the installation is successful:

python3 scripts/cli.py --help

If the help information is successfully output, it indicates that the environment configuration is complete.

Feature Overview

This is a local command-line toolkit for operating BytePlus CDN, fully corresponding to all the instruction requirements in CLI.md. It includes the following core features:

1. Add CDN Domain - supports two methods:
   • Method 1: Directly configure the origin (supports Alibaba Cloud OSS, Tencent Cloud COS, AWS S3, BytePlus TOS, IP, Domain)
   • Method 2: Bind an existing distribution policy template
2. Create Policy Template - pre-configure and publish CDN distribution policies
3. Purge Cache - file refresh and directory refresh
4. Prefetch Cache - pre-load files from origin to CDN nodes
5. Create Offline/Real-time Log Delivery Tasks - configure log delivery destinations, supporting delivery to platforms like S3, BytePlus TOS, Splunk, etc.

✨ New Feature: Interactive Guide (Interactive Mode) If you run a command without any parameters (e.g., python3 scripts/cli.py add-domain oss), the CLI will guide you through the required parameters step by step like a wizard!

Agent Interaction Guidelines

When the Agent (AI) finds that it needs to collect missing parameters from the user, must follow these interaction specifications:

1. Option Type Parameters: Must use the AskUserQuestion tool to let the user make single or multiple selections (e.g., origin type, service type).
2. In-depth Understanding and Transparency of Underlying Prompts: Before calling AskUserQuestion to collect parameters, you must read the prompt and help definitions of the corresponding parameters in scripts/cli.py.
3. Construct Precise Collection Forms: In the collection form (AskUserQuestion) presented to the user, the description or options you provide must fully include the special prompts from cli.py! For example: if cli.py specifies that --domain can input "all" to represent all domains, you must provide a special ["All Domains (all)"] option in the form, and must not make up irrelevant test options yourself.
4. String Input Type Parameters: Except for special values supported by the underlying layer (such as all), always provide a ["Manual Input (Please select Other to input)"] option, allowing the user to evoke a friendly text input prompt via the system's own Other option.

Command List (Corresponding to CLI List)

The following examples all demonstrate usage in non-interactive mode (bringing all parameters at once). If you want to use interactive mode, simply omit the --xxx parameters.

1-6. Add CDN Domain (add-domain)

• Alibaba Cloud OSS (CLI 1)

  python3 scripts/cli.py add-domain oss --domain YOUR_DOMAIN_NAME --origin YOUR_BUCKET_NAME.YOUR_OSS_REGION.aliyuncs.com --service-type web --private-bucket yes --bucket-ak YOUR_AK --bucket-sk YOUR_SK --apply-recommended yes
  

• Tencent Cloud COS (CLI 2)

  python3 scripts/cli.py add-domain cos --domain YOUR_DOMAIN_NAME --origin YOUR_BUCKET_NAME.cos.YOUR_COS_REGION.myqcloud.com --service-type download --private-bucket no --apply-recommended yes
  

• AWS S3 (CLI 3)

  python3 scripts/cli.py add-domain aws --domain YOUR_DOMAIN_NAME --origin YOUR_BUCKET_NAME.s3.YOUR_AWS_REGION.amazonaws.com --service-type video --private-bucket yes --bucket-ak YOUR_AK --bucket-sk YOUR_SK --region YOUR_AWS_REGION --apply-recommended yes
  

• BytePlus TOS (CLI 4)

  python3 scripts/cli.py add-domain tos --domain YOUR_DOMAIN_NAME --origin YOUR_BUCKET_NAME.YOUR_TOS_REGION.bytepluses.com --service-type web --private-bucket yes --apply-recommended yes
  

• IP Origin (CLI 5)

  python3 scripts/cli.py add-domain ip --domain YOUR_DOMAIN_NAME --origin YOUR_IP_ADDRESS --service-type web --apply-recommended yes
  

• Domain Origin (CLI 6)

  python3 scripts/cli.py add-domain domain --domain YOUR_DOMAIN_NAME --origin YOUR_ORIGIN_DOMAIN --service-type web --apply-recommended yes
  

• Bind Policy Template - add a domain by binding a published distribution policy

  # Basic Usage
  python3 scripts/cli.py add-domain template --domain YOUR_DOMAIN_NAME --service-template-id tpl-s2Q4mq
  
  # Enable HTTPS
  python3 scripts/cli.py add-domain template --domain YOUR_DOMAIN_NAME --service-template-id tpl-s2Q4mq --https-switch on --cert-id cert-044833503b2349b4b42c2e80b0aa8c23
  
  # Full Usage (including cipher policy and rule engine policy)
  python3 scripts/cli.py add-domain template --domain YOUR_DOMAIN_NAME,img.YOUR_DOMAIN_NAME --service-template-id tpl-s2Q4mq --cipher-template-id tpl-cqgRvW --https-switch on --cert-id cert-044833503b2349b4b42c2e80b0aa8c23 --rule-template-ids tpl-re9gvl6,tpl-abc123
  

7-11. Create Policy Template (create-template)

The command structure is similar to add-domain, using --title and --message instead of --domain.

• Alibaba Cloud OSS (CLI 7)

  python3 scripts/cli.py create-template oss --title "YOUR_TEMPLATE_TITLE" --origin YOUR_BUCKET_NAME.YOUR_OSS_REGION.aliyuncs.com --service-type web --private-bucket no --apply-recommended yes
  

• Other cloud providers and origin types (cos, aws, ip, domain) are the same, just use create-template <origin-type>.

12-13. Refresh Cache (refresh purge)

• File Refresh (CLI 12) - up to 100 URLs

  python3 scripts/cli.py refresh file --urls "https://YOUR_DOMAIN_NAME/1.jpg,https://YOUR_DOMAIN_NAME/2.jpg"
  

• Directory Refresh (CLI 13) - up to 50 directories, must end with /

  python3 scripts/cli.py refresh dir --urls "https://YOUR_DOMAIN_NAME/images/,https://YOUR_DOMAIN_NAME/assets/"
  

14. Prefetch Cache (preload prefetch)

• File Pre-warm (CLI 14) - up to 100 URLs

  python3 scripts/cli.py preload --urls "https://YOUR_DOMAIN_NAME/1.jpg,https://YOUR_DOMAIN_NAME/2.jpg"
  

15. Create Offline Log Delivery Task (log-offline)

Deliver offline logs of domains to object storage (TOS/S3).

• Deliver to TOS

  python3 scripts/cli.py log-offline tos --bucket YOUR_BUCKET_NAME/logs --domain YOUR_DOMAIN_NAME --private-bucket no --endpoint YOUR_TOS_ENDPOINT --region YOUR_TOS_REGION
  

• Deliver to Private S3

  python3 scripts/cli.py log-offline s3 --bucket YOUR_BUCKET_NAME/logs --domain YOUR_DOMAIN_NAME --endpoint YOUR_S3_ENDPOINT --region YOUR_AWS_REGION --private-bucket yes --ak YOUR_AK --sk YOUR_SK
  

16. Create Real-time Log Delivery Task (log-realtime)

Deliver real-time logs of domains to external systems (TLS, SLS, HttpServer, Splunk, BigQuery).

• Deliver to TLS

  python3 scripts/cli.py log-realtime tls --domain YOUR_DOMAIN_NAME --project-id YOUR_PROJECT_ID --region HongKong --topic-name YOUR_TOPIC_NAME --ttl 30
  

• Deliver to SLS

  python3 scripts/cli.py log-realtime sls --domain YOUR_DOMAIN_NAME --sls-endpoint YOUR_SLS_ENDPOINT --project YOUR_PROJECT_NAME --log-store YOUR_LOG_STORE --ak YOUR_AK --sk YOUR_SK
  

• Deliver to HTTP Server

  python3 scripts/cli.py log-realtime http_server --domain YOUR_DOMAIN_NAME --url https://log-server.YOUR_DOMAIN_NAME/ingest --auth-mechanism true --secret-key YOUR_SECRET_KEY --compress-type gzip
  

• Deliver to Splunk

  python3 scripts/cli.py log-realtime splunk --domain YOUR_DOMAIN_NAME --url https://splunk.YOUR_DOMAIN_NAME:8088/services/collector/event --token YOUR_TOKEN
  

• Deliver to BigQuery

  # Method 1: Pass JSON string directly
  python3 scripts/cli.py log-realtime bigquery --domain YOUR_DOMAIN_NAME --project-id YOUR_GCP_PROJECT_ID --dataset-id YOUR_DATASET_ID --table-id YOUR_TABLE_ID --auth-str '{"type":"service_account",...}'
  
  # Method 2 (Recommended): Pass JSON via local file (CLI will automatically read and escape)
  python3 scripts/cli.py log-realtime bigquery --domain YOUR_DOMAIN_NAME --project-id YOUR_GCP_PROJECT_ID --dataset-id YOUR_DATASET_ID --table-id YOUR_TABLE_ID --auth-file /path/to/gcp-auth.json
  

Recommended Configuration Description (Only applicable to add-domain and create-template)

When you use --apply-recommended yes, the CLI will automatically inject the following CDN optimization configurations based on --service-type:

1. Web Acceleration (web)
   • Cache key includes all query parameters.
   • Do not cache .php, .jsp, .asp, .aspx, and cache all files matched by /* root directory for 30 days by default.
   • Enable HTML page optimization and Gzip smart compression.
2. Download Acceleration (download)
   • Cache key ignores all query parameters.
   • Enable Range shard origin pull, origin redirect follow, and Multi Range optimization.
3. VOD Acceleration (video)
   • Includes all optimizations from download acceleration.
   • Additionally enable video seek feature.

Executable File Function Description

If you need to understand the function description of the multiple executable files provided in the scripts folder, you can directly refer to the reference/about.txt file.