@thinkingai/ae-cli 6.1.19 → 6.1.21

package/skills/ae-analysis/references/user_tag_member_export.md

@@ -2,7 +2,7 @@
 
 Stream the native full tag-member download as an async gzip artifact. Read `analysis_data_retrieval.md` first.
 
-Do not use this command for an inline sample or filtered keyword search; use `user-tag-member run` for preview behavior.
+Do not use this command for an inline sample or filtered keyword search; use `user-tag-member list` for preview behavior.
 
 Flags: `--project-id`, `--tag-name` required. Optional: `--snapshot-date`, `--property-names`, `--request-id`, `--artifact-format jsonl|csv`, `--timeout-seconds`. The default format is `jsonl`.
 
@@ -11,7 +11,7 @@ If you provide `--request-id`, use `cli_<32 lowercase hex>`. Omit it unless you
 Export does not accept `--offset`, `--fields`, `--query`, or `--use-cache`. Common executes the native current-tag or history-tag full-download SQL once and streams result rows directly as `jsonl.gz` or `csv.gz`; it does not concatenate preview pages. The existing full-download ceiling still applies.
 
 ```bash
-ae-cli analysis user-tag-member export --project-id <project_id> --tag-name user_level --artifact-format jsonl
-ae-cli analysis run inspect --run-id <run_id>
-ae-cli analysis artifact download --run-id <run_id> --artifact-id <artifact_id> --output tag-members.jsonl.gz
+ae-cli analysis user-tag-member export --project-id <project_id> --tag-name user_level --artifact-format jsonl --output tag-members.jsonl.gz
 ```
+
+Use `--output` to wait and download the completed artifact. If interrupted, resume with `ae-cli analysis run wait --run-id <run_id> --output <file>` using the same export response. See [`run_wait.md`](run_wait.md).

package/skills/ae-analysis/references/user_tag_models.md

@@ -24,12 +24,20 @@ Top-level `type` is exactly one of `condition`, `metric`, `first_last`, or `sql`
 
 ## Metric tag
 
-Required: `event`, `aggregation`. `property`, `time_range`, and `filters` are optional. Filters support only event properties and user properties. A string `field` is an event property; use `{name,type:"user_property"}` for a user property.
+Required: `event`, `aggregation`. `property`, `percentile`, `time_range`, and `filters` are optional. Filters support only event properties and user properties. A string `field` is an event property; use `{name,type:"user_property"}` for a user property.
+
+Use `aggregation=percentile` with a numeric event `property` and pass `percentile`. Supported percentile values match the page controls: `5`, `10`, `20`, `25`, `30`, `40`, `60`, `70`, `75`, `80`, `90`, `95`, and `99`. The `percentile` field is required for percentile aggregation and is rejected for every other aggregation.
 
 ```json
 {"type":"metric","metric":{"event":"pay","aggregation":"sum","property":"amount","time_range":{"mode":"previous","unit":"day","value":30},"filters":{"relation":"and","items":[{"field":"channel","operator":"eq","values":["app"]},{"field":{"name":"country","type":"user_property"},"operator":"eq","values":["US"]}]}}}
 ```
 
+Percentile example:
+
+```json
+{"type":"metric","metric":{"event":"pay","aggregation":"percentile","property":"amount","percentile":90}}
+```
+
 ## First/last tag
 
 Required: `event`, `occurrence=first|last`, and exactly one value source: `calculation` or `property`. `time_range` and `filters` are optional. Filters support only event properties and user properties. A string `field` is an event property; use `{name,type:"user_property"}` for a user property. Supplying neither or both value sources is rejected before execution. Use the semantic time mappings in [`audience_models.md`](audience_models.md) for dynamic ranges such as today, this month, or a fixed start date through today.

package/skills/ae-analysis/references/user_tag_update.md

@@ -2,11 +2,11 @@
 
 Update a user tag. Discover the exact `tag_name` first.
 
-Do not use it for ID-file value replacement or to create a missing tag. Supplying `--definition-request` automatically starts recomputation after the definition is updated; do not call `user-tag refresh` afterward. Updating only `--display-name` or `--remark` does not recompute. `--auto-refresh-cron` changes an existing enabled auto-refresh schedule and does not enable auto refresh. A successful update means the definition was saved, not that the new result is complete. Record the current `refresh_time` before updating, then poll `user-tag get` until `progress=100` and `refresh_time` advances before using `users_num` or querying members.
+Do not use it for ID-file value replacement or to create a missing tag. Supplying `--definition-request` automatically starts recomputation after the definition is updated; do not call `user-tag refresh` afterward. Updating only `--display-name` or `--remark` does not recompute. A schedule-only update changes periodic refresh without starting immediate recomputation. `--auto-refresh-cron` or `--auto-refresh-schedule` can enable periodic refresh directly, including on a previously disabled tag. A successful update means the definition was saved, not that the new result is complete. Record the current `refresh_time` before updating, then poll `user-tag get` until `progress=100` and `refresh_time` advances before using `users_num` or querying members.
 
 The response distinguishes both paths. A definition update returns `computation.triggered_automatically=true`, `result_freshness.is_stale=true`, and normally `next_action=poll_get` with an exact capability/input pair. A display-name/remark-only update returns `computation.status=not_triggered`, `result_freshness.status=fresh`, and `next_action=none`.
 
