Update to Control Plane

{
  "name": "query-spec",
  "description": "Filters, selects, and sorts Control Plane resources with the query spec language. Use when the user asks about targetQuery, memberQuery, cpln query commands, tag-based selection, property filtering, or dynamic location selection.",
  "included_files": [],
  "skill_md_contents": "---\nname: query-spec\ndescription: \"Filters, selects, and sorts Control Plane resources with the query spec language. Use when the user asks about targetQuery, memberQuery, cpln query commands, tag-based selection, property filtering, or dynamic location selection.\"\n---\n\n# Query Spec — Filtering & Selecting Resources\n\nControl Plane has one query language used in two ways: **ad-hoc filtering** of a resource list (CLI / API), and **dynamic targeting** embedded inside three resource fields.\n\n| Where | Field / command | Purpose |\n|:---|:---|:---|\n| Policy | `targetQuery` | Target resources by tag/property instead of listing `targetLinks` (see **access-control**) |\n| Group | `memberQuery` | Assign members dynamically — **users only** |\n| GVC | `spec.staticPlacement.locationQuery` | Select locations dynamically instead of listing `locationLinks` |\n| CLI | `cpln KIND query` | Ad-hoc filtering — every resource kind |\n| API | `POST /org/ORG/KIND/-query` | Ad-hoc filtering — every resource kind |\n\n**Not an MCP list parameter.** `list_resources` has no filter argument (list a kind, then filter the table yourself); `query_audit_events` filters by kind/name/subject/context/time; `query_metrics` takes PromQL. The query spec appears only inside the three resource fields above, set when you create or update that resource.\n\n## Structure\n\n```yaml\nkind: workload          # resource kind being selected\nfetch: items            # \"items\" (objects, default) or \"links\" (references)\nspec:\n  match: all            # \"all\" (default), \"any\", or \"none\"\n  terms:\n    - op: \"=\"\n      tag: environment\n      value: production\n    - op: exists\n      tag: monitored\n  sort:\n    by: name\n    order: asc\n```\n\n## Terms\n\nEach term targets exactly **one** of three fields (mutually exclusive — the schema rejects a term that sets more than one):\n\n| Field | Targets | Example |\n|:---|:---|:---|\n| `tag` | Resource tags (key/value labels) | `tag: environment`, `value: production` |\n| `property` | Built-in properties (`name`, `description`, `status.phase`, …) | `property: name`, `value: my-app` |\n| `rel` | Relationships to other resources | `rel: gvc`, `value: my-gvc` |\n\n### Operators\n\n| Operator | Needs `value` | Meaning |\n|:---|:---:|:---|\n| `=` | yes | Equal (default when `op` is omitted) |\n| `!=` | yes | Not equal |\n| `>` `>=` `<` `<=` | yes | Numeric / date comparison |\n| `~` | yes | Pattern match (schema op name `match`) |\n| `=~` | yes | Regex match (schema op name `regex`) |\n| `contains` | yes | Substring match |\n| `exists` | no | Tag/property is present (any value) |\n| `!exists` | no | Tag/property is absent |\n\n`value` accepts a string, number, boolean, or ISO date. **Boolean values are auto-converted to strings on `tag` terms only** — store `monitored=true` and you must query `value: \"true\"`, not `value: true`, or it silently matches nothing.\n\n## Match modes\n\n| Mode | Behavior |\n|:---|:---|\n| `all` | Every term must match (default) |\n| `any` | At least one term matches |\n| `none` | No term may match |\n\n## Sorting\n\n```yaml\nsort:\n  by: name            # required\n  order: asc          # \"asc\" (default) or \"desc\"\n```\n\nSort is **API- and manifest-only** — the `cpln KIND query` CLI has no sort flag, so a sort directive passed there is ignored.\n\nCommon fields (most kinds): `id`, `name`, `version`, `description`, `created`, `lastModified`. Kind-specific: `location` adds `origin`/`provider`/`region`; `cloudaccount` adds `provider`; `user` adds `idp`/`email`; `policy` and `group` add `origin`.\n\n## CLI\n\n**Ad-hoc filtering** — every kind supports `query`:\n\n```bash\ncpln workload query --tag environment=production\ncpln workload query --match all --tag environment=production --tag region=europe\ncpln workload query --rel gvc=my-gvc\ncpln policy query --prop name=my-policy\ncpln workload query --tag monitored                       # existence (no value)\ncpln workload query --match any --rel gvc=one --rel gvc=two\n```\n\n| Flag | Alias | Notes |\n|:---|:---|:---|\n| `--match` | | `all` / `any` / `none` (default `all`); single value |\n| `--tag` | | `KEY=VALUE`, or `KEY` for existence; repeatable |\n| `--property` | `--prop` | `KEY=VALUE`; repeatable |\n| `--rel` | | `KEY=VALUE`; repeatable |\n\nResults cap at 50 by default — raise with `--max 0` for all records.\n\n**Authoring dynamic targeting** — `gvc`, `policy`, and `group` create/update commands embed a query via `--query-match`, `--query-tag`, `--query-property`, `--query-rel` (group also `--query-kind user`):\n\n```bash\ncpln policy create --name img-policy --query-kind image --query-property repository=my-app ...\n```\n\n## API\n\n```\nPOST https://api.cpln.io/org/ORG/workload/-query\n```\n\n```json\n{ \"spec\": { \"match\": \"all\",\n  \"terms\": [\n    { \"op\": \"=\", \"tag\": \"region\", \"value\": \"emea\" },\n    { \"rel\": \"gvc\", \"op\": \"=\", \"value\": \"mygvc\" }\n  ],\n  \"sort\": { \"by\": \"name\", \"order\": \"asc\" } } }\n```\n\n## Dynamic targeting examples\n\n**Policy `targetQuery`** — applies to matching resources, including ones created later:\n\n```yaml\nkind: policy\ntargetKind: image\ntargetQuery:\n  spec:\n    terms:\n      - { property: repository, value: my-app }\nbindings:\n  - permissions: [pull, view]\n    principalLinks: [//group/developers]\n```\n\n**Group `memberQuery`** — dynamic membership by user tag (users only; service accounts must be added via `memberLinks`):\n\n```yaml\nkind: group\nmemberQuery:\n  kind: user\n  spec:\n    terms:\n      - { tag: \"firebase/sign_in_provider\", value: \"microsoft.com\" }\n```\n\n## Defaults & gotchas\n\n- Omitted `op` defaults to `=`; omitted `match` defaults to `all`; omitted `fetch` defaults to `items`; omitted sort `order` defaults to `asc`.\n- Boolean tag values become strings — query `\"true\"`, not `true`.\n- `targetQuery` is retroactive: tag a new resource and matching policies cover it automatically — a scope to watch when granting permissions.\n- `memberQuery` ignores service accounts.\n\n## Related\n\n**access-control** (policy `targetQuery` / group `memberQuery` in context) · **cpln** (CLI command surface).\n"
}