@thinkingai/ae-cli 6.0.20 → 6.0.22

package/skills/ae-metadata/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: ae-metadata
+version: 1.0.0
+description: "AE/TE metadata capability-gateway CLI: metadata event/property detail, metadata data-table management, input-file upload, and property dimension-table binding. Use for ae-cli metadata commands backed by /api/cli/metadata/v1. Must read references before composing commands; command/flags use kebab-case while gateway input keeps snake_case. Never guess project_id, event/property names, input_file_id, or data_table_id."
+---
+
+# ae-metadata
+
+Capability-gateway domain **`metadata`** — REST via `/api/cli/metadata/v1/...`, auth header **`cli-token`**.
+
+Parallel to **`ae-analysis`** (MCP `analysis_meta` for metadata lists/governance). Use **this skill** for gateway-backed metadata detail and data-table/dimension-table operations; use **`ae-analysis`** for MCP metadata list/search, metrics, virtual create, and batch edit.
+
+## Global AE CLI Rules
+
+| Parameter | Description |
+|---|---|
+| `--format <json\|table>` | Output format. Default JSON. |
+| `--jq <expr>` | jq filter on JSON output. |
+| `--host <url>` | Override active AE host, e.g. `ae-cli metadata event get --host <url> ...`. |
+| `--dry-run` | Validate input against gateway schema without executing. |
+
+Output and errors:
+- Success: JSON envelope (default).
+- Failure: `{ "ok": false, "error": { "type", "message", "hint" } }`, non-zero exit.
+
+Safety:
+- Read-only commands can run directly after IDs/names are verified.
+- Write commands (`data-table *-write`, `*-delete`, `property-bindings-update`, dimension-table bind/create, `input-file upload`) require `--yes` for non-dry-run execution.
+- **Before any command**, read the matching `references/<name>.md` (filename = command with spaces → underscores, e.g. `metadata event get` → `metadata_event_get.md`).
+- Never invent `project_id`, event/property names, `input_file_id`, or `data_table_id`. Discover names via `ae-analysis` and data table IDs via `metadata data-table list`.
+
+## When to Use
+
+Switch to **`ae-metadata`** when the user needs:
+
+- Full detail for **one** super-event (incl. virtual event `definition`)
+- Full detail for **one** super-property (incl. virtual property `definition`)
+- Metadata data-table list/get/create/update/delete/download
+- Upload a local file to get `input_file_id`
+- Bind an existing data table to a property, or create a CSV dimension table and bind it
+
+Stay on **`ae-analysis`** for: metadata event/property/metric list/search, metric CRUD, batch metadata, virtual create, project config, tracking plans.
+
+## Command Format
+
+```bash
+ae-cli metadata <resource> <action> [options]
+ae-cli metadata property <dimension-table-action> [options]
+```
+
+- Commands and flags use **kebab-case**: `data-table`, `input-file`, `dimension-table`, `--project-id`, `--data-table-id`.
+- Gateway `input` body fields remain **snake_case** (`project_id`, `event_name`, …); ae-cli maps flags automatically.
+
+## PROJECT_ID_GATE
+
+Same rules as `ae-analysis`: reuse verified project context in one conversation; otherwise `ae-cli analysis_common +list_projects` (or `ae-analysis` skill) to resolve `project_id`.
+
+## Commands (13)
+
+| User command | Capability id | Reference |
+|---|---|---|
+| `metadata event get` | `metadata.event.get` | [metadata_event_get.md](references/metadata_event_get.md) |
+| `metadata property get` | `metadata.property.get` | [metadata_property_get.md](references/metadata_property_get.md) |
+| `metadata input-file upload` | `POST /input-files` | [metadata_input_file_upload.md](references/metadata_input_file_upload.md) |
+| `metadata data-table list` | `metadata.data_table.list` | [metadata_data_table_list.md](references/metadata_data_table_list.md) |
+| `metadata data-table get` | `metadata.data_table.get` | [metadata_data_table_get.md](references/metadata_data_table_get.md) |
+| `metadata data-table csv-write` | `metadata.data_table.csv_write` | [metadata_data_table_csv_write.md](references/metadata_data_table_csv_write.md) |
+| `metadata data-table sql-write` | `metadata.data_table.sql_write` | [metadata_data_table_sql_write.md](references/metadata_data_table_sql_write.md) |
+| `metadata data-table csv-delete` | `metadata.data_table.csv_delete` | [metadata_data_table_csv_delete.md](references/metadata_data_table_csv_delete.md) |
+| `metadata data-table sql-delete` | `metadata.data_table.sql_delete` | [metadata_data_table_sql_delete.md](references/metadata_data_table_sql_delete.md) |
+| `metadata data-table download` | `metadata.data_table.download` | [metadata_data_table_download.md](references/metadata_data_table_download.md) |
+| `metadata data-table property-bindings-update` | `metadata.data_table.property_bindings_update` | [metadata_data_table_property_bindings_update.md](references/metadata_data_table_property_bindings_update.md) |
+| `metadata property bind-existing-dimension-table` | `metadata.property.bind_existing_dimension_table` | [metadata_property_dimension_table_bind_existing.md](references/metadata_property_dimension_table_bind_existing.md) |
+| `metadata property create-and-bind-csv-dimension-table` | `metadata.property.create_and_bind_csv_dimension_table` | [metadata_property_dimension_table_create_and_bind_csv.md](references/metadata_property_dimension_table_create_and_bind_csv.md) |
+
+## Quick Verification
+
+```bash
+ae-cli metadata --help
+ae-cli metadata event get --help
+ae-cli metadata property get --help
+ae-cli metadata data-table list --help
+ae-cli metadata event get --project-id 1 --event-name <name> --dry-run
+ae-cli metadata data-table list --project-id 1 --dry-run
+```
+
+## Related Skills
+
+- **`ae-analysis`**: `analysis_meta +list_events` / `+list_properties` to discover names before detail get.
+- **Dev workflow**: `.cursor/skills/te-cli-capability-gateway` — inspect gateway schema when adding new metadata capabilities.