-Flags: `--project-id`, `--tag-name` required. Optional: `--display-name`, `--definition-request`, `--authenticated-only`, `--remark`, `--zone-offset`, `--auto-refresh-cron`. The tag type comes from `definition_request.type` when the definition changes.
+Flags: `--project-id`, `--tag-name` required. Optional: `--display-name`, `--definition-request`, `--authenticated-only`, `--remark`, `--zone-offset`, `--enable-auto-refresh`, `--auto-refresh-schedule`, `--auto-refresh-cron`. The tag type comes from `definition_request.type` when the definition changes.
 
 `display_name` is at most 80 characters and `remark` is at most 400 characters. The CLI rejects violations before dispatch. `tag_name` is an existing exact identifier and cannot be renamed by update.
 
@@ -17,3 +17,15 @@ ae-cli analysis user-tag update --project-id <project_id> --tag-name user_level
 
 ae-cli analysis user-tag update --project-id <project_id> --tag-name user_level --auto-refresh-cron '0 30 2 * * ? *'
 ```
+
+Omitting scheduling flags preserves the existing enable state and schedule, including during a definition update. Omitting `--zone-offset` preserves the saved tag timezone. `--enable-auto-refresh true` can reuse an existing saved plan; if none exists, provide a new schedule. `--enable-auto-refresh false` disables periodic refresh. Do not combine false with a schedule or pass both schedule forms. Structured schedule fields and timezone rules are described in [user_tag_create.md](user_tag_create.md).
+
+```bash
+# Enable daily refresh in one update
+ae-cli analysis user-tag update --project-id <project_id> --tag-name user_level --auto-refresh-schedule '{"frequency":"daily","time":"02:30"}'
+
+# Disable periodic refresh
+ae-cli analysis user-tag update --project-id <project_id> --tag-name user_level --enable-auto-refresh false
+```
+
+Read `user-tag get` after updating to verify `enable_auto_refresh` (1=enabled, 0=disabled), `scheduler_ui_config`, and `cluster_zone_offset`. Schedule-only updates return `computation.status=not_triggered` and `next_action=none`.

package/skills/ae-analysis/references/virtual_event_create.md

@@ -4,15 +4,15 @@ Use when the user needs to create a virtual event from events and filters.
 
 Do not use it for super-event creation.
 
-Before constructing `--events` / `--filter`, validate the available events and properties with `analysis-meta event list` and `analysis-meta property list` in the same `project_id`.
+Before constructing `--events` / `--filter`, validate the available events and properties with `analysis-meta event list` and `analysis-meta property list` in the same `project_id`. Resolve tag and cluster names with `analysis user-tag list` / `analysis user-cluster list`; for a fixed tag snapshot, resolve a real date with `analysis history-tag list`.
 
 Command:
 
 ```bash
 ae-cli analysis-meta virtual-event create --project-id <project_id> --event-name ta@demo --event-desc demo --events '[{"event_name":"purchase"}]'
 ae-cli analysis-meta virtual-event create --project-id <project_id> --event-name ta@demo2 --event-desc demo --remark demo --events '[{"event_name":"add_to_cart","filter":{"relation":"and","items":[{"field":{"name":"country","type":"user_property"},"operator":"eq","values":["US"]}]}}]' --override true
+ae-cli analysis-meta virtual-event create --project-id <project_id> --event-name ta@vip_purchase --event-desc 'VIP purchase' --events '[{"event_name":"purchase","filter":{"relation":"and","items":[{"field":{"name":"vip_users","type":"tag"},"operator":"is_true","cluster_date_policy":"SPECIFIED","specified_cluster_date":"2026-09-15"}]}}]'
 ae-cli analysis-meta virtual-event create --project-id <project_id> --override false --payload '{"event_name":"ta@qualified_purchase","event_desc":"Qualified purchase","rule":{"events":[...],"filter":{...}}}'
-ae-cli analysis-meta virtual-event create --dry-run
 ```
 
 Capability id: `metadata.virtual_event.create`.
@@ -30,16 +30,21 @@ Output data contains `v_event_id` and `event_name`. Use the returned `v_event_id
 | `--event-name` | No | Virtual event name. Must start with `ta@`. Required when `--payload` is omitted. |
 | `--event-desc` | No | Virtual event display name. Required when `--payload` is omitted. |
 | `--remark` | No | Optional virtual event remark. |
