huawei-cloud-cli-guidance

Provides guidance for Huawei Cloud KooCLI command-line tool operations. Covers KooCLI installation, IAM authentication configuration, access credential configuration, command construction, common error troubleshooting. Use this skill when users ask about any cloud-related services or wants to operate Huawei Cloud services from the terminal. Triggers: Huawei Cloud, huaweiyun, "华为云"，"华为cli", "命令行"， KooCLI, hcloud, huaweiyunCLI, Huawei Cloud command line, OBS, ECS, VPC, "云", yun， huaweiyun tool, huawei tool, "华为云工具", "云工具", "工具"

Overview

Huawei Cloud KooCLI command-line tool guidance skill, providing comprehensive KooCLI usage guide. This skill covers core functionalities including KooCLI installation, authentication configuration, command construction, common error troubleshooting, helping users efficiently manage Huawei Cloud resources.

Capability boundaries: This skill only covers Huawei Cloud KooCLI (hcloud) usage guidance. It does not cover other cloud providers' CLIs (e.g. AWS CLI), and it does not execute commands on the user's behalf: it never runs hcloud for the user, never queries live resource state or credential values, and never asks the user to paste AK/SK in the conversation. Requests outside these boundaries (e.g. "install AWS CLI", "run this hcloud command for me", "how many ECS instances do I have") must be declined or redirected to the correct entry point instead of being guessed at.

Attention

1. Any issues encountered during the use of koocli must be addressed by prioritizing the guidance steps provided in this skill. [MUST][IMPORTANT]
2. It is essential to read this document in its entirety and make full use of its guidance during the process.[MUST][IMPORTANT]

Prerequisites

• KooCLI Version: 7.2.2 or higher
• Huawei Cloud Account: Valid Huawei Cloud account with corresponding access permissions
• Authentication Credentials: Access Key (AK) and Secret Key (SK) or IAM user credentials
• Network Connection: Accessible Huawei Cloud service endpoints
• Operating System: Linux, macOS, or Windows (WSL supported)

Getting Started (Prerequisite Guide) [MUST]: first-time users must complete ./references/getting-started.md first — environment preparation, KooCLI installation, first-time authentication (privacy policy acceptance and credential security rules) and the basic usage flow — and verify installation (hcloud version) and authentication (hcloud configure list) before constructing any hcloud command. [MUST][IMPORTANT]

KooCLI Command Format Standard

Huawei Cloud KooCLI adopts a unified command format:

bash

hcloud <service> <operation> [parameters] [options]

Command Structure

• hcloud: Command-line tool name
• <service>: Cloud service name (e.g., ECS, VPC, OBS, etc.)
• <operation>: API operation name (e.g., ListServersDetails, CreateVpc, etc.)
• [parameters]: Operation parameters (e.g., instance_id, vpc_name, etc.)
• [options]: Global options (e.g., --cli-region, --cli-output, etc.)

Parameter Format Rules

1. Required parameters: Directly specified in the command, e.g., --instance_id=i-12345678
2. Optional parameters: Represented with square brackets, e.g., [--description="instance description"]
3. Authentication parameters: Use --cli- prefix, e.g., --cli-profile, --cli-region
4. Output parameters: Use --cli-output to specify output format (json/table/tsv)
5. Query parameters: Use --cli-query to perform JMESPath query filtering

Scenario Routing

Installation Scenario

1. User asks about KooCLI installation → Jump to "1. Install KooCLI"
2. User needs to verify installation → Check version command hcloud version
3. User is new to Huawei Cloud or KooCLI (first time, setup, quickstart) → Follow ./references/getting-started.md first (environment preparation → installation → first-time authentication → basic usage flow) [Required]

Authentication Scenario

1. User needs to configure authentication → Jump to "2. Configure koocli"
2. User asks about different authentication modes → Choose Profile mode, explicit parameter mode, etc. based on requirements

Command Execution Scenario

1. User needs to execute specific operations → Guide to use hcloud <service> --help to query available operations
2. User encounters errors → Jump to "8. Common issues" for troubleshooting

Output Formatting Scenario

1. User needs specific format output → Use --cli-output=json/table/tsv
2. User needs to filter results → Use --cli-query for JMESPath querying

Core Commands

refer to '../references/core-commands.md'

Architecture:

markdown

