@frontera-sdk/cli 1.52.38 → 1.52.40

package/src/commands/blueprint/get.ts

@@ -124,7 +124,7 @@ export const blueprintGet: Command = {
       },
     ],
     flags: {},
-    summary: 'Show one object type: its properties, relations and metrics',
+    summary: 'Show one object type: its id, properties, relations and metrics',
     examples: ['frontera blueprint get Shipment', 'frontera blueprint get shipment --json'],
   },
 
@@ -221,6 +221,8 @@ export const blueprintGet: Command = {
     const heading = [apiName, type.displayName].filter(Boolean)
     const lines = [
       heading[1] && heading[1] !== heading[0] ? `${heading[0]} — ${heading[1]}` : String(heading[0]),
+      // The runtime's id: what a hard-coded id in an App, a workflow or a test has to equal.
+      `  id ${selfId || (types.ok ? '(not in the object-type catalog)' : `(unavailable: ${types.unavailable})`)}`,
       ...(type.description ? ['', type.description] : []),
       '',
       `Properties (${props.length})`,
@@ -254,7 +256,9 @@ export const blueprintGet: Command = {
 
     return {
       data: {
-        objectType: type,
+        // `id` from the organization catalog; null when it could not be read or does not list the type.
+        objectType: { ...type, id: selfId || null },
+        id: selfId || null,
         properties: props,
         // `null` rather than `[]` for an unreadable section, and a sibling
         // field saying why. A consumer that treats absence as emptiness now has

package/src/commands/blueprint/grants.ts

@@ -25,9 +25,11 @@ async function resolveSubject(
   const byId = candidates.find((candidate) => candidate.id === nameOrId)
   if (byId?.id) return { id: byId.id, name: byId.name ?? byId.id }
 
-  const matches = candidates.filter((candidate) =>
-    candidate.name === nameOrId
-    || (subject === 'workspace' && (candidate as { slug?: string }).slug === nameOrId))
+  // An Agent by its slug too (`agentId`, `dispatcher`), as every other command names it; a
+  // workspace by its slug. A slug names one, so it wins over a display name that matches.
+  const slugOf = (candidate: { slug?: string; agentId?: string }) => (subject === 'workspace' ? candidate.slug : candidate.agentId ?? candidate.slug)
+  const bySlug = candidates.filter((candidate) => slugOf(candidate as { slug?: string; agentId?: string }) === nameOrId)
+  const matches = bySlug.length ? bySlug : candidates.filter((candidate) => candidate.name === nameOrId)
   const only = matches.length === 1 ? matches[0] : undefined
   if (only?.id) return { id: only.id, name: only.name ?? only.id }
   if (matches.length > 1) {
@@ -42,11 +44,47 @@ async function resolveSubject(
   throw new CliError(`No ${subject} named "${nameOrId}" in this organization.`, {
     code: 'NOT_FOUND',
     hint: candidates.length
-      ? `Known ${subject}s: ${candidates.map((candidate) => candidate.name).filter(Boolean).join(', ')}`
+      ? `Known ${subject}s: ${candidates.map((candidate) => { const slug = slugOf(candidate as { slug?: string; agentId?: string }); return slug && slug !== candidate.name ? `${slug} (${candidate.name})` : candidate.name }).filter(Boolean).join(', ')}`
       : `No ${subject}s are visible to this credential.`,
   })
 }
 
+/**
+ * `--permissions`, as the grant's whole list: `read` always, `read_sensitive`
+ * the only other one. A workspace's only: an Agent's clearance is its
+ * bindings.json, and a revoke takes the whole grant.
+ */
+export function grantPermissions(raw: string | boolean | undefined, subject: string, revoke: boolean): string[] | undefined {
+  if (raw === undefined) return undefined
+  if (typeof raw !== 'string' || !raw.trim()) throw new CliError('--permissions takes a list: read,read_sensitive', { code: 'USAGE', hint: 'frontera blueprint grant workspace <name> <apiName…> --permissions read,read_sensitive' })
+  if (subject !== 'workspace') throw new CliError('--permissions is for a workspace grant', { code: 'USAGE', hint: 'an Agent\'s clearance over sensitive fields is `read_sensitive` in its bindings.json' })
+  if (revoke) throw new CliError('--revoke takes the whole grant; --permissions sets what a grant gives', { code: 'USAGE', hint: 'to keep only read, grant again with --permissions read' })
+  const given = raw.split(',').map((p) => p.trim()).filter(Boolean)
+  const unknown = given.filter((p) => p !== 'read' && p !== 'read_sensitive')
+  if (unknown.length) throw new CliError(`${unknown.join(', ')} ${unknown.length === 1 ? 'is not a permission' : 'are not permissions'} a workspace grant takes`, { code: 'USAGE', hint: 'the permissions are read and read_sensitive' })
+  return ['read', ...(given.includes('read_sensitive') ? ['read_sensitive'] : [])]
+}
+
+/**
+ * What a grant without `--permissions` sends, per object type: each grant
+ * replaces the whole permission list, so `read` plus whatever the grant
+ * already holds (`act`, `read_sensitive`), never `read` alone over a grant
+ * that had more. `kept` names what was kept, by object type.
+ */
+export function keptPermissions(apiNames: string[], current: Array<{ objectTypeApiName?: string; permissions?: string[] }>): { send: Map<string, string[] | undefined>; kept: Record<string, string[]> } {
+  const send = new Map<string, string[] | undefined>()
+  const kept: Record<string, string[]> = {}
+  for (const apiName of apiNames) {
+    const held = current.find((g) => g.objectTypeApiName === apiName)?.permissions ?? []
+    const extras = [...new Set(held.filter((p) => p !== 'read'))].sort()
+    if (extras.length) {
+      send.set(apiName, ['read', ...extras])
+      kept[apiName] = extras
+    } else send.set(apiName, undefined)
+  }
+  return { send, kept }
+}
+
 export const blueprintGrant: Command = {
   meta: {
     noun: 'blueprint',
@@ -56,10 +94,15 @@ export const blueprintGrant: Command = {
       { name: 'name', required: false, description: 'Workspace or agent, by name or id' },
       { name: 'apiName...', required: false, description: 'One or more object type API names' },
     ],
-    flags: { revoke: 'boolean' },
+    flags: { revoke: 'boolean', permissions: 'string' },
     summary: 'Grant or revoke an object type for a workspace or an agent',
+    details: [
+      '`--permissions read,read_sensitive` gives a workspace clearance over the type\'s confidential and restricted fields, for the workflows, Functions and Apps that read through it (`read` is always included; `--permissions` sets the grant\'s whole list). An Agent\'s clearance is its bindings.json. In a local project, blueprint/workspace-grants.yaml declares it and `frontera local dev` applies it.',
+      'Without `--permissions`, a grant keeps what it already holds: read, plus the grant\'s `read_sensitive` or an Agent\'s `act` (submit Actions), and the output says what it kept. To take one away: `--permissions read` for a workspace; for an Agent, revoke the grant and grant it again.',
+    ],
     examples: [
       'frontera blueprint grant workspace Ops Customer Policy',
+      'frontera blueprint grant workspace Ops Customer --permissions read_sensitive',
       'frontera blueprint grant agent "Claims bot" Customer --revoke',
       'frontera blueprint grant list',
     ],
@@ -145,15 +188,20 @@ export const blueprintGrant: Command = {
       })
     }
 
-    const resolved = await resolveSubject(client, subject, name)
     const revoke = ctx.flags.revoke === true
+    const permissions = grantPermissions(ctx.flags.permissions, subject, revoke)
+    const resolved = await resolveSubject(client, subject, name)
+    // Each grant replaces the whole list: without --permissions, what each grant holds is read first and kept.
+    const { send, kept } = revoke || permissions
+      ? { send: new Map<string, string[] | undefined>(apiNames.map((n) => [n, permissions])), kept: {} as Record<string, string[]> }
+      : keptPermissions(apiNames, subject === 'workspace' ? await client.workspaceGrants(resolved.id) : await client.agentGrants(resolved.id))
     for (const apiName of apiNames) {
       try {
         if (subject === 'workspace') {
           if (revoke) await client.revokeWorkspace(resolved.id, apiName)
-          else await client.grantWorkspace(resolved.id, apiName)
+          else await client.grantWorkspace(resolved.id, apiName, send.get(apiName))
         } else if (revoke) await client.revokeAgent(resolved.id, apiName)
-        else await client.grantAgent(resolved.id, apiName)
+        else await client.grantAgent(resolved.id, apiName, send.get(apiName))
       } catch (err) {
         /**
          * Grants address the PUBLISHED catalog, and the draft is a different
@@ -166,6 +214,10 @@ export const blueprintGrant: Command = {
          * which step — a comprehension audit read the bare 404 as the whole
          * pipeline being broken.
          */
+        // Grants are a Blueprint Steward's to give, `read_sensitive` above all: said as that.
+        if (err instanceof CliError && err.code === 'FORBIDDEN' && permissions?.includes('read_sensitive')) {
+          throw new CliError(`${err.message} Granting ${apiName} with read_sensitive needs a Blueprint Steward.`, { code: err.code, hint: 'run it with the credential of a Blueprint Steward of this organization', cause: err })
+        }
         const notFound = err instanceof CliError && err.code === 'NOT_FOUND'
         if (!notFound) throw err
         const onDraft = await client.getObjectType(apiName).then((t) => Boolean(t?.id)).catch(() => false)
@@ -182,10 +234,12 @@ export const blueprintGrant: Command = {
       }
     }
 
+    const keptText = Object.entries(kept).map(([apiName, extras]) => `${extras.join(' and ')} on ${apiName}`).join('; ')
     return {
-      data: { subject, id: resolved.id, name: resolved.name, apiNames, revoked: revoke },
+      data: { subject, id: resolved.id, name: resolved.name, apiNames, revoked: revoke, ...(permissions ? { permissions } : {}), ...(keptText ? { kept } : {}) },
       text: `${revoke ? 'Revoked' : 'Granted'} ${apiNames.join(', ')} `
-        + `${revoke ? 'from' : 'to'} ${subject} "${resolved.name}".`,
+        + `${revoke ? 'from' : 'to'} ${subject} "${resolved.name}"${permissions ? ` (${permissions.join(', ')})` : ''}.`
+        + (keptText ? ` Kept what the grant${Object.keys(kept).length === 1 ? '' : 's'} already held: ${keptText} (\`--permissions\` sets the whole list).` : ''),
     }
   },
 }

package/src/commands/blueprint/metric.ts

@@ -0,0 +1,108 @@
+import { PlatformApi } from '../../api/platform-api'
+import { METRIC_GRAINS, metricQueryBody, metricRows, resolveRangeWindow, timeseriesOf, type RangeWindow } from '../../blueprint/metric-query'
+import { UsageError } from '../../errors'
+import { table } from '../../table'
+import { flagBool, flagString, type Command } from '../types'
+
+/**
+ * A metric's numbers, through the same route an App's `useMetric` and an
+ * Agent's `blueprint_query_metric` read: so a metric just authored can be
+ * checked from the CLI, as `blueprint query` checks an object type's rows.
+ */
+
+const list = (raw: string | undefined) => (raw === undefined ? undefined : raw.split(',').map((s) => s.trim()).filter(Boolean))
+
+function cell(value: unknown): string {
+  if (value === null || value === undefined) return ''
+  if (typeof value === 'number') return Number.isInteger(value) ? String(value) : String(Number(value.toFixed(4)))
+  if (typeof value === 'object') return JSON.stringify(value)
+  return String(value)
+}
+
+export const blueprintMetric: Command = {
+  meta: {
+    noun: 'blueprint',
+    verb: 'metric',
+    // Reads the slice granted to ONE workspace, as `blueprint query` does.
+    scope: 'workspace' as const,
+    args: [
+      { name: 'query', required: true, description: 'query (the one action)' },
+      { name: 'apiName', required: true, description: 'the metric, from `frontera blueprint list` or blueprint/metrics/<apiName>.yaml' },
+    ],
+    flags: { measure: 'string', 'group-by': 'string', grain: 'string', range: 'string', start: 'string', end: 'string', compare: 'boolean' },
+    summary: 'Query the numbers of a Blueprint metric: by grain, over a time window, grouped by its dimensions',
+    details: [
+      'Every measure the metric defines, unless `--measure a,b` names some. `--group-by d1,d2` breaks the numbers down by the metric\'s dimensions.',
+      `\`--grain\` (${METRIC_GRAINS.join(', ')}) gives a series: the metric's timeseries dimension is added to the group-by. \`--range P7D\` is a window as an ISO-8601 duration, counted back from the newest value of the metric's timeseries in the data, not from now (so a load that runs behind does not empty it); the answer says the window it covered. \`--start\` and \`--end\` give a fixed one (a date reads as its midnight UTC; the end is exclusive). \`--compare\` adds the window before: <measure>_prev, <measure>_delta and <measure>_pct.`,
+      'Reads what the workspace is granted, as `blueprint query` does: an unknown or ungranted metric is NOT_FOUND. A metric the runtime is still building says so; run it again shortly.',
+    ],
+    examples: [
+      'frontera blueprint metric query workOrderBacklog',
+      'frontera blueprint metric query workOrderBacklog --group-by state,priority',
+      'frontera blueprint metric query workOrdersOpened --grain day --range P7D',
+      'frontera blueprint metric query workOrdersOpened --range P7D --compare',
+    ],
+  },
+
+  async run(ctx) {
+    const [first, second, ...rest] = ctx.positional
+    // `metric <apiName>` reads as `metric query <apiName>`.
+    const apiName = first === 'query' ? second : first
+    const extra = first === 'query' ? rest : [second, ...rest].filter((x) => x !== undefined)
+    if (!apiName) throw new UsageError('missing <apiName>', 'frontera blueprint list — then `frontera blueprint metric query <apiName>`')
+    if (extra.length) throw new UsageError(`unexpected ${extra.join(' ')}`, 'name one metric: `frontera blueprint metric query <apiName> [--group-by …]`')
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
+    const grain = flagString(ctx, 'grain')
+    // The timeseries dimension, read only when a series is asked for.
+    let timeseries: string | null | undefined
+    let metricRow: unknown
+    if (grain !== undefined) {
+      metricRow = await api.blueprintMetric(apiName).catch(async () => {
+        const all = (await api.blueprintMetrics().catch(() => [])) as Array<{ apiName?: string }>
+        return all.find((m) => m?.apiName === apiName) ?? null
+      })
+      timeseries = metricRow ? timeseriesOf(metricRow) : undefined
+    }
+    let body
+    try {
+      body = metricQueryBody({
+        measures: list(flagString(ctx, 'measure')),
+        dimensions: list(flagString(ctx, 'group-by')),
+        grain,
+        range: flagString(ctx, 'range'),
+        from: flagString(ctx, 'start'),
+        to: flagString(ctx, 'end'),
+        compare: flagBool(ctx, 'compare') || undefined,
+      }, timeseries)
+    } catch (err) {
+      throw new UsageError((err as Error).message.replace(/^(grain|range|compare)\b/, '--$1').replace(/^from\b/, '--start').replace(/^to\b/, '--end').replace(/give a range \(P7D\) or from and to/, 'give --range (P7D) or --start and --end').replace(/as a range \(P7D\) or as from and to/, 'as --range (P7D) or as --start and --end'), 'e.g. `frontera blueprint metric query <apiName> --grain day --range P7D`')
+    }
+    const result = await api.blueprintMetricQuery(apiName, body)
+    const rows = metricRows(result)
+    // A `--range` window ends at the newest record, not at now: say which window it was.
+    const isoDuration = body.timeRange?.isoDuration
+    const window: RangeWindow | undefined = isoDuration
+      ? await resolveRangeWindow(isoDuration, {
+          metric: async () => metricRow ?? api.blueprintMetric(apiName),
+          objectTypes: () => api.blueprintObjectTypes(),
+          aggregate: (aggregate) => api.blueprintAggregate(aggregate),
+        })
+      : undefined
+    const data = window ? (Array.isArray(result) ? { data: result, window } : { ...result, window }) : result
+    const compared = !Array.isArray(result) ? (result?.compareWindow as { start?: string; end?: string } | undefined) : undefined
+    const windowLine = (window ? `\n  Window: ${window.note}` : '')
+      + (compared?.start && compared.end ? `\n  Compared with: ${compared.start} up to ${compared.end} (the _prev, _delta and _pct columns).` : '')
+    if (!rows.length) {
+      return {
+        data,
+        text: `No rows for ${apiName}${body.timeRange ? ' in that window' : ''}.${windowLine}\n  The metric's object type may have no records yet; \`frontera blueprint query <ObjectType> --limit 5\` shows whether it has.`,
+      }
+    }
+    const columns = [...new Set(rows.flatMap((r) => Object.keys(r)))]
+    const truncated = !Array.isArray(result) && result?.truncated ? '\n  Truncated: narrow the window or group by fewer dimensions.' : ''
+    return {
+      data,
+      text: `${table(columns, rows.map((r) => columns.map((c) => cell(r[c]))))}\n\n${rows.length} row${rows.length === 1 ? '' : 's'}.${windowLine}${truncated}`,
+    }
+  },
+}

package/src/commands/blueprint/object-sets.ts

@@ -0,0 +1,71 @@
+import { PlatformApi } from '../../api/platform-api'
+import { findObjectSet, normalizeObjectSets, projectObjectSetNames, type SavedObjectSet } from '../../blueprint/object-sets'
+import { CliError } from '../../errors'
+import { findSolutionRoot } from '../../local/local-project'
+import { table } from '../../table'
+import type { Command, CommandContext } from '../types'
+
+/**
+ * The saved object sets this credential can read: name, id, object type.
+ *
+ * A set is saved from a project file (`blueprint/object-sets/<name>.yaml`) by
+ * `local dev`, or in the Console, and a file or an App names it. An App's
+ * code keeps the id, a workflow file or a query the name: this is where both
+ * are read.
+ */
+export async function savedObjectSets(ctx: Pick<CommandContext, 'apiUrl' | 'token' | 'workspaceId'> & { cwd?: string }): Promise<SavedObjectSet[]> {
+  // In a project, a set a file saves is referenced by that file's name, as `status` names it.
+  const files = ctx.cwd ? projectObjectSetNames(projectRoot(ctx.cwd)) : new Map<string, string>()
+  return normalizeObjectSets(await new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId).blueprintObjectSets(), files)
+}
+
+/** The project's root when the working directory is in one with object set files; else null. */
+function projectRoot(cwd: string): string | null {
+  try {
+    return findSolutionRoot(cwd)
+  } catch {
+    return null
+  }
+}
+
+/** The set a flag names, by id, name or reference; a refusal that lists the sets otherwise. */
+export async function resolveObjectSet(ctx: Pick<CommandContext, 'apiUrl' | 'token' | 'workspaceId' | 'cwd'>, wanted: string, sets?: SavedObjectSet[]): Promise<SavedObjectSet> {
+  const all = sets ?? (await savedObjectSets(ctx))
+  const found = findObjectSet(all, wanted, projectObjectSetNames(projectRoot(ctx.cwd)))
+  if ('set' in found) return found.set
+  const listed = (found.ambiguous ?? all).slice(0, 8).map((s) => `${s.name} (${s.ref}, ${s.id})`)
+  throw new CliError(found.problem, {
+    code: found.ambiguous ? 'AMBIGUOUS_OBJECT_SET' : 'UNKNOWN_OBJECT_SET',
+    hint: all.length
+      ? `${found.ambiguous ? 'pass its id; they are' : 'the sets here are'}: ${listed.join('; ')}${all.length > 8 && !found.ambiguous ? ` and ${all.length - 8} more` : ''} — \`frontera blueprint object-sets\` lists them`
+      : 'no saved object set is readable here: add blueprint/object-sets/<name>.yaml and run `frontera local dev`, or save one in the Console',
+  })
+}
+
+export const blueprintObjectSetsList: Command = {
+  meta: {
+    noun: 'blueprint',
+    verb: 'object-sets',
+    scope: 'workspace' as const,
+    args: [],
+    flags: {},
+    summary: 'List the saved object sets: name, id, object type and the reference a file names it by',
+    details: [
+      'Pass a set to `frontera blueprint query --object-set <name|ref|id>` to read its rows. A workflow file names it as `objectSet/<ref>` or by its name; an App keeps its id.',
+    ],
+    examples: ['frontera blueprint object-sets', 'frontera blueprint object-sets --json'],
+  },
+
+  async run(ctx) {
+    const sets = await savedObjectSets(ctx)
+    return {
+      data: sets,
+      text: sets.length
+        ? table(
+            ['name', 'id', 'object type', 'kind', 'reference'],
+            sets.map((s) => [s.name, s.id, s.objectType, s.kind, s.ref]),
+          )
+        : 'No saved object sets are readable with this credential. Add blueprint/object-sets/<name>.yaml and run `frontera local dev`, or save one in the Console.',
+    }
+  },
+}

package/src/commands/blueprint/query.ts

@@ -1,9 +1,12 @@
 import { readFileSync } from 'node:fs'
 
 import { PlatformApi } from '../../api/platform-api'
+import { resolveObjectSetReferences, type SavedObjectSet } from '../../blueprint/object-sets'
 import { CliError, UsageError } from '../../errors'
+import { isUuid } from '../../local/local-sync-refs'
+import { resolveObjectSet, savedObjectSets } from './object-sets'
 import { table } from '../../table'
-import { flagString, type Command } from '../types'
+import { flagBool, flagString, flagStrings, type Command } from '../types'
 
 /**
  * Read rows through the ontology.
@@ -23,11 +26,61 @@ function api(ctx: { apiUrl: string; token: string; workspaceId?: string }): Plat
   return new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
 }
 
-/** `status:open` and `amount:>:1000` — the two forms worth typing by hand. */
+/** The operators the shorthand names, so `url:https://…` reads as an equality on `url`, not as operator `https`. */
+const WHERE_OPS = new Set(['eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'notIn', 'between', 'contains', 'startsWith', 'isNull', 'isNotNull'])
+/** Spellings a person types: `not_in` for `notIn`, `>` for `gt`. */
+const OP_ALIASES: Record<string, string> = {
+  not_in: 'notIn', notin: 'notIn', nin: 'notIn',
+  '=': 'eq', '!=': 'ne', '>': 'gt', '>=': 'gte', '<': 'lt', '<=': 'lte',
+}
+/** Operators whose value is a list: `state:in:new,assigned`, `amount:between:10,20`. */
+const LIST_OPS = new Set(['in', 'notIn', 'between'])
+
+/**
+ * A comma list, as `in`, `notIn` and `between` take one: `new,assigned`.
+ * `\,` is a comma inside a value and `\\` a backslash; a value that starts
+ * with `[` is read as a JSON array instead (`["Smith, J", "Lee"]`), which also
+ * keeps numbers and `null` as written.
+ */
+export function parseWhereList(raw: string, op: string): unknown[] {
+  const trimmed = raw.trim()
+  if (trimmed.startsWith('[')) {
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(trimmed)
+    } catch (e) {
+      throw new UsageError(`the "${op}" list is not valid JSON: ${(e as Error).message}`, 'write it as a JSON array, like ["new","assigned"], or as new,assigned')
+    }
+    if (!Array.isArray(parsed)) throw new UsageError(`the "${op}" list is not a JSON array`, 'write it as ["new","assigned"]')
+    return parsed
+  }
+  const values: string[] = []
+  let current = ''
+  for (let i = 0; i < raw.length; i += 1) {
+    const ch = raw[i]!
+    if (ch === '\\' && i + 1 < raw.length) {
+      current += raw[i + 1]
+      i += 1
+    } else if (ch === ',') {
+      values.push(current)
+      current = ''
+    } else {
+      current += ch
+    }
+  }
+  values.push(current)
+  return values.map((v) => v.trim()).filter((v) => v !== '')
+}
+
+/**
+ * `status:open`, `amount:gt:1000` and `state:in:new,assigned` — the forms worth
+ * typing by hand. The value is everything after the operator, so a time
+ * (`openedAt:gt:2026-10-01T09:00:00Z`) or a URL keeps its colons.
+ */
 export function parseWhere(raw: string): unknown {
   const trimmed = raw.trim()
   // A JSON object is passed through untouched: the shorthand covers one
-  // condition, and anything with an `and`/`or` in it needs the real grammar
+  // condition, and anything with an `or` in it needs the real grammar
   // rather than a punctuation language invented here to avoid it.
   if (trimmed.startsWith('{')) {
     try {
@@ -41,17 +94,54 @@ export function parseWhere(raw: string): unknown {
     }
   }
 
-  const parts = trimmed.split(':')
-  if (parts.length === 2) {
-    return { property: parts[0], op: 'eq', value: parts[1] }
+  const first = trimmed.indexOf(':')
+  const property = first === -1 ? '' : trimmed.slice(0, first)
+  if (!property) {
+    throw new UsageError(
+      `cannot read --where "${raw}"`,
+      'use <property>:<value>, <property>:<op>:<value>, <property>:in:<a>,<b>, or a JSON where-node',
+    )
+  }
+  const rest = trimmed.slice(first + 1)
+  const second = rest.indexOf(':')
+  const named = second === -1 ? rest : rest.slice(0, second)
+  const op = OP_ALIASES[named.toLowerCase()] ?? named
+  if (!WHERE_OPS.has(op)) {
+    // A word between two colons is an operator, and a misspelt one must not
+    // turn into an equality that quietly matches nothing.
+    if (second !== -1 && /^(?:[A-Za-z_]+|[<>=!]+)$/.test(named)) {
+      throw new UsageError(
+        `--where "${raw}": unknown operator "${named}"`,
+        `use one of ${[...WHERE_OPS].join(', ')}; for a value with a colon in it, write ${property}:eq:<value>`,
+      )
+    }
+    // No operator: the whole rest is the value of an equality (`openedAt:2026-10-01T09:00:00Z`).
+    return { property, op: 'eq', value: rest }
+  }
+  if (op === 'isNull' || op === 'isNotNull') {
+    if (second !== -1 && rest.slice(second + 1).trim() !== '') throw new UsageError(`"${op}" takes no value`, `use ${property}:${op}`)
+    return { property, op }
   }
-  if (parts.length === 3) {
-    return { property: parts[0], op: parts[1], value: parts[2] }
+  if (second === -1) {
+    // `status:in` — the operator word with nothing after it reads as the value "in"
+    // of an equality, which is what it said before operators were recognised.
+    return { property, op: 'eq', value: rest }
   }
-  throw new UsageError(
-    `cannot read --where "${raw}"`,
-    'use <property>:<value>, <property>:<op>:<value>, or a JSON where-node',
-  )
+  const value = rest.slice(second + 1)
+  if (LIST_OPS.has(op)) {
+    const values = parseWhereList(value, op)
+    if (values.length === 0) throw new UsageError(`"${op}" on "${property}" names no values`, `use ${property}:${op}:<a>,<b>`)
+    if (op === 'between' && values.length !== 2) throw new UsageError(`"between" on "${property}" takes two values, a low and a high`, `use ${property}:between:<low>,<high>`)
+    return { property, op, values }
+  }
+  return { property, op, value }
+}
+
+/** Several `--where` flags are all true at once: one condition each, ANDed. */
+export function parseWheres(raws: readonly string[]): unknown {
+  const nodes = raws.map(parseWhere)
+  if (nodes.length === 0) return null
+  return nodes.length === 1 ? nodes[0] : { and: nodes }
 }
 
 export function parseOrder(raw: string): Array<{ property: string; dir: 'asc' | 'desc' }> {
@@ -94,12 +184,16 @@ export function coerceWhereValue(value: unknown, dataType: string | undefined):
   return value
 }
 
-/** `{ property, op, value }` from the shorthand, retyped against the ontology. */
+/** `{ property, op, value }` (or `values`) from the shorthand, retyped against the ontology; `and` of them too. */
 export function typeWhereNode(node: unknown, types: Map<string, string>): unknown {
-  const condition = node as { property?: string; value?: unknown }
+  const and = (node as { and?: unknown })?.and
+  if (Array.isArray(and)) return { and: and.map((n) => typeWhereNode(n, types)) }
+  const condition = node as { property?: string; value?: unknown; values?: unknown }
   if (!condition || typeof condition !== 'object' || typeof condition.property !== 'string') return node
+  const dataType = types.get(condition.property)
+  if (Array.isArray(condition.values)) return { ...condition, values: condition.values.map((v) => coerceWhereValue(v, dataType)) }
   if (!('value' in condition)) return node
-  return { ...condition, value: coerceWhereValue(condition.value, types.get(condition.property)) }
+  return { ...condition, value: coerceWhereValue(condition.value, dataType) }
 }
 
 export function parseLimit(raw: string): number {
@@ -140,25 +234,47 @@ export const blueprintQuery: Command = {
       limit: 'string',
       'page-token': 'string',
       file: 'string',
+      'object-set': 'string',
     },
     aliases: { f: 'file' },
-    summary: 'Read rows of an object type through the ontology',
+    summary: 'Read rows of an object type, or of a saved object set, through the ontology',
+    details: [
+      '`--object-set` reads a saved object set\'s rows instead of a whole object type: name it by its name (`"Open work orders"`), the reference a file names it by (`objectSet/open-work-orders`) or its id, from `frontera blueprint object-sets`. `--where` then narrows the set.',
+      'In a `--file` query, a `{ "type": "reference", "objectSetId": … }` may name the set the same ways; the name is read as its id before the query is sent.',
+      '`--where` takes `<property>:<value>` (equality), `<property>:<op>:<value>` with op one of eq, ne, gt, gte, lt, lte, contains, startsWith, or `<property>:isNull` / `<property>:isNotNull`. `in`, `notIn` and `between` take a comma list: `--where state:in:new,assigned`, `--where amount:between:10,20`. Write `\\,` for a comma inside a value, or give the list as a JSON array: `--where \'owner:in:["Smith, J","Lee"]\'`. Repeat `--where` for conditions that must all hold; pass a JSON where-node for an `or` or a `not`.',
+      'On a date or time property, a value can be the time the query runs: `$now`, or `$now` plus or minus an amount in m (or min), h, d or w: `--where \'dueAt:lt:$now\'` (overdue), `--where \'createdAt:gt:$now-7d\'` (the last week). Quote it, so the shell leaves `$now` alone; a `--file` query takes the same value.',
+    ],
     examples: [
       'frontera blueprint query Invoice --limit 5',
+      'frontera blueprint query --object-set "Open work orders" --limit 10',
+      'frontera blueprint query --object-set objectSet/open-orders --where tier:gold',
       'frontera blueprint query Invoice --where status:open --select id,amount',
       'frontera blueprint query Invoice --order amount:desc --limit 20',
+      "frontera blueprint query WorkOrder --where 'dueAt:lt:$now'",
+      'frontera blueprint query WorkOrder --where state:in:new,assigned',
       'frontera blueprint query --file ./query.json --json',
     ],
   },
 
   async run(ctx) {
-    const apiName = ctx.positional[0]
     const file = flagString(ctx, 'file')
+    const setFlag = flagString(ctx, 'object-set')
+    if (setFlag !== undefined && !setFlag.trim()) throw new UsageError('--object-set names no set', 'frontera blueprint object-sets — then pass a name, reference or id')
+    if (setFlag && file) throw new UsageError('--object-set and --file both say what to read', 'put the set in the file as { "type": "reference", "objectSetId": "<name or id>" }, or drop --file')
+    // The sets, read once, when a name has to become an id.
+    let listed: SavedObjectSet[] | undefined
+    const sets = async () => (listed ??= await savedObjectSets(ctx))
+    const set = setFlag ? await resolveObjectSet(ctx, setFlag, await sets()) : null
+    if (set && ctx.positional[0] && set.objectType && !isUuid(set.objectType) && ctx.positional[0] !== set.objectType) {
+      throw new UsageError(`${set.name} is a set of ${set.objectType}, not ${ctx.positional[0]}`, `drop <apiName>, or pass ${set.objectType}`)
+    }
+    // A set's object type is what its rows are: the shorthand's values are typed against it.
+    const apiName = ctx.positional[0] ?? (set && !isUuid(set.objectType) ? set.objectType : undefined)
 
-    if (!apiName && !file) {
+    if (!apiName && !file && !set) {
       throw new UsageError(
         'missing <apiName>',
-        'frontera blueprint list — then `frontera blueprint query <apiName>`',
+        'frontera blueprint list — then `frontera blueprint query <apiName>`; or `frontera blueprint object-sets`, then `--object-set <name>`',
       )
     }
 
@@ -184,17 +300,19 @@ export const blueprintQuery: Command = {
           'the minimum is { "objectSet": { "type": "base", "objectType": "Invoice" } }',
         )
       }
-      body = doc as typeof body
+      // A set named in words (`objectSet/open-work-orders`, `Open work orders`) is sent as its id.
+      body = (await resolveObjectSetReferences(doc, async (name) => (await resolveObjectSet(ctx, name, await sets())).id)) as typeof body
     } else {
-      const where = flagString(ctx, 'where')
-      let node = where ? parseWhere(where) : null
+      // Every `--where` holds: repeated, they are ANDed (the last one alone used to win, silently).
+      const wheres = flagStrings(ctx, 'where')
+      let node = parseWheres(wheres)
 
       // One extra read, and only when the shorthand is used: the flag carries
       // a string and the compiler is typed, so the property's declared type is
       // what makes `--where salesIdr:gt:9000000` a number rather than a 400.
       // A JSON where-node is already typed by whoever wrote it, and is left
       // exactly as given.
-      if (node && where && !where.trim().startsWith('{')) {
+      if (node && wheres.some((w) => !w.trim().startsWith('{')) && apiName) {
         const shape = (await api(ctx).blueprintObjectType(apiName!)) as {
           properties?: Array<{ apiName?: string; dataType?: string }>
         }
@@ -202,14 +320,13 @@ export const blueprintQuery: Command = {
         for (const p of shape?.properties ?? []) {
           if (p.apiName && p.dataType) types.set(p.apiName, p.dataType)
         }
-        node = typeWhereNode(node, types)
+        node = wheres.length === 1
+          ? typeWhereNode(node, types)
+          : { and: wheres.map((w, i) => (w.trim().startsWith('{') ? (node as { and: unknown[] }).and[i] : typeWhereNode((node as { and: unknown[] }).and[i], types))) }
       }
 
-      body = {
-        objectSet: node
-          ? { type: 'filter', objectSet: { type: 'base', objectType: apiName }, where: node }
-          : { type: 'base', objectType: apiName },
-      }
+      const from = set ? { type: 'reference', objectSetId: set.id } : { type: 'base', objectType: apiName }
+      body = { objectSet: node ? { type: 'filter', objectSet: from, where: node } : from }
     }
 
     const select = flagString(ctx, 'select')
@@ -221,7 +338,14 @@ export const blueprintQuery: Command = {
     const pageToken = flagString(ctx, 'page-token')
     if (pageToken) body.pageToken = pageToken
 
-    const result = await api(ctx).blueprintQuery(body)
+    // JSON is read by code that may go on to submit an Action: each row says its record version
+    // (`_meta.recordVersion`). A runtime that predates the flag is asked again without it.
+    if (flagBool(ctx, 'json')) body.recordVersions = true
+    const result = await api(ctx).blueprintQuery(body).catch(async (err: unknown) => {
+      if (!body.recordVersions || !/recordVersions/.test(String((err as Error)?.message ?? ''))) throw err
+      delete body.recordVersions
+      return api(ctx).blueprintQuery(body)
+    })
     const rows = result.rows ?? []
 
     if (rows.length === 0) {
@@ -231,7 +355,7 @@ export const blueprintQuery: Command = {
         // names the two things that produce one rather than printing "0 rows".
         text:
           'No rows.\n'
-          + '  The object type may have no dataset binding yet, or the filter matched nothing.\n'
+          + (set ? `  The set ${set.name} has no rows now, or the filter matched nothing.\n` : '  The object type may have no dataset binding yet, or the filter matched nothing.\n')
           + `  Check the binding with \`frontera blueprint get ${apiName ?? '<apiName>'}\`.`,
       }
     }