diff --git a/README.md b/README.md index 6124be8..080593d 100644 --- a/README.md +++ b/README.md @@ -44,9 +44,9 @@ By default skills land under the agent's standard directory (`~/.claude/skills/` ### `excloud-cli` -Safe end-to-end control of Excloud resources through the `exc` CLI. Covers compute (create / inspect / resize / restart / terminate, delete protection, exec / scp / console), networking (subnets, public IPv4, security groups and rules/bindings), volumes and snapshots, SSH keys, Kubernetes (clusters, workers, kubeconfig fetch / merge), object storage buckets (bucket lifecycle, object copy/sync/delete/share, access keys, multipart uploads), org secrets (path-addressed encrypted store with versions, audited reveals, value-source flags, reveal output combinators), IAM (accounts, service accounts, API keys, policies), billing details and pre-flight cost estimates, quota, serial console logs, and metrics. +Safe end-to-end control of Excloud resources through the `exc` CLI. Covers compute (create / inspect / resize / restart / terminate, delete protection, exec / scp / console), networking (subnets, public IPv4, security groups and rules/bindings), volumes and snapshots, SSH keys, Kubernetes (clusters, workers, kubeconfig fetch / merge), object storage buckets (bucket lifecycle, object copy/sync/delete/share, access keys, multipart uploads), org secrets (path-addressed encrypted store with versions, audited reveals, value-source flags, reveal output combinators), IAM (accounts, service accounts, API keys, policies), billing details, pre-flight cost estimates, cost explorer triage, quota, serial console logs, and metrics. -**Use when:** the user asks to plan or run `exc` commands, provision / introspect / tear down VMs, estimate VM costs before creation or resizing, attach a public IP, adjust a security group, pull a kubeconfig, manage buckets or S3 access keys, save / reveal / rotate an org secret, debug a stuck boot via serial logs, or exec / scp against a VM. +**Use when:** the user asks to plan or run `exc` commands, provision / introspect / tear down VMs, estimate VM costs before creation or resizing, investigate what is costing money, attach a public IP, adjust a security group, pull a kubeconfig, manage buckets or S3 access keys, save / reveal / rotate an org secret, debug a stuck boot via serial logs, or exec / scp against a VM. **Key guidance the skill encodes:** diff --git a/skills/excloud-cli/SKILL.md b/skills/excloud-cli/SKILL.md index b63f86c..2eee8cf 100644 --- a/skills/excloud-cli/SKILL.md +++ b/skills/excloud-cli/SKILL.md @@ -64,6 +64,7 @@ The skill does _not_ hard-code IDs, instance type names, image IDs, subnet IDs, - `exc securitygroup list` + `exc securitygroup rule list --security_group_id ` + `exc securitygroup binding list --security_group_id ` (or `--interface_id `) — confirm what a SG allows and where it's bound before relying on it. - `exc compute publicip list` / `exc compute key list` / `exc compute volume list` / `exc compute snapshot list` — authoritative inventories for each resource type. - `exc billing estimate --help` + `exc compute instancetype list` — shape a pre-flight monthly cost estimate before creating or scaling VMs. Instance type names and pricing inputs change; verify them rather than hard-coding. +- `exc billing costs --help` — read-only cost explorer for "what is costing money?" investigations. Use it before guessing from resource inventories; group by resource type first, then drill into resource ids/names. - `exc buckets list` / `exc buckets get ` / `exc buckets usage` — authoritative object-storage inventory and quota checks. - `exc buckets objects list [--prefix ] [--all]` — discover keys before copy/delete/share operations. - `exc buckets keys list` and `exc buckets multipart list ` — discover S3 access keys and abandoned multipart uploads before managing them. @@ -409,6 +410,30 @@ Notes: - Output is a human-readable cost table with component rows (`Instance`, optional `Storage`, optional `Network`) and `TOTAL` / hourly summary rows. It is for display and comparison, not JSON scripting. - If the service has no price data for an instance type, the command prints `No pricing data found for instance type: `. +### Billing cost explorer + +Use `exc billing costs` for read-only spend triage, especially when the user asks what is costing money or where spend is coming from. Always run `exc billing costs --help` first; this command is UX-focused and has aliases `cost`, `spend`, and `cost-explorer`. + +Good starting points: + +```bash +exc billing costs +exc billing costs --period 7d +exc billing costs --period last-month +exc billing costs --from --to --by resource-type +exc billing costs --by resource-id --resource-type ONDEMAND_INSTANCE --top 20 +exc billing costs --json +``` + +Notes: + +- Default period is month-to-date, grouped by `resource-type`, sorted by cost descending, top 10 rows. +- `--period` accepts values like `mtd`, `last-month`, `7d`, `30d`, and `6mo`; use explicit `--from` / `--to` when the user gives exact dates. +- `--by` accepts `resource-type`, `resource-id`, or `resource-name`. Start with `resource-type` for a summary, then drill down with `resource-id` or `resource-name`. +- Filter with `--resource-type`, `--resource-id`, and `--resource-name`; comma-separated values are accepted by Cobra string-slice flags. +- `--granularity` accepts `auto`, `hourly`, `daily`, or `monthly`. Hourly is limited to about 7 days, daily to about 31 days, and monthly to about 6 months. +- Table output includes `TOTAL`, cost, share percentage, and a best-effort usage display. Use `--json` for scripts. + ## Config and misc - `exc me` / `exc version` / `exc completion ` @@ -419,10 +444,10 @@ Notes: Every command either prints a column table (or TSV) or prints JSON — no command should print raw Go-struct dumps anymore. Both shapes are machine-parseable; pick your tool accordingly. -- **Column tables / TSV** (awk / `cut` / `awk -F\t` friendly): `compute list`, `compute get`, `compute create`, `compute terminate` (TSV `vm_id\tstate`), `compute instancetype list` / `capacity`, `compute image list`, `compute subnet list`, `compute volume list`, `compute volume get`, `compute snapshot list`, `compute publicip list`, `compute key list`, `securitygroup list` / `rule list` / `binding list`, `org list`, `account list`, `apikey list`, `policy list`, `billing estimate`, `config list`, `compute seriallogs`, `buckets list`, `buckets ls`, `buckets objects list`, `buckets keys list`, `buckets multipart list`. +- **Column tables / TSV** (awk / `cut` / `awk -F\t` friendly): `compute list`, `compute get`, `compute create`, `compute terminate` (TSV `vm_id\tstate`), `compute instancetype list` / `capacity`, `compute image list`, `compute subnet list`, `compute volume list`, `compute volume get`, `compute snapshot list`, `compute publicip list`, `compute key list`, `securitygroup list` / `rule list` / `binding list`, `org list`, `account list`, `apikey list`, `policy list`, `billing estimate`, `billing costs`, `config list`, `compute seriallogs`, `buckets list`, `buckets ls`, `buckets objects list`, `buckets keys list`, `buckets multipart list`. - **JSON** (pipe through `jq`): `me`, `quota`, `billing get`, `compute health` (`{"raw":"OK"}`), `k8s health`, `compute subnet get`, `compute publicip get`, `compute key get`, `securitygroup get`, `compute metrics`, `compute connect`, `serviceaccount list`, `compute protect`, `compute unprotect`, `compute rename`, `k8s cluster kubeconfig get` (raw kubeconfig YAML, not JSON-wrapped), `buckets get`, `buckets usage`, `buckets keys create`, multipart create/uploadpart/complete/abort, and the inline `kubeconfig` field inside the JSON response from `k8s cluster create` when `-o` is not set. -Many bucket list/delete commands have explicit `--json`; use it for scripts instead of scraping tables. `buckets objects presign` intentionally prints only the URL so it can be piped to tools like `pbcopy`. +Many bucket list/delete commands and `billing costs` have explicit `--json`; use it for scripts instead of scraping tables. `buckets objects presign` intentionally prints only the URL so it can be piped to tools like `pbcopy`. Before scripting heavy logic against a command, run it once and check the shape. The split between "table" and "JSON" is not always guessable — lists tend to be tables, getters tend to be JSON, but verify.