Cloud Service OpenAPI
    |
    | ECS API / VPC API / RDS API / OBS API / IAM API ...
    v
Service Metadata JSON API Definition
    |
    | Description:
    | - Service name
    | - API version
    | - Request method GET / POST / PUT / DELETE...
    | - URI path
    | - Request parameters
    | - Response structure
    | - Authentication method
    | - Region and Endpoint
    v
KooCLI Core
    |
    | Read metadata
    | Generate commands
    | Validate parameters
    | Assemble HTTP requests
    | Signature authentication
    | Call OpenAPI
    v
Dynamically Generated Commands
    |
    | hcloud <service name> <API operation name> [parameters]
    v
Unified Execution Engine
    |
    | Execute requests
    | Return results
    v
Huawei Cloud Resource Operation Results

Understand the logic and process of KooCLI managing Huawei Cloud resources. Every time Huawei Cloud service is called or problems are encountered during the process, you must refer to and understand the architecture again, clarifying current steps and subsequent steps. [Required]

1. Install KooCLI

1. Check local version

bash

hcloud version

Expected output: Current KooCLI version: 7.2.2 or higher.

2. One-click installation (skip this step if local version check passes)

bash

# Universal for all platforms
curl -sSL https://cn-north-4-hdn-koocli.obs.cn-north-4.myhuaweicloud.com/cli/latest/hcloud_install.sh -o ./hcloud_install.sh && bash ./hcloud_install.sh

# Non-interactive installation
curl -sSL https://cn-north-4-hdn-koocli.obs.cn-north-4.myhuaweicloud.com/cli/latest/hcloud_install.sh -o ./hcloud_install.sh && bash ./hcloud_install.sh -y

After installation completes, check if local installation was successful.

Important: No additional operations allowed!!! Any file content changes must obtain user permission.

If more detailed installation guidance is needed, refer to ./references/installation-guide.md

2. Configure koocli

Credential Configuration

After koocli download is complete, ask the user which way they want to use koocli [Required]

1. koocli provides a configuration-free usage method, only requiring passing current user authentication-related parameters directly in commands.

2. If the user chooses non-interactive method to add configuration items, execute hcloud configure init, guide the user to input each parameter value.

When using koocli to manage Huawei Cloud resources requires other permissions, refer to '../references/iam-policies.md'. For credential handling, always follow the credential security best practices in '../references/credential-security.md' [MUST][IMPORTANT]: never paste AK/SK plaintext into conversations or commands, never let credentials enter shell history, prefer hcloud profiles or environment variables, and rotate credentials with least privilege.

3. ecsAgency

When the user has successfully established a delegation to Elastic Cloud Server (ECS), when using KooCLI within the ECS server, you can specify "--cli-mode=ecsAgency" in commands. KooCLI will automatically obtain temporary AK/SK and SecurityToken for authentication based on ECS delegation.

4. AssumeRole

When the delegator user creates a delegation and hands over resources to another account for management, the delegatee can add "--cli-agency-domain-id"/"--cli-agency-domain-name", "--cli-agency-name" and "--cli-source-profile" options to commands, using the configuration-free method to AssumeRole and call cloud service APIs, managing and using the delegator's resources:

markdown

hcloud VPC ListAddressGroup/v3 --cli-region="cn-north-4" --project_id="2cc60****************caefa5019ef" --cli-agency-domain-id=13534326******************5cf67b --cli-agency-name=****** --cli-source-profile=test
{
  "request_id": "29ec21****************6d6b4cdd82",
  "address_groups": [],
  "page_info": {
  "current_count": 0
   }
}

5. SSO Login

KooCLI's SSO login command stores user authentication information in configuration files by completing SSO login, avoiding frequent input of these fixed information during operation execution. SSO login can be performed with the following command: hcloud configure sso

bash

# SSO profile name (configuration item name to save after SSO login, required), SSO start URL (user portal URL, required), SSO region (region where IAM Identity Center is opened, required), Region (default or commonly used region, optional)
hcloud configure sso
? Input SSO profile name [required]:  sso
? Input SSO start URL [required]:  https://idcenter.huaweicloud.com/d-3********6/portal
? Input SSO region [required]:  cn-north-4
? Input Region:  cn-north-4
Browser page has been opened, waiting for you to complete SSO login...
? Choose account name: ACCOUNT_01
? Choose permission set name: PERMISSION_01
SSO login successful