package/skills/ae-metadata/references/metadata_data_table_csv_delete.md

@@ -0,0 +1,15 @@
+# metadata data-table csv-delete
+
+> Capability id: `metadata.data_table.csv_delete` · Domain: `metadata`.
+
+```bash
+ae-cli metadata data-table csv-delete --project-id <project_id> --data-table-id <id> --yes
+ae-cli metadata data-table csv-delete --project-id <project_id> --data-table-id <id> --dry-run
+```
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--data-table-id` | Yes | CSV-backed data table ID. |
+
+This is a write command. Confirm the table with `metadata data-table get` before deleting.

package/skills/ae-metadata/references/metadata_data_table_csv_write.md

@@ -0,0 +1,29 @@
+# metadata data-table csv-write
+
+> Capability id: `metadata.data_table.csv_write` · Domain: `metadata`.
+
+## Command
+
+```bash
+ae-cli metadata data-table csv-write --project-id <project_id> --operation create --input-file-id <input_file_id> --data-table-name <name> --columns '<columns_json>' --yes
+ae-cli metadata data-table csv-write --project-id <project_id> --operation incremental_update --data-table-id <id> --input-file-id <input_file_id> --yes
+ae-cli metadata data-table csv-write --project-id <project_id> --operation replace_update --data-table-id <id> --input-file-id <input_file_id> --yes
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--operation` | Yes | `create`, `incremental_update`, or `replace_update`. |
+| `--input-file-id` | Yes | ID returned by `metadata input-file upload`. |
+| `--data-table-id` | For updates | Existing data table ID. |
+| `--data-table-name` | For create | Technical data table name. |
+| `--display-name` | No | Human-readable table name. |
+| `--description` | No | Table description. |
+| `--columns` | No | Column definitions JSON array. |
+
+## Decision Rules
+
+- Upload the CSV first with `metadata input-file upload --purpose data_table.csv`.
+- This is a write command; use `--dry-run` before non-dry-run and pass `--yes` when executing.

package/skills/ae-metadata/references/metadata_data_table_download.md

@@ -0,0 +1,17 @@
+# metadata data-table download
+
+> Capability id: `metadata.data_table.download` · Domain: `metadata`.
+
+```bash
+ae-cli metadata data-table download --project-id <project_id> --data-table-id <id>
+ae-cli metadata data-table download --project-id <project_id> --data-table-id <id> --request-id cli_0123456789abcdef0123456789abcdef --timeout-seconds 120
+```
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--data-table-id` | Yes | Data table ID. |
+| `--request-id` | No | Optional `cli_<32 lowercase hex>` request ID. |
+| `--timeout-seconds` | No | Timeout in seconds, 1 to 7200. |
+
+Use this command when the user needs an exported data-table artifact.

