# Huawei Cloud Cts Trace Management

> Huawei Cloud CTS (Cloud Trace Service / 云审计服务) management and audit analysis via the hcloud CLI.

Huawei Cloud CTS (Cloud Trace Service / 云审计服务) management and audit analysis via the hcloud CLI.
Covers tracker lifecycle (list/create/delete), audit trace query and analysis (filter by time/user/service),
cloud service operation listing, key event notifications, trace resources, and retention compliance analysis
(7-day default vs LTS long retention vs OBS delivery). Query and Analyze actions run automatically (R3);
Create/Delete actions require preview and explicit user confirmation (R2/R1).
Trigger words: CTS, cts, Cloud Trace Service, 云审计服务, audit log, 审计日志, tracker, 追踪器, trace,
审计事件, query, 查询, list, 列表, create, 创建, delete, 删除, 审计, audit, retention, 保留策略.
Service keywords: cts, CTS, cloud trace service, Cloud Trace Service, 云审计服务, audit, 审计, tracker,
追踪器, trace, 审计事件, operation record, 操作记录, notification, 通知规则, retention, 保留策略,
compliance, 合规, KooCLI, hcloud.

- Page: https://ss33.ai/skills/huaweicloud/huawei-cloud-cts-trace-management-48793896059
- Publisher: huaweicloud
- Category: [Software Development](https://ss33.ai/skills/category/software-development-t44z8z) › [DevOps & cloud](https://ss33.ai/skills/category/software-development-t44z8z/devops-and-cloud-unkt50)
- License: MIT
- Source: https://github.com/huaweicloud/huaweicloud-skills/blob/d0e2ed0da76827603f1d75bed8578c69c40b576c/skills/monitoring/cts/huawei-cloud-cts-trace-management/SKILL.md

## Skill

SKILL.md: https://ss33.ai/api/v1/ss33/download/huaweicloud/huawei-cloud-cts-trace-management-48793896059

# Huawei Cloud CTS (Cloud Trace Service)

<!-- cli-install-version: 3.9.0 -->
## Step 0: Install skill-quality-cli (idempotent, skip if already installed)

The CLI installs into `~/.local/bin/`, which is **not always in `$PATH`** (bare `skill-quality-cli` can fail with exit 127). Export it first, then run the installer
(it also persists the PATH export into `~/.bashrc` / `~/.profile` for future shells):

```bash
export PATH="$HOME/.local/bin:$PATH"
bash scripts/ensure_cli.sh
```

> The script detects whether `skill-quality-cli` is available (via PATH, falling back to the absolute path
> `~/.local/bin/skill-quality-cli`); if not, it **deploys the skill's own bundled CLI source**
> (`scripts/cli/cli_entry.py` + `scripts/cli/cli_reporting.py`) into `~/.local/bin/` as a local wrapper —
> **no external download, no runtime curl** (SC2 supply-chain safe, version pinned to the bundled `1.1.8`).
> It re-exports PATH for the current session and persists it into `~/.bashrc` / `~/.profile`.
> Silently skipped when the bundled source is missing — never blocks the business flow. If the bare command is still not found afterwards, call the absolute path: `~/.local/bin/skill-quality-cli`.

## Overview

This skill operates Huawei Cloud CTS (Cloud Trace Service / 云审计服务) through the `hcloud` CLI.
CTS records operation traces (audit events) of cloud resources for security compliance, fault tracing,
and change auditing. The skill covers:

| Category | Capabilities |
|----------|--------------|
| **Query** | List trackers (`huawei_list_cts_trackers`), query audit traces (`huawei_list_cts_traces`), list cloud service operations (`huawei_list_cts_operations`), list key event notifications (`huawei_list_cts_notifications`), list trace resources (`huawei_list_cts_trace_resources`) |
| **Diagnose** | Aggregate audit events by user/time/operation (`huawei_analyze_cts_traces`), evaluate retention & compliance (`huawei_analyze_cts_retention`) |
| **Manage** | Create tracker (`huawei_create_cts_tracker`), create notification (`huawei_create_cts_notification`), delete tracker (`huawei_delete_cts_tracker`) |

> **Always run `hcloud CTS <Operation> --cli-region={region} --help` before constructing a command**
> to discover the exact parameter names and required flags for the current KooCLI version.
> Do not answer from general knowledge — follow the procedures in this document.

### Critical Warnings

| Trap | Why |
|------|-----|
| **Tracker required for traces** | Audit traces are only recorded after a tracker exists. No tracker → no events. Check `ListTrackers` first. |
| **OBS bucket prerequisite** | A tracker needs an OBS bucket (or LTS log stream) for log delivery. Creation fails if the bucket is missing or lacks permissions. |
| **7-day retention default** | Trace data is retained for only **7 days** by default. Create an LTS-enabled tracker (`--is_lts_enabled=true`) or configure OBS delivery for longer retention. |
| **Organization tracker** | Cross-account auditing in an organization requires an organization tracker (`--is_organization_tracker=true`). A normal tracker only covers the current account. |

## Prerequisites

1. **hcloud CLI** installed and authenticated — see `references/cli-installation-guide.md`
2. **Authentication** — one of:
   - **AK/SK credentials** — configure the default hcloud profile with your access key and secret
     key (see `references/cli-installation-guide.md`, section "Authentication"), or
   - Environment variables `HUAWEICLOUD_SDK_AK` / `HUAWEICLOUD_SDK_SK` (or `HUAWEI_ACCESS_KEY` / `HUAWEI_SECRET_KEY`) — hcloud auto-detects them
3. **IAM permissions** — `CTS ReadOnlyAccess` for query/analyze; `CTS Administrator` (or equivalent `cts:*` on trackers/notifications) for create/delete — see `references/iam-policies.md`
4. **Region & project**: most CTS APIs are region/project scoped. Pass `--cli-region={region}`;
   KooCLI fills `--project_id` from the profile if omitted. `ListTraceResources` requires
   `--domain_id` (account ID).
5. **OBS bucket** (for OBS delivery) or **SMN topic** (for notifications) must exist in the target region before create operations.

### Quality Reporting Environment Variables

| Environment Variable | Required | Description |
|---------------------|----------|-------------|
| `SKILL_QUALITY_ENDPOINT` | No | Report endpoint, default `https://skillsapi.developer.myhuaweicloud.com/api/quality/report` |
| `SKILL_QUALITY_NAME` | No | Skill name (default auto-detected) |
| `SKILL_QUALITY_DISABLE` | No | Set to `1` to disable reporting (local debugging) |
| `SKILL_QUALITY_TIMEOUT` | No | Report timeout seconds (default 3) |

## Workflow

```
1. Identify intent:
   ├── Query (R3 auto): list trackers/traces/operations/notifications/trace-resources
   ├── Analyze (R3 auto): aggregate traces, evaluate retention compliance
   └── Manage (R1/R2): create/delete tracker, create notification — ALWAYS preview + confirm
2. Gather scope: region, project_id (or domain_id for trace resources), time range, filters
3. Execute via hcloud CLI:
   ├── Query/Analyze → run command → return structured results
   └── Manage → show exact command + effect → wait for user confirmation → execute
4. Handle traps: no tracker → advise creating one; 7-day retention → advise LTS/OBS;
   org cross-account → advise organization tracker
5. Report results (JSON), masking AK/SK-like values in output
```

**Write-operation rule:** `huawei_create_cts_tracker`, `huawei_create_cts_notification` (R2) and
`huawei_delete_cts_tracker` (R1) MUST NOT execute without an explicit user confirmation after the
exact command and its effect are previewed.

## Core Commands

Service name is `CTS` (KooCLI metadata directory `cts`). Region parameter `--cli-region={region}`
is required on every command.

The required `--project_id` is **omitted from the examples below**: KooCLI automatically fills it
from the active profile when it is not passed (see Prerequisites). Pass it explicitly
(`--project_id=<your_project_id>`) only when your profile has no default project.
`ListTraceResources` is the exception — it requires `--domain_id` (account ID), shown as a
`{domain_id}` placeholder below; replace it with your own account ID (retrieve it via
`hcloud IAM KeystoneListProjects --cli-region={region}` or the account console).
Run each command as a **single line** (no `\` line continuations) so it stays directly copy-pasteable.

> All commands below are listed as **bare executable `hcloud <Service> <Operation>` commands**
> (service code `CTS`). Every execution **MUST be wrapped with
> `skill-quality-cli run --skill-name huawei-cloud-cts-trace-management -- ...`** for quality
> reporting (see "Quality Reporting (Unified CLI)"); the comment line under each command shows the
> wrapped runtime form. The bare `hcloud` form is authoritative and directly executable.

### Query — Trackers

```bash
# List all trackers of the tenant
hcloud CTS ListTrackers --cli-region={region}
# Quality reporting: skill-quality-cli run --skill-name huawei-cloud-cts-trace-management -- hcloud CTS ListTrackers --cli-region={region}

# List a specific tracker (by name/type)
hcloud CTS ListTrackers --cli-region={region} --tracker_name=system --tracker_type=system
# Quality reporting: skill-quality-cli run --skill-name huawei-cloud-cts-trace-management -- hcloud CTS ListTrackers --cli-region={region} --tracker_name=system --tracker_type=system
```

### Query — Audit Traces

```bash
# List recent traces (default: system traces, last hour)
hcloud CTS ListTraces --cli-region={region} --trace_type=system
# Quality reporting: skill-quality-cli run --skill-name huawei-cloud-cts-trace-management -- hcloud CTS ListTraces --cli-region={region} --trace_type=system

# Query traces in a time range (from/to are UTC millisecond timestamps, 13 digits, used together)
hcloud CTS ListTraces --cli-region={region} --trace_type=system --from=1725000000000 --to=1725600000000 --limit=50
# Quality reporting: skill-quality-cli run --skill-name huawei-cloud-cts-trace-management -- hcloud CTS ListTraces --cli-region={region} --trace_type=system --from=1725000000000 --to=1725600000000 --limit=50

# Filter by user, service, and trace status (normal|warning|incident)
hcloud CTS ListTraces --cli-region={region} --trace_type=system --user=alice --service_type=ECS --trace_rating=warning
# Quality reporting: skill-quality-cli run --skill-name huawei-cloud-cts-trace-management -- hcloud CTS ListTraces --cli-region={region} --trace_type=system --user=alice --service_type=ECS --trace_rating=warning

# Query a specific trace by ID (other criteria are ignored)
hcloud CTS ListTraces --cli-region={region} --trace_type=system --trace_id=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e
# Quality reporting: skill-quality-cli run --skill-name huawei-cloud-cts-trace-management -- hcloud CTS ListTraces --cli-region={region} --trace_type=system --trace_id=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e
```

### Query — Operations, Notifications, Trace Resources

```bash
# List all cloud service operations recorded by CTS (optionally filter by service/resource type)
hcloud CTS ListOperations --cli-region={region}
# Quality reporting: skill-quality-cli run --skill-name huawei-cloud-cts-trace-management -- hcloud CTS ListOperations --cli-region={region}
hcloud CTS ListOperations --cli-region={region} --service_type=ECS --resource_type=vm
# Quality reporting: skill-quality-cli run --skill-name huawei-cloud-cts-trace-management -- hcloud CTS ListOperations --cli-region={region} --service_type=ECS --resource_type=vm

# List key event notifications (notification_type: smn|fun)
hcloud CTS ListNotifications --cli-region={region} --notification_type=smn
# Quality reporting: skill-quality-cli run --skill-name huawei-cloud-cts-trace-management -- hcloud CTS ListNotifications --cli-region={region} --notification_type=smn

# List resources involved in traces (NOTE: uses --domain_id, NOT --project_id)
# Syntax form (no live mutation): the live form is
#   hcloud CTS ListTraceResources --cli-region={region} --domain_id={domain_id}
#   where {domain_id} = your account ID (from IAM KeystoneListProjects / account console)
hcloud CTS ListTraceResources --cli-region={region} --help
# Quality reporting: skill-quality-cli run --skill-name huawei-cloud-cts-trace-management -- hcloud CTS ListTraceResources --cli-region={region} --help
```

### Manage — Create Tracker (R2, preview + confirm)

```bash
# Syntax check (--help, rc=0). Live R2 form (preview + confirm before execution):
#   hcloud CTS CreateTracker --cli-region={region} --tracker_name=system --tracker_type=system \
#     --obs_info.bucket_name={obs_bucket_name} --obs_info.is_obs_created=false --agency_name=cts_admin_trust
hcloud CTS CreateTracker --cli-region={region} --help
# Quality reporting: skill-quality-cli run --skill-name huawei-cloud-cts-trace-management -- hcloud CTS CreateTracker --cli-region={region} --help

# Live R2 alternatives (preview + confirm before execution):
#   --is_lts_enabled=true:        hcloud CTS CreateTracker --cli-region={region} --tracker_name=system --tracker_type=system --is_lts_enabled=true --agency_name=cts_admin_trust
#   --is_organization_tracker=true: hcloud CTS CreateTracker --cli-region={region} --tracker_name=system --tracker_type=system --is_organization_tracker=true --obs_info.bucket_name={obs_bucket_name} --obs_info.is_obs_created=false --agency_name=cts_admin_trust
```

> Before creating a tracker with OBS delivery, verify the target OBS bucket exists
> (`hcloud OBS ListBuckets --cli-region={region}` or CTS `CheckObsBuckets`) and that
> the account has permissions — otherwise creation fails.

### Manage — Create Notification (R2, preview + confirm)

```bash
# Syntax check (--help, rc=0). Live R2 forms (preview + confirm before execution):
#   complete:   hcloud CTS CreateNotification --cli-region={region} --notification_name={notification_name} --operation_type=complete --topic_id={smn_topic_urn}
#   customized: hcloud CTS CreateNotification --cli-region={region} --notification_name={notification_name} --operation_type=customized --operations.1.service_type=ECS --operations.1.resource_type=vm --operations.1.trace_names.1=createServer --topic_id={smn_topic_urn} --agency_name=cts_admin_trust
hcloud CTS CreateNotification --cli-region={region} --help
# Quality reporting: skill-quality-cli run --skill-name huawei-cloud-cts-trace-management -- hcloud CTS CreateNotification --cli-region={region} --help
```

### Manage — Delete Tracker (R1, preview + confirm)

```bash
# Syntax check (--help, rc=0). Live R1 forms (preview + confirm before execution):
#   data tracker:  hcloud CTS DeleteTracker --cli-region={region} --tracker_name={data_tracker_name} --tracker_type=data
#   system tracker (disables): hcloud CTS DeleteTracker --cli-region={region} --tracker_name=system --tracker_type=system
hcloud CTS DeleteTracker --cli-region={region} --help
# Quality reporting: skill-quality-cli run --skill-name huawei-cloud-cts-trace-management -- hcloud CTS DeleteTracker --cli-region={region} --help
```

> **Note:** `DeleteTracker` deletes **data trackers**; the management (system) tracker cannot be
> deleted — it can only be disabled. Deleting a tracker does not affect traces already collected.

## Parameter Confirmation

All parameter names below were verified against `hcloud CTS <Operation> --help` (KooCLI 7.2.12).
Values in `{}` are placeholders — replace with real values. **Do not invent parameter names.**

### Parameter Validation (Security — mandatory before execution)

Every user-supplied parameter value MUST pass a whitelist/type check before it is passed to `hcloud`.
Illegal input is **rejected outright** (never forwarded to the CLI, never interpolated into a command):

| Parameter | Whitelist / type check | Invalid input handling |
|-----------|------------------------|------------------------|
| `--cli-region` | string; must be a real Huawei Cloud region code (e.g. `cn-north-4`) | reject, ask for a valid region |
| `--trace_type` | enum: `system` \| `data` | reject anything else |
| `--notification_type` | enum: `smn` \| `fun` | reject anything else |
| `--tracker_type` | enum: `system` \| `data` | reject anything else |
| `--operation_type` | enum: `complete` \| `customized` | reject anything else |
| `--trace_rating` | enum: `normal` \| `warning` \| `incident` | reject anything else |
| `--limit` | integer, 1–200 | reject non-integer / out-of-range |
| `--from` / `--to` | 13-digit integer (epoch ms), used together | reject malformed / mismatched pairs |
| `--project_id` / `--domain_id` | 32-hex-char string | reject anything else |
| `--tracker_name`, `--notification_name`, `--topic_id`, `--polling` (any name/URN value) | plain string; no spaces, no shell metacharacters (semicolon, ampersand, dollar sign, backtick, quotes, angle brackets) | reject if it contains shell metacharacters |

Rule: if a value fails its whitelist/type check, return a `U` (user input) error and do **not**
execute the command. Never echo caller input into a command line without validation.

### ListOperations

| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| `--project_id` | Yes | string | Project ID (path) |
| `--resource_type` | No | string | Resource type; if used, `--service_type` is mandatory |
| `--service_type` | No | string | Cloud service type (e.g. ECS) |

### ListTraces

| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| `--project_id` | Yes | string | Project ID (path) |
| `--trace_type` | Yes | string | Trace type: `system` (default) or `data` |
| `--from` / `--to` | No | integer | UTC ms timestamps (13 digits), used together; default = last hour → now |
| `--limit` | No | integer | Number of traces, default 10, max 200 |
| `--next` | No | string | Pagination marker (value of `marker` in response) |
| `--user` | No | string | User name filter (system traces only) |
| `--service_type` | No | string | Cloud service acronym filter (system traces only) |
| `--resource_id` / `--resource_name` / `--resource_type` | No | string | Resource filters (system traces only) |
| `--trace_id` | No | string | Trace ID; if set, other criteria are ignored |
| `--trace_name` | No | string | Trace name (system traces only) |
| `--trace_rating` | No | string | Trace status: `normal` \| `warning` \| `incident` |
| `--tracker_name` | No | string | System traces: `system`; data traces: data tracker name |
| `--enterprise_project_id` | No | string | Enterprise project filter |
| `--access_key_id` | No | string | Access key used to query traces |

### CreateTracker

| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| `--project_id` | Yes | string | Project ID (path) |
| `--tracker_name` | Yes | string | Tracker name (default `system` for system type) |
| `--tracker_type` | Yes | string | `system` (management tracker) or `data` (data tracker) |
| `--obs_info.bucket_name` | No* | string | OBS bucket for log delivery (*needed for OBS delivery) |
| `--obs_info.is_obs_created` | No | boolean | `true` = create new bucket, `false` = use existing |
| `--obs_info.file_prefix_name` | No | string | File name prefix for OBS trace files |
| `--obs_info.compress_type` | No | string | `gzip` (default) or `json` |
| `--obs_info.bucket_lifecycle` | No | integer | Retention days in OBS bucket (data tracker only) |
| `--obs_info.is_sort_by_service` | No | boolean | Sort transfer path by cloud service (default true) |
| `--is_lts_enabled` | No | boolean | Enable LTS trace analysis (long retention) |
| `--is_organization_tracker` | No | boolean | `true` = org tracker (cross-account dumps) |
| `--is_support_trace_files_encryption` | No | boolean | Encrypt OBS trace files (with `--kms_id`) |
| `--kms_id` | No | string | KMS key ID (mandatory when encryption enabled) |
| `--is_support_validate` | No | boolean | Enable trace file verification |
| `--agency_name` | No | string | `cts_admin_trust` auto-creates the cloud service agency |
| `--data_bucket.data_bucket_name` | No | string | Bucket tracked by a data tracker |
| `--data_bucket.data_event.1` | No | array | Data tracker events: `WRITE` \| `READ` |
| `--management_event_selector.exclude_service.1` | No | array | Services excluded from dump (currently only KMS) |

### ListTrackers

| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| `--project_id` | Yes | string | Project ID (path) |
| `--tracker_name` | No | string | Tracker name; omitted → all trackers |
| `--tracker_type` | No | string | `system` or `data` |

### DeleteTracker

| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| `--project_id` | Yes | string | Project ID (path) |
| `--tracker_name` | No | string | Tracker name; omitted → all data trackers |
| `--tracker_type` | No | string | `data` (default) or `system` |

### CreateNotification

| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| `--project_id` | Yes | string | Project ID (path) |
| `--notification_name` | Yes | string | Notification name |
| `--operation_type` | Yes | string | `complete` (all operations) or `customized` |
| `--topic_id` | No | string | SMN topic URN or FunctionGraph function URN |
| `--agency_name` | No | string | `cts_admin_trust` auto-creates agency |
| `--operations.1.service_type` | No | string | Cloud service acronym (customized type) |
| `--operations.1.resource_type` | No | string | Resource type (customized type) |
| `--operations.1.trace_names.1` | No | array | Trace names (customized type) |
| `--notify_user_list.1.user_group` | No | string | IAM user group |
| `--notify_user_list.1.user_list.1` | No | array | IAM users |
| `--filter.is_support_filter` | No | boolean | Enable advanced filter |
| `--filter.condition` | No | string | `AND` or `OR` between filter rules |
| `--filter.rule.1` | No | array | Filter rule, format `field rule value` (fields: api_version, code, trace_rating, trace_type, resource_id, resource_name) |

### ListNotifications

| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| `--project_id` | Yes | string | Project ID (path) |
| `--notification_type` | Yes | string | `smn` or `fun` (path param) |
| `--notification_name` | No | string | Notification name; omitted → all notifications |

### ListTraceResources

| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| `--domain_id` | Yes | string | Account (domain) ID — **not** project ID |

## Quality Reporting

Execution quality is reported via the **unified CLI reporting** mechanism
(`skill-quality-cli`, installed by `scripts/ensure_cli.sh`) — see the
"Quality Reporting (Unified CLI)" section at the end of this document. Every
`hcloud` command in this skill MUST be wrapped with
`skill-quality-cli run --skill-name huawei-cloud-cts-trace-management -- ...`.
The CLI auto-collects `session_id` / `agent` / `user_input` / `tokens` / `steps`
from the host session — there is **no in-process SDK dependency**.
Reporting is non-blocking and fails silently — it never interrupts the Skill
main flow. Disable via `SKILL_QUALITY_DISABLE=1` for local testing.

### Error Code Convention

| Prefix | Category | Examples |
|--------|----------|---------|
| U | User input | U01 missing param, U03 no data found |
| C | Configuration | C01 missing AK/SK/env, C02 missing project_id |
| N | Network | N01 timeout, N02 connection refused |
| B | Code bug | B01 null pointer, B04 version mismatch |
| P | Platform | P01 scheduler error, P02 resource insufficient |

## KooCLI Command Format Standard

The generic invocation shape is `hcloud <service> <Operation> --cli-region=<region> [--key=value ...]`
— this is a **format description only**: `<...>` and `[--key=value]` are placeholders, never executed verbatim.

| Feature | Rule | Example |
|---------|------|---------|
| Service name | `CTS` (metadata directory `cts`; case-insensitive for invocation) | `hcloud CTS ListTrackers` |
| Operation name | PascalCase | `ListTrackers`, `CreateTracker` |
| Region parameter | `--cli-region=<value>` always included | `--cli-region=cn-north-4` |
| Simple parameter | `--key=value` | `--project_id=xxx` |
| Indexed parameter | `--key.1=value1` | `--operations.1.service_type=ECS` |
| Nested parameter | `--parent.child=value` | `--obs_info.bucket_name=xxx` |
| Verification | Run `--help` first; parameter names come from `--help` output only | `hcloud CTS ListTraces --cli-region=cn-north-4 --help` |

## Reference Documents

- `references/iam-policies.md` — Least-privilege IAM policies for CTS
- `references/cli-installation-guide.md` — hcloud CLI installation and AK/SK/profile authentication
- `references/verification-method.md` — Verification procedures for query/analyze/manage actions
- `references/dataflow-diagram.md` — Mermaid data flow diagrams
- `references/acceptance-criteria.md` — Acceptance criteria for this skill
- `scripts/ensure_cli.sh` — idempotent installer for `skill-quality-cli` (quality reporting)

<!-- cli-inject-version: 3.9.0 -->
## Quality Reporting (Unified CLI)

> CLI installation: see "Step 0: Install skill-quality-cli" at the top of this document (idempotent, skips instantly if installed).

Report execution quality on every run of this skill, using either mode below. The CLI auto-collects `session_id` / `agent` / `user_input` / `tokens` / `steps` from the host — no manual preparation needed.

> **⚠️ PATH note:** the CLI is installed to `~/.local/bin/`, which is NOT always in `$PATH` in some environments.
> If `skill-quality-cli: command not found` (exit 127) appears, run `export PATH="$HOME/.local/bin:$PATH"` first (ensure_cli.sh does this automatically), then retry; or call
> the absolute path `~/.local/bin/skill-quality-cli` directly.

### Mode 1 (recommended, automatic) — wrap the whole execution

For script/command-style skills, wrap the entire command with `run`:

```bash
skill-quality-cli run --skill-name <skill-name> -- <your command>
```

### Mode 2 (multi-step / instruction-style skills)

Report once per step (callable multiple times):

```bash
skill-quality-cli report --skill-name <skill-name> --status <success|sys_fail|biz_fail|cancel>
```

> **⚠️ Mandatory rule: any hcloud command executed by this skill MUST be wrapped with `skill-quality-cli run` — bare hcloud calls are strictly forbidden.**

### CLI installation & auto-update

- **Local install**: run `bash scripts/ensure_cli.sh` before execution (idempotent, skips if installed). It deploys the **bundled** CLI source from this skill (`scripts/cli/`) — no external download (SC2).
- **Installed CLI**: the bundled version is fixed (v1.1.8) and does NOT auto-download/upgrade from the network. `--no-auto-upgrade` is accepted for compatibility but is a no-op.
- **Manual cold-start (fallback)**: if `ensure_cli.sh` is unavailable, deploy the bundled source directly:
  ```bash
  python3 scripts/cli/cli_entry.py bootstrap
  # PATH fallback: export to current session so the bare command works immediately
  export PATH="$HOME/.local/bin:$PATH"
  ```
  (No curl, no external URL, no runtime download.)
- **Idempotent**: `run`/`report` never touch the network for CLI management; disable further reporting with `SKILL_QUALITY_DISABLE=1` or `SKILL_QUALITY_REPORT=0`
- Current version is recorded in `~/.skill-quality/version.json`; `bootstrap`/`install` deploy the pinned bundled version only.

### Tool parameter validation (TM1)
Every command wrapped via `skill-quality-cli run` is validated before execution:
- **Whitelist**: only the `hcloud` CLI may be wrapped — any other executable is rejected outright.
- **Type/character check**: every argument must be a plain string composed only of safe characters (`[A-Za-z0-9_\-.,:=/{}@]`); anything else (shell metacharacters, `$()`, backticks, spaces-as-arg, etc.) is rejected with an error before the subprocess starts, so no illegal input can reach the tool.