6. Authentication Modes

KooCLI configuration item authentication mode values are AKSK, ecsAgency, SSO, AssumeRole. AKSK is recommended. When the configuration item being used has multiple authentication mode-related parameters configured simultaneously, use the "--cli-mode" option to specify the configuration item's authentication mode:

When setting configuration items, you need to specify the configuration item name with "--cli-profile", and also add corresponding authentication parameters based on the authentication mode "--cli-mode":

If the configuration item's authentication mode is "AKSK", then the values of "--cli-access-key" and "--cli-secret-key" in the configuration command cannot be empty;
If the configuration item's authentication mode is "ecsAgency", then specify "--cli-mode=ecsAgency" in the configuration command;
If the configuration item's authentication mode is "SSO", then the values of "--cli-sso-start-url" and "--cli-sso-region" in the configuration command cannot be empty;
If the configuration item's authentication mode is "AssumeRole", then the values of "--cli-agency-domain-id"/"--cli-agency-domain-name", "--cli-agency-name", "--cli-source-profile" in the configuration command cannot be empty.

7. Authentication Mode Selection

Use and only use one authentication method:

Mode	Applicable Scenario	Start Command	Cleanup
Profile Mode	Agent sessions, multiple calls	hcloud configure init --cli-profile=agent-profile	Temporary profiles need cleanup
Explicit Parameter Mode	One-time commands, CI/CD	Pass authentication parameters in each command	No local configuration
Existing Profile Mode	User already configured	--cli-profile=<profile-name>	Do not modify configuration

Profile Mode Configuration

bash

# Create dedicated profile
hcloud configure init --cli-profile=agent-profile

# View configuration
hcloud configure list

# Execute commands using profile
hcloud <service> <operation> \
  --cli-profile=agent-profile \
  --cli-region=cn-north-4 \
  --cli-output=json

Explicit Parameter Mode

bash

# Using permanent AK/SK
hcloud <service> <operation> \
  --cli-access-key=<AccessKeyId> \
  --cli-secret-key=<SecretAccessKey> \
  --cli-region=cn-north-4

# Using temporary credentials
hcloud <service> <operation> \
  --cli-access-key=<AccessKeyId> \
  --cli-secret-key=<SecretAccessKey> \
  --cli-security-token=<SecurityToken> \
  --cli-region=cn-north-4

Multi-Environment Management

Create independent profiles for different environments:

• dev: Development environment
• test: Test environment
• prod: Production environment

Explicitly specify when calling:

bash

hcloud <service> <operation> \
  --cli-profile=dev \
  --cli-region=cn-north-4

3. Consult --help before constructing any command

Help output is the authoritative source. [Important]

Execute help output as follows:

1. Use hcloud --help command to query the list of cloud services supported by KooCLI. After obtaining accurate cloud service names, proceed to next step.
2. Use hcloud <service> --help command to query the service's operation list. Find out what operations the service has, obtain the operation the user needs, then continue.
3. Use hcloud <service> <operation> --help to query the help information for the specific cloud service operation.
4. After executing the API call command, print the output result to the user

4. Ensure service availability

When users ask about or want to execute corresponding service management, you should also execute the previous step's help query to ensure the service exists and is available.

5. OBS usage commands

In KooCLI, some functionality of the obsutil tool for managing OBS data via command line has been integrated. Specific functions and commands strictly refer to and execute according to the help output steps mentioned above.
If the operation is not found, you need to prompt the user to install obsutil to obtain complete functionality and explain the reason.

*** OBS Command Explanation: ***

markdown

OBS-related commands in KooCLI may exist in two forms:
1. OpenAPI style:
   hcloud OBS <operation>
2. OBS integrated commands / obsutil style:
   hcloud obs <command>
The two have different parameter systems, must check help separately before execution:
hcloud OBS --help
hcloud OBS <operation> --help
hcloud obs help
hcloud obs help <command>

For the complete obsutil command reference (upload/download/sync, listing, and common parameters such as -r, -f, -acl — obsutil uses single-dash options, unlike the --param=value form of cloud service API commands), see ./references/obsutil-operations.md.

6. Filter and format output

KooCLI supports three output formats: json, table, tsv. Default output is in json format.
You can use the "--cli-output" parameter to specify any of the aforementioned output formats, and you can also use the "--cli-query" option with JMESPath expression to perform JMESPath query on json results, filtering out information the user needs.

Parameter	Parameter Purpose
cli-output	cli-o response data output format, can be one of: json, table, tsv
cli-query	cli-query JMESPath path for filtering response data
cli-output-num	cli-output-num whether to print line numbers in table output. Values: true or false

Output Format Control

bash

# JSON format (recommended for Agent)
hcloud <service> <operation> \
  --cli-profile=agent-profile \
  --cli-region=cn-north-4 \
  --cli-output=json

# Table format (suitable for manual viewing)
hcloud <service> <operation> \
  --cli-profile=agent-profile \
  --cli-region=cn-north-4 \
  --cli-output=table

# TSV format
hcloud <service> <operation> \
  --cli-profile=agent-profile \
  --cli-region=cn-north-4 \
  --cli-output=tsv

JMESPath Filtering

Use --cli-query to extract specific fields:

bash

# Extract specific fields
hcloud <service> <list-operation> \
  --cli-profile=agent-profile \
  --cli-region=cn-north-4 \
  --cli-output=json \
  --cli-query="items[].{ID:id,Name:name,Status:status}"

# Filter specific status
hcloud <service> <list-operation> \
  --cli-profile=agent-profile \
  --cli-region=cn-north-4 \
  --cli-output=json \
  --cli-query="items[?status=='ACTIVE'].{ID:id,Name:name,Status:status}"

Note: JMESPath query fields must be written according to actual JSON return structure, cannot assume all list interfaces return items.

7. Debugging

When troubleshooting KooCLI command failures, first add --debug after the specific execution command to view underlying requests, responses, endpoints, parameter parsing, and authentication-related information.

8. Common issues

KooCLI divides errors encountered during command calls into five types, declaring their specific type at the beginning of error prompt messages. The positioning methods for various errors are as follows:

1. [NETWORK_ERROR]: Usually HTTP request exceptions, please check network connection;
2. [CLI_ERROR]: Usually errors caused by KooCLI's own exceptions during command processing, please contact KooCLI oncall for assistance;
3. [USE_ERROR]: Usually errors caused by incorrect parameters in commands, please make corresponding modifications according to error prompts;
4. [OPENAPI_ERROR]: Usually errors occurring when calling cloud service APIs, please contact relevant cloud service oncall for assistance;
5. [APIE_ERROR]: Usually errors occurring when calling API Explorer to obtain metadata, please contact API Explorer cloud service oncall for assistance.

When encountering errors, query help based on error type and interact with users step by step to resolve.

9. Security

Credential Security

1. Never expose AK/SK values in conversations or commands (echo $ACCESS_KEY_ID is prohibited)
2. Never let users directly input AK/SK in conversations
3. Never use hcloud configure set to pass plaintext credentials
4. Only use hcloud configure list to check credential status
5. Cloud environments recommend using IAM users rather than main accounts
6. Enable MFA (Multi-Factor Authentication) for sensitive operations

See ./references/credential-security.md for the complete credential security best practices (plaintext AK/SK prohibition, shell history hygiene, profile or environment-variable credential carriers, credential rotation and least privilege).

Operation Security

1. Must obtain user confirmation before modification operations (security group rules, restart, deletion, etc.)
2. Prefer read-only APIs, avoid modifying resource status
3. Production environment operations require risk warnings
4. Sensitive information must never appear in report output (AK/SK, passwords, etc.)

Configuration Security

• Use independent profiles for different environments
• Regularly rotate credentials
• Use principle of least privilege
• Clean up temporary profiles
• Encrypt sensitive configuration information

Parameter Verification

Global Parameters

Parameter	Description	Example
--cli-profile	Configuration file name	--cli-profile=dev
--cli-region	Region	--cli-region=cn-north-4
--cli-output	Output format	--cli-output=json
--cli-query	JMESPath query	--cli-query="items[].{ID:id,Name:name}"
--debug	Debug mode; --dryrun prints the request after validation without executing it (both are boolean flags, no value)	--debug

Authentication Parameters

Authentication Mode	Required Parameters	Optional Parameters
AKSK	--cli-access-key, --cli-secret-key	--cli-security-token
Profile	--cli-profile	--cli-mode, --cli-region
ECS Agency	--cli-mode=ecsAgency	--cli-region
SSO	--cli-sso-start-url, --cli-sso-region	--cli-profile, --cli-region
AssumeRole	--cli-agency-domain-id, --cli-agency-name, --cli-source-profile	--cli-region