package/skills/ae-metadata/references/metadata_data_table_get.md

@@ -0,0 +1,24 @@
+# metadata data-table get
+
+> Capability id: `metadata.data_table.get` · Domain: `metadata`.
+
+## Command
+
+```bash
+ae-cli metadata data-table get --project-id <project_id> --data-table-id <id>
+ae-cli metadata data-table get --project-id <project_id> --data-table-id <id> --include-preview true
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--data-table-id` | Yes | Data table ID from `metadata data-table list`. |
+| `--include-preview` | No | Include preview rows when true. |
+
+## Request Body
+
+```json
+{ "project_id": 1, "data_table_id": 42, "include_preview": true }
+```

package/skills/ae-metadata/references/metadata_data_table_list.md

@@ -0,0 +1,27 @@
+# metadata data-table list
+
+> Capability id: `metadata.data_table.list` · Domain: `metadata`.
+
+## Command
+
+```bash
+ae-cli metadata data-table list --project-id <project_id>
+ae-cli metadata data-table list --project-id <project_id> --dry-run
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+
+## Request Body
+
+```json
+{ "project_id": 1 }
+```
+
+## Decision Rules
+
+- Use this command to discover `data_table_id` before get, delete, download, or property binding.
+- If the list is empty, do not invent IDs; create/upload a table first or ask for the target table.

package/skills/ae-metadata/references/metadata_data_table_property_bindings_update.md

@@ -0,0 +1,17 @@
+# metadata data-table property-bindings-update
+
+> Capability id: `metadata.data_table.property_bindings_update` · Domain: `metadata`.
+
+```bash
+ae-cli metadata data-table property-bindings-update --project-id <project_id> --data-table-id <id> --bind-properties '<bind_json>' --yes
+ae-cli metadata data-table property-bindings-update --project-id <project_id> --data-table-id <id> --unbind-properties '<unbind_json>' --yes
+```
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--data-table-id` | Yes | Data table ID. |
+| `--bind-properties` | No | Properties to bind JSON array. Each item includes `property_name` and `property_scope`. |
+| `--unbind-properties` | No | Properties to unbind JSON array. Each item includes `property_name` and `property_scope`. |
+
+This is a write command. Use the direct property dimension-table commands when binding a single property is the user-facing goal.

package/skills/ae-metadata/references/metadata_data_table_sql_delete.md