-| `--events` | No | JSON array of `{event_name,event_desc?,filter?}`. Each filter uses `{relation:'and|or',items:[{field:{name,type?},operator,values?}]}`. Required when `--payload` is omitted. |
-| `--filter` | No | Optional global AI-facing filter with the same `relation/items` shape. Raw `taFilters`, `junctionKind`, and `calcuSymbol` are rejected. Referenced properties must come from `analysis-meta property list`. |
+| `--events` | No | JSON array of `{event_name,event_desc?,filter?}`. Each filter uses `{relation:"and|or",items:[{field:{name,type?},operator,values?,cluster_date_policy?,specified_cluster_date?}]}`. Required when `--payload` is omitted. |
+| `--filter` | No | Optional global AI-facing filter with the same `relation/items` shape. Raw `taFilters`, `junctionKind`, and `calcuSymbol` are rejected. Normal properties must come from `analysis-meta property list`; tags/clusters must come from their dedicated list commands. |
 
 ## Decision Rules
 - `events` / `filter` must not be handwritten by intuition alone; they must match real metadata in the same project.
 - Use snake_case `event_name`; do not pass the legacy `eventName` spelling.
+- `cluster_date_policy` is valid only when `field.type` is `tag` or `cluster`: `LATEST` uses the latest computed result, `AUTO` matches each analysis date dynamically, and `SPECIFIED` selects one fixed snapshot.
+- `SPECIFIED` requires `specified_cluster_date` in `yyyy-MM-dd` format. Do not send `specified_cluster_date` with `LATEST` or `AUTO`.
+- For tag `SPECIFIED`, choose a date returned by `analysis history-tag list`; do not invent a snapshot date. For a cluster, verify that the chosen fixed date exists in the target environment before creation.
 - Before calling `event list` / `property list`, read the corresponding reference documents.
 - For first validation, pass only required typed parameters: `--project-id`, `--event-name`, `--event-desc`, and `--events`.
 - Use `--payload` only when an exact virtual-event rule DTO is already available.
 - This is an ordinary write operation; execute it without the high-risk confirmation flag.
 
 ## Recommended Chain
-- `analysis-meta event list` -> `analysis-meta property list` -> `analysis-meta virtual-event create`
+- Ordinary properties: `analysis-meta event list` -> `analysis-meta property list` -> `analysis-meta virtual-event create`
+- Tag snapshot: `analysis-meta event list` -> `analysis user-tag list` -> `analysis history-tag list` -> `analysis-meta virtual-event create`
+- Cluster snapshot: `analysis-meta event list` -> `analysis user-cluster list` -> verify the fixed result date -> `analysis-meta virtual-event create`

package/skills/ae-analysis/references/virtual_event_get.md

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli analysis-meta virtual-event get --project-id <project_id> --v-event-id <v_event_id>
-ae-cli analysis-meta virtual-event get --dry-run
 ```
 
 Capability id: `metadata.virtual_event.get`.

package/skills/ae-analysis/references/virtual_property_create.md

@@ -12,7 +12,6 @@ Command:
 ae-cli analysis-meta virtual-property create --project-id <project_id> --property-name '#vp@demo' --table-type event --select-type string --sql-expression 'event_name' --sql-event-relation-type relation_default
 ae-cli analysis-meta virtual-property create --project-id <project_id> --property-name '#vp@demo' --property-desc demo --table-type event --select-type string --sql-expression "CASE WHEN status = 1 THEN 'active' ELSE 'inactive' END" --sql-event-relation-type relation_by_setting --related-events '[{"eventName":"purchase"}]' --property-remark demo
 ae-cli analysis-meta virtual-property create --project-id <project_id> --sql-expression '<sql>' --v-prop '{"property":{"column_name":"#vp@demo","table_type":"event","select_type":"string"}}' --properties '[...]'
-ae-cli analysis-meta virtual-property create --project-id <project_id> --sql-expression '<sql>' --v-prop '{...}' --dry-run
 ```
 
 Capability id: `metadata.virtual_property.create`.

package/skills/ae-analysis/references/virtual_property_sql_rule_update.md

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli analysis-meta virtual-property sql-rule-update --project-id <project_id> --sql-expression '<sql>' --v-prop '{"prop_id":22990,"property":{"column_name":"#vp@demo","table_type":"event","select_type":"number"}}' --properties '[...]'
-ae-cli analysis-meta virtual-property sql-rule-update --project-id <project_id> --sql-expression '<sql>' --v-prop '{"prop_id":22990,"property":{"column_name":"#vp@demo","table_type":"event","select_type":"number"}}' --dry-run
 ```
 
 Capability id: `metadata.virtual_property.sql_rule_update`.