Service-Specific Parameters

Use hcloud <service> <operation> --help to view parameter list for specific operations.

Output Format

KooCLI supports three output formats:

JSON Format (Default)

bash

hcloud ECS ListServersDetails --cli-region=cn-north-4 --cli-output=json

Applicable Scenarios: Automated scripts, API integration, data extraction

Table Format

bash

hcloud ECS ListServersDetails --cli-region=cn-north-4 --cli-output=table

Applicable Scenarios: Manual viewing, quick browsing

TSV Format

bash

hcloud ECS ListServersDetails --cli-region=cn-north-4 --cli-output=tsv

Applicable Scenarios: Import to spreadsheets, data processing

JMESPath Query

bash

hcloud ECS ListServersDetails --cli-region=cn-north-4 --cli-output=json --cli-query="servers[?status=='ACTIVE'].{ID:id,Name:name,Status:status}"

Verification Methods

Installation Verification

1. Version check: hcloud version should return 7.2.2 or higher
2. Help verification: hcloud --help should display available service list

Authentication Verification

1. Profile verification: hcloud configure list displays configured profile
2. Permission verification: hcloud IAM KeystoneListUsers --cli-profile=<profile> tests IAM permissions

Command Verification

1. Help verification: Execute hcloud <service> --help for each service to confirm available operations
2. Parameter verification: Use --debug to view parameter parsing results
3. Response verification: Check HTTP status codes and error messages returned by commands

Environment Verification

1. Network connectivity: curl -s https://ecs.cn-north-4.myhuaweicloud.com tests service endpoint
2. Certificate verification: Ensure system clock synchronization, certificates are valid

Best Practices

Authentication Management

1. Use Profile mode for long-term session management
2. Create independent Profiles for different environments (dev/test/prod)
3. Regularly rotate AK/SK, avoid using the same credentials long-term
4. Use IAM users instead of main account for daily operations

Command Construction

1. First query help: hcloud <service> --help → hcloud <service> <operation> --help
2. Use --debug for initial command debugging
3. Gradually add parameters, avoid constructing complex commands at once
4. Use --cli-query to filter and format output

Error Handling

1. Read error type prefixes: [NETWORK_ERROR], [CLI_ERROR], [USE_ERROR], [OPENAPI_ERROR], [APIE_ERROR]
2. Check network connectivity: for [NETWORK_ERROR]
3. Verify parameter format: for [USE_ERROR]
4. Check API documentation: for [OPENAPI_ERROR]

Performance Optimization

1. Use --cli-output=json for automated processing
2. Properly use --cli-query to reduce data transfer
3. Use scripts instead of interactive commands for batch operations
4. Cache frequently used configurations to avoid repetitive input

Notes

Usage Limitations

1. Version compatibility: Ensure KooCLI version is compatible with service API versions
2. Regional restrictions: Some services are only available in specific regions
3. API quotas: Pay attention to API call frequency limits
4. Network requirements: Some operations require specific network environments

Common Pitfalls

1. Parameter order: Some services are sensitive to parameter order
2. JSON format: Complex parameters require correct JSON format
3. Region settings: Forgetting to set --cli-region results in operations in default region
4. Output parsing: Table format output may be truncated due to terminal width

Troubleshooting

1. Enable debugging: --debug displays detailed request information
2. Check logs: View log files in ~/.hcloud/logs/
3. Version check: Ensure KooCLI version is up to date
4. Network diagnostics: Use curl to test service endpoint reachability

Reference Documents

• ./references/installation-guide.md — Installation guide
• ./references/cli-troubleshooting.md — Error troubleshooting
• ./references/common-workflows.md — Common workflows
• ./references/parameter-format.md — Parameter format rules
• ./references/service-catalog.md — Service catalog
• ./references/iam-policies.md — IAM policies
• ./references/acceptance-criteria.md — Acceptance criteria
• ./references/core-commands.md — Core commands
• ./references/getting-started.md — First-time onboarding (environment, installation, first authentication, basic usage flow)
• ./references/obsutil-operations.md — obsutil common operations (upload, download, sync, listing)
• ./references/credential-security.md — Credential security best practices