@@ -0,0 +1,15 @@
+# metadata data-table sql-delete
+
+> Capability id: `metadata.data_table.sql_delete` · Domain: `metadata`.
+
+```bash
+ae-cli metadata data-table sql-delete --project-id <project_id> --data-table-id <id> --yes
+ae-cli metadata data-table sql-delete --project-id <project_id> --data-table-id <id> --dry-run
+```
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--data-table-id` | Yes | SQL-backed data table ID. |
+
+This is a write command. Confirm the table with `metadata data-table get` before deleting.

package/skills/ae-metadata/references/metadata_data_table_sql_write.md

@@ -0,0 +1,31 @@
+# metadata data-table sql-write
+
+> Capability id: `metadata.data_table.sql_write` · Domain: `metadata`.
+
+## Command
+
+```bash
+ae-cli metadata data-table sql-write --project-id <project_id> --operation create --table-name <name> --columns '<columns_json>' --qp '<qp_json>' --strategy overwrite --yes
+ae-cli metadata data-table sql-write --project-id <project_id> --operation update --data-table-id <id> --columns '<columns_json>' --qp '<qp_json>' --yes
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--operation` | Yes | `create` or `update`. |
+| `--columns` | Yes | Column definitions JSON array. |
+| `--qp` | Yes | SQL data table query plan JSON. |
+| `--data-table-id` | For update | Existing data table ID. |
+| `--table-name` | For create | Technical table name. |
+| `--display-name` | No | Human-readable name. |
+| `--remarks` | No | Table remarks. |
+| `--zone-offset` | No | Time zone offset such as `+08:00`. |
+| `--strategy` | No | `overwrite` or `insert`. |
+| `--update-cron` | No | Scheduled update cron. |
+
+## Decision Rules
+
+- This is a write command; use `--dry-run` before non-dry-run and pass `--yes` when executing.
+- Keep `columns` and `qp` as valid JSON; do not pass raw SQL unless the server schema requires it inside `qp`.

package/skills/ae-metadata/references/metadata_event_get.md

@@ -0,0 +1,52 @@
+# metadata event get (Super-Event Detail)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md) (`ae-metadata` skill).
+>
+> Capability id: `metadata.event.get` · Domain: `metadata` (capability gateway REST, not MCP `analysis_meta`).
+
+## Use Cases
+
+- Fetch **one** super-event metadata record by technical name (full detail, not a paginated list).
+- Inspect virtual event definition (`definition.sources`, filters, relation) when `event_kind=virtual_event`.
+- Read-only; requires metadata **view** permission (`VIEW_META`) in the target project.
+
+## Commands
+
+```bash
+ae-cli metadata event get --project-id <project_id> --event-name <event_name>
+ae-cli metadata event get -p <project_id> --event-name <event_name> --dry-run
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--event-name` | Yes | Super-event technical name. Virtual events use the same field. |
+
+Gateway request body uses snake_case `input`:
+
+```json
+{
+  "project_id": 1,
+  "event_name": "purchase"
+}
+```
+
+## Decision Rules
+
+- Prefer **`metadata event get`** over `analysis_meta +list_events` when you need **full detail + virtual definition**, not browsing or fuzzy search.
+- Use `ae-analysis` → `analysis_meta +list_events` first when the event name is unknown or you need keyword search / pagination.
+- If the gateway returns `EVENT_NOT_FOUND`, verify `event_name` spelling and `project_id`; do not invent names.
+- Auth: `cli-token` header (ae-cli injects automatically in sandbox; local CLI uses `getCliToken()`).
+
+## Recommended Chaining
+
+- `ae-analysis`: `analysis_meta +list_events` (discover name) → `metadata event get` (detail)
+- `metadata event get` → `metadata property get` (inspect properties listed in response)
+
+## Next Steps After Failure
+
+- Empty or not found: confirm project id and exact `event_name` from `+list_events`.
+- Permission error: confirm metadata view permission in the project.
+- Gateway unavailable: confirm nginx routes `/api/cli/metadata/` and backend capability catalog is deployed.

package/skills/ae-metadata/references/metadata_input_file_upload.md

@@ -0,0 +1,29 @@
+# metadata input-file upload
+
+> Capability endpoint: `POST /api/cli/metadata/v1/input-files` · Domain: `metadata`.
+
+## Use Cases
+
+- Upload a local CSV file before `metadata data-table csv-write`.
+- Get an `input_file_id` such as `ifile_<32 lowercase hex>`.
+
+## Command
+
+```bash
+ae-cli metadata input-file upload --project-id <project_id> --purpose data_table.csv --file <local_file> --yes
+ae-cli metadata input-file upload --project-id <project_id> --purpose data_table.csv --file <local_file> --dry-run
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--purpose` | Yes | Input-file purpose. Use `data_table.csv` for data table CSV imports. |
+| `--file` | Yes | Local file path to upload. |
+
+## Decision Rules
+
+- Run `--dry-run` first to verify the gateway URL and multipart fields.
+- Use the returned `input_file_id` in CSV data-table write or create-and-bind commands.
+- This is a write command; non-dry-run execution requires `--yes`.

package/skills/ae-metadata/references/metadata_property_dimension_table_bind_existing.md

@@ -0,0 +1,27 @@
+# metadata property bind-existing-dimension-table
+
+> Capability id: `metadata.property.bind_existing_dimension_table` · Domain: `metadata`.
+
+## Command
+
+```bash
+ae-cli metadata property bind-existing-dimension-table --project-id <project_id> --property-name <name> --property-scope user --data-table-id <id> --yes
+ae-cli metadata property bind-existing-dimension-table --project-id <project_id> --property-name <name> --property-scope event --data-table-id <id> --dict-columns '["display_name"]' --yes
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--property-name` | Yes | Property technical name. |
+| `--property-scope` | Yes | Property owner table, for example `event` or `user`. |
+| `--data-table-id` | Yes | Existing dimension data table ID. |
+| `--timestamp-join-format` | No | Timestamp join format. |
+| `--dict-columns` | No | Dictionary column names JSON array. |
+
+## Decision Rules
+
+- Confirm the property with `metadata property get` or `analysis_meta +list_properties`.
+- Confirm the data table with `metadata data-table get`.
+- This is a write command; use `--dry-run` before non-dry-run and pass `--yes` when executing.

package/skills/ae-metadata/references/metadata_property_dimension_table_create_and_bind_csv.md

@@ -0,0 +1,30 @@
+# metadata property create-and-bind-csv-dimension-table
+
+> Capability id: `metadata.property.create_and_bind_csv_dimension_table` · Domain: `metadata`.
+
+## Command
+
+```bash
+ae-cli metadata property create-and-bind-csv-dimension-table --project-id <project_id> --property-name <name> --property-scope user --input-file-id <input_file_id> --data-table-name <table_name> --columns '<columns_json>' --yes
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--property-name` | Yes | Property technical name. |
+| `--property-scope` | Yes | Property owner table, for example `event` or `user`. |
+| `--input-file-id` | Yes | ID returned by `metadata input-file upload`. |
+| `--data-table-name` | No | Technical data table name. |
+| `--display-name` | No | Human-readable table name. |
+| `--description` | No | Table description. |
+| `--columns` | No | Column definitions JSON array. |
+| `--timestamp-join-format` | No | Timestamp join format. |
+| `--dict-columns` | No | Dictionary column names JSON array. |
+
+## Decision Rules
+
+- Upload the CSV first with `metadata input-file upload --purpose data_table.csv`.
+- Use this one-step command when the user wants a new CSV dimension table bound to a property.
+- This is a write command; use `--dry-run` before non-dry-run and pass `--yes` when executing.

package/skills/ae-metadata/references/metadata_property_get.md

@@ -0,0 +1,54 @@
+# metadata property get (Super-Property Detail)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md) (`ae-metadata` skill).
+>
+> Capability id: `metadata.property.get` · Domain: `metadata` (capability gateway REST, not MCP `analysis_meta`).
+
+## Use Cases
+
+- Fetch **one** super-property metadata record (event scope or user scope).
+- Inspect virtual property definition (`definition.expression`, `dependencies`).
+- Read-only; requires metadata **view** permission in the target project.
+
+## Commands
+
+```bash
+ae-cli metadata property get --project-id <project_id> --property-name <name> --property-scope event
+ae-cli metadata property get --project-id <project_id> --property-name <name> --property-scope user --dry-run
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--property-name` | Yes | Super-property technical name. |
+| `--property-scope` | Yes | `event` (super event properties) or `user` (super user properties). |
+
+Gateway request body uses snake_case `input`:
+
+```json
+{
+  "project_id": 1,
+  "property_name": "price",
+  "property_scope": "event"
+}
+```
+
+## Decision Rules
+
+- Prefer **`metadata property get`** over `analysis_meta +list_properties` when you need **full detail + virtual definition**, not browsing or fuzzy search.
+- Use `ae-analysis` → `analysis_meta +list_properties` first when the property name is unknown or you need keyword search / pagination.
+- `property_scope` must be exactly `event` or `user` (backend accepts case-insensitive).
+- Virtual / dict / exchange-rate properties are addressed by `property-name` only; do not pass legacy `prop_name`.
+- Event-scoped names like `#account_id` must be passed literally (quote in shell when `#` is present).
+
+## Recommended Chaining
+
+- `ae-analysis`: `analysis_meta +list_properties` (discover name + scope) → `metadata property get` (detail)
+- `metadata event get` → `metadata property get` (follow properties from event detail)
+
+## Next Steps After Failure
+
+- Not found: confirm scope (`event` vs `user`) and exact name from `+list_properties`.
+- Permission error: confirm metadata view permission in the project.