Skip to content

Commit d769b95

Browse files
committed
docs(cli): correct API-name and validation/conflict-check claims
- filtering.md: account-name resolution uses organizations:DescribeAccount (per-ID + cached), not organizations:ListAccounts. IAM-policy authors granting only ListAccounts on the prior wording would have hit a permission gap. - filtering.md: scope the include/exclude conflict-check note to the three pairs actually validated at startup (regions, instance types, engines) and document that --include-accounts/--exclude-accounts and --include-sp-types/--exclude-sp-types fall through without that check, with exclude winning on overlap. - README.md + purchase-safety.md: drop the "validated as a Go duration string" claim for --idempotency-window; the CLI does not parse the value at startup, only the server-side scheduler does.
1 parent 051bacf commit d769b95

3 files changed

Lines changed: 6 additions & 4 deletions

File tree

‎docs/cli/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ All flags belong to the root command unless noted otherwise.
5353
| `--purchase` | | `false` | Execute real purchases. In the normal cloud-fetch path it must be combined with `--dry-run=false` (`--purchase` alone sets `ActualPurchase=true` but `DryRun` stays `true`, so the run remains a dry run). **Exception:** in `--input-csv` mode `--dry-run` is ignored and `--purchase` alone executes real purchases. See [purchase-safety.md](purchase-safety.md). |
5454
| `--yes` | | `false` | Skip the interactive confirmation prompt. Use with caution in automation. |
5555
| `--audit-log` | | `./cudly-audit.jsonl` | Path to the JSONL audit log file. Written for every recommendation (dry-run and real). See [purchase-safety.md](purchase-safety.md). |
56-
| `--idempotency-window` | | `24h` | Lookback window for duplicate purchase detection. Accepted and validated as a Go duration string; see [purchase-safety.md](purchase-safety.md). |
56+
| `--idempotency-window` | | `24h` | Lookback window for duplicate purchase detection. Accepted as a Go duration string (not validated by the CLI; currently has no effect on CLI runs). See [purchase-safety.md](purchase-safety.md). |
5757

5858
### Recommendation quality filters
5959

‎docs/cli/filtering.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,18 +9,20 @@ All filters are evaluated before any purchase is attempted. Filtered-out recomme
99

1010
## Scoping filters
1111

12-
Scoping filters operate on include/exclude list pairs. An item that appears in both lists is rejected at startup with an error:
12+
Scoping filters operate on include/exclude list pairs. For region, instance-type, and engine pairs, an item that appears in both lists is rejected at startup with an error:
1313

1414
> `region 'us-east-1' cannot be both included and excluded`
1515
16+
The conflict check is NOT applied to `--include-accounts`/`--exclude-accounts` or `--include-sp-types`/`--exclude-sp-types`; for those, a name listed in both lists silently behaves as excluded (exclude wins). Avoid listing the same value in both lists.
17+
1618
### Account filters
1719

1820
```text
1921
--include-accounts Only include recommendations for these account names (comma-separated)
2022
--exclude-accounts Exclude recommendations for these account names (comma-separated)
2123
```
2224

23-
Account names are matched against the friendly alias resolved from AWS Organizations (`organizations:ListAccounts`). If the alias cannot be resolved, the account ID is used as a fallback.
25+
Account names are matched against the friendly alias resolved from AWS Organizations (`organizations:DescribeAccount`, called per account ID and cached). If the alias cannot be resolved, the account ID is used as a fallback.
2426

2527
```bash
2628
# Only process two accounts

‎docs/cli/purchase-safety.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@ The default path (`./cudly-audit.jsonl`) writes to the current working directory
9393
--idempotency-window string default: 24h
9494
```
9595

96-
This flag is accepted and validated as a Go duration string (e.g. `24h`, `48h`, `1h30m`). The CLI pipeline stores it but does not yet subtract previously-purchased commitments from new recommendations based on this window; that deduction logic runs in the server-side scheduler path, not the CLI purchase loop. Passing this flag in CLI invocations has no effect on which recommendations are purchased.
96+
This flag is accepted as a Go duration string (e.g. `24h`, `48h`, `1h30m`). The CLI does not validate the string at startup; it stores the raw value but does not yet subtract previously-purchased commitments from new recommendations based on this window. The deduction logic runs in the server-side scheduler path (where the duration IS parsed), not the CLI purchase loop. Passing this flag in CLI invocations has no effect on which recommendations are purchased.
9797

9898
The audit status value `skipped_covered` (idempotency hit) is defined in the audit record schema for use by the server path and is not emitted by the CLI.
9999

0 commit comments

Comments
 (0)