@configdirector/cli 0.22.0 → 0.23.0

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to `@configdirector/cli` are documented here. The format fol
 
 ## [Unreleased]
 
+## [0.23.0] - 2026-11-12
+
+### Added
+
+- `configdirector metrics create` takes `--filter <file>`, or `--filter -` for stdin, a JSON file holding the conditions on an event's details that the event must match to count for the metric, such as only the checkouts on the Team plan, in the shape `metrics get --json` prints a metric's `filter` in. It also takes `--value-field <pointer>`, the field of the event's details whose number value per context sums in place of the event's value, with `--kind value-per-context`. A metric keeps both for its whole life, and a run counts it from the moment it is attached to the experiment.
+- `configdirector metrics get`, `metrics update` and `metrics delete` take `--id <metric id>` in place of the event name, to name one of several metrics with the same event name.
+
+### Changed
+
+- `configdirector metrics get`, `metrics update` and `metrics delete` change nothing when several metrics have the event name you give: they list the metrics with their IDs and exit with 2. Earlier versions act on the first metric ConfigDirector lists for the event name, so once a project has several metrics on one event name, their `metrics update` and `metrics delete` can change or delete another metric than the one you mean. Upgrade every CLI that changes metrics before you create a second metric on an event name.
+- `configdirector metrics list`, `metrics get`, `metrics create`, `metrics update`, `metrics delete` and `configs runs` name a metric by its event name, then its filter's conditions, then its value field, as in `checkout_completed · /plan is one of [team] · value from /items`. The first column of `metrics list` is headed `METRIC`.
+- `configdirector configs runs` says since when a run counted a metric with a filter or a value field that was attached to the experiment while the run was going, under each of the metric's kinds, and that events reported before then are not in its numbers. For such a metric that was not attached while the run was open, it says the run did not count it and shows no numbers. `--json` prints the Admin API's response as received, as before.
+- `configdirector metrics delete --json` prints the deleted metric's `deletedMetricId` beside its `deletedEventName`.
+
 ## [0.22.0] - 2026-11-11
 
 ### Added

package/README.md

@@ -183,6 +183,7 @@ configdirector segments list
 configdirector segments get <key>
 configdirector metrics list
 configdirector metrics get <event name>
+configdirector metrics get --id <metric id>
 ```
 
 `projects list` lists your organization's projects with their slugs and names, whichever project is selected. The other commands read the project from `--project`, `CONFIGDIRECTOR_PROJECT` or `configdirector.json`, as `scan` does:
@@ -192,7 +193,7 @@ configdirector metrics get <event name>
 - `configs get <key>` shows the config's settings, including its type's constraints, then each environment's targeting rules in order, written as `evaluate` writes them, with the default targeting rule value last. An old key works, and the output then starts with a line naming the current key.
 - `configs activity <key>` shows when SDKs last evaluated the config, one line per environment, SDK key kind, SDK name and SDK version, with the time in UTC.
 - `segments list` lists the segments with how many configs use each, and `segments get <key>` shows a segment's condition groups and its environment overrides.
-- `metrics list` lists the metrics with their kinds, their direction and how many experiments use each, and `metrics get <event name>` shows a metric's kinds and direction, and each experiment that uses it, with its role and the environments of its runs in progress.
+- `metrics list` lists the metrics with their kinds, their direction and how many experiments use each, and `metrics get <event name>` shows a metric's kinds and direction, and each experiment that uses it, with its role and the environments of its runs in progress. Both name a metric by its event name, then its filter's conditions, then its value field, as in `checkout_completed · /plan is one of [team] · value from /items`. When several metrics have the event name, `metrics get` lists them with their IDs and exits with 2, and `metrics get --id <metric id>` shows one of them.
 
 ```txt
 new-checkout
@@ -218,7 +219,7 @@ On an experiment, each value comes after the name of its variation, as in `40% g
 
 `projects list`, `environments list`, `configs list`, `configs activity`, `segments list` and `metrics list` print a header row that names their columns above their lines, such as `KEY   TYPE   ROLE   LIFETIME   STATE` for `configs list`, and `--no-headers` leaves it out. An empty list prints only a sentence, such as `No configs found in web-app.`
 
-With `--json`, each prints the Admin API's response as received, except `configs list --state`, which prints only the configs in that state, and `metrics get`, which prints the metric as the Admin API listed it for its event name. A key no config or segment has, or an event name no metric has, exits with 2.
+With `--json`, each prints the Admin API's response as received, except `configs list --state`, which prints only the configs in that state, and `metrics get`, which prints the metric as the Admin API listed it for its event name, or returned it for its ID. A key no config or segment has, or an event name or ID no metric has, exits with 2.
 
 `projects list` needs `projects:read`. The others need `projects:read` to find the project, and `environments list` needs `environments:read`, `configs list`, `configs get` and `configs activity` need `configs:read`, plus `tags:read` for `--tag`, `segments list` and `segments get` need `segments:read`, and `metrics list` and `metrics get` need `metrics:read`. Without `segments:read`, `configs get` shows a segment condition's segment ID instead of its name; without `environments:read`, `segments get` names an override's environment by its ID instead of its slug, and `metrics get` a run's environment.
 
@@ -358,7 +359,18 @@ Running since 2026-11-03 12:00 UTC
   Results can be up to 25 minutes behind.
 ```
 
-Each kind a metric reports gets a line with the metric's role, its event name, the kind and its direction, then one row per variation, the control first: its value, and for every other variation the lift against the control with the range it is likely in, the chance to beat control and the verdict, `likely better`, `likely worse` or `no clear difference`. With three or more variations, each row also shows the variation's chance to be best. Until every variation has enough exposures, the rollout says the run needs more exposures and shows the values alone. While a run is going, `How long to run` follows the primary metric's results: for a real lift of 2%, 5%, 10%, 20% and 50%, in the metric's better direction, the exposures so far against those needed before a variation with that lift has a good chance of reading likely better, and about how many days remain at the pace of new exposures since the time it names. An ended run's last line says when its final results were taken, once they are in. A run also shows its hypothesis and the note it ended with, and lists the events sent with `track` during the run that no metric measures.
+Each kind a metric reports gets a line with the metric's role, its name, the kind and its direction, then one row per variation, the control first: its value, and for every other variation the lift against the control with the range it is likely in, the chance to beat control and the verdict, `likely better`, `likely worse` or `no clear difference`. With three or more variations, each row also shows the variation's chance to be best. Until every variation has enough exposures, the rollout says the run needs more exposures and shows the values alone. While a run is going, `How long to run` follows the primary metric's results: for a real lift of 2%, 5%, 10%, 20% and 50%, in the metric's better direction, the exposures so far against those needed before a variation with that lift has a good chance of reading likely better, and about how many days remain at the pace of new exposures since the time it names. An ended run's last line says when its final results were taken, once they are in. A run also shows its hypothesis and the note it ended with, and lists the events sent with `track` during the run that no metric measures.
+
+A run counts a metric with a filter or a value field from the moment it is attached to the experiment. When that was during the run, a line under each of the metric's kinds says since when, and that events reported before then are not in its numbers. When the metric was not attached while the run was open, the run shows the metric's line and says it did not count it, with no numbers:
+
+```txt
+    Secondary metric: checkout_completed · /plan is one of [team], conversion, higher is better
+      Counted since 2026-11-05 09:30 UTC, when this metric was attached to the experiment. Events reported before then are not in these numbers.
+      control (Start free trial)              2.1%   control
+      treatment-a (Try it free for 14 days)   3.0%   +43% (-5% to +110%)   91% chance to beat control   no clear difference
+    Guardrail: checkout_completed · value from /refunded, lower is better
+      This run did not count this metric: a metric with a filter or a value field is counted from the moment it is attached to an experiment, and this one was not attached while the run was open.
+```
 
 - `configs ship` serves one variation to everyone in the environment and ends the run. `--variation` takes its name or its ID. The default targeting rule value becomes the variation's value, every percentage rollout is removed, including one a conditional rule serves, and a conditional rule serving a single value stays.
 - `configs stop` ends the run without choosing a variation: every percentage rollout is removed, including one a conditional rule serves, and the default targeting rule value and any conditional rule serving a single value stay.
@@ -426,17 +438,38 @@ configdirector segments delete beta-testers
 
 ```bash
 configdirector metrics create --event-name checkout_completed --kind conversion --kind value-per-context --direction higher-is-better
+configdirector metrics create --event-name checkout_completed --filter team-plan.json --value-field /items --kind value-per-context --direction higher-is-better
 configdirector metrics update checkout_completed --direction lower-is-better
-configdirector metrics delete checkout_completed
+configdirector metrics delete --id 4f5a6b7c-8d9e-4f0a-9b1c-3d4e5f6a7b8c
 ```
 
-A metric is what an experiment measures: an event name the application sends with the SDK's `track` call, the numbers it reports and whether a higher or a lower number is better. A project has one metric per event name, and the commands name a metric by its event name. Attaching metrics to an experiment happens on its Settings tab in the dashboard, or through the Admin API or the MCP server.
+A metric is what an experiment measures: the events with one name the application sends with the SDK's `track` call, all of them or only those whose details match the metric's filter, the numbers it reports and whether a higher or a lower number is better. A project can have several metrics on one event name, told apart by their filter and value field, and the commands name a metric by its event name, then its filter's conditions, then its value field, as in `checkout_completed · /plan is one of [team] · value from /items`. Attaching metrics to an experiment happens on its Settings tab in the dashboard, or through the Admin API or the MCP server.
 
 - `metrics create` needs `--event-name`, exactly as the application passes it to `track`; `--kind`, repeatable: `conversion`, `count-per-context` or `value-per-context`; and `--direction`: `higher-is-better` or `lower-is-better`. `--description <text>` is optional. It prints `Created metric checkout_completed in web-app.`, then the metric as `metrics get` shows it.
-- `metrics update <event name>` changes what its options name: `--kind`, repeated, replaces the kinds, and `--direction` and `--description` replace theirs; `--description ""` removes the description. A metric keeps its event name. Removing a kind an experiment's primary metric decides on is refused, and the command exits with 2 listing those experiments.
-- `metrics delete <event name>` deletes the metric and detaches it from the experiments that use it, and prints `Deleted metric checkout_completed from web-app.`; `--json` prints `{ "deletedEventName": "checkout_completed" }` with the event name as given. While an experiment that uses the metric has a run in progress, it is not deleted: the command exits with 2 and lists each experiment with the environments of its runs.
+- `metrics create --filter <file>`, or `--filter -` for stdin, counts only the events whose details match every condition in the file, 1 to 5 of them, in the shape `metrics get --json` prints a metric's `filter` in:
+
+  ```json
+  [{ "field": "/plan", "targetType": "text", "operator": "is one of", "targetValues": ["team"] }]
+  ```
+
+  `field` is a JSON pointer into the details the application sends with the event. A `text` condition takes `is one of` or `is NOT one of`; a `number` condition takes `=`, `!=`, `>`, `>=`, `<` or `<=`, with its number as text, such as `"2"`; and a `boolean` condition takes `equals`, with `"true"` or `"false"`. A condition means what it means in a targeting rule, so a field an event lacks reads as empty text, and `is NOT one of` and `!=` count an event without it.
+
+- `metrics create --value-field <pointer>` sums the number at that field of the event's details for value per context, in place of the event's value, and needs `--kind value-per-context`.
+- A metric keeps its filter and value field for its whole life: for others, create another metric. A run counts a metric with a filter or a value field from the moment it is attached to the experiment.
+- `metrics update <event name>` changes what its options name: `--kind`, repeated, replaces the kinds, and `--direction` and `--description` replace theirs; `--description ""` removes the description. A metric keeps its event name, filter and value field. Removing a kind an experiment's primary metric decides on is refused, and the command exits with 2 listing those experiments.
+- `metrics delete <event name>` deletes the metric and detaches it from the experiments that use it, and prints `Deleted metric checkout_completed from web-app.`; `--json` prints `{ "deletedMetricId": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "deletedEventName": "checkout_completed" }`. While an experiment that uses the metric has a run in progress, it is not deleted: the command exits with 2 and lists each experiment with the environments of its runs.
+
+`metrics update` and `metrics delete` take the event name while only one metric has it. When several metrics have it, they change nothing: they list the metrics with their IDs and exit with 2, and `--id <metric id>` names one of them:
+
+```txt
+Error: 2 metrics in web-app have the event name "checkout_completed". Name one with --id:
+  1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f   checkout_completed
+  4f5a6b7c-8d9e-4f0a-9b1c-3d4e5f6a7b8c   checkout_completed · /plan is one of [team]
+```
+
+Versions of the CLI before 0.23.0 act on the first metric ConfigDirector lists for an event name, so once a project has several metrics on one event name, their `metrics update` and `metrics delete` can change or delete another metric than the one you mean. Upgrade every CLI that changes metrics before you create a second metric on an event name.
 
-None of them asks for confirmation. An event name no metric has exits with 2 for `update` and `delete`, and so does a metric ConfigDirector refuses, such as a second metric for an event name. With `--json`, `create` and `update` print the metric as the Admin API returned it.
+None of them asks for confirmation. An event name or ID no metric has exits with 2 for `update` and `delete`, and so does a metric ConfigDirector refuses, such as one with the same event name, filter and value field as another. With `--json`, `create` and `update` print the metric as the Admin API returned it.
 
 `metrics create` needs `projects:read` and `metrics:create`, `metrics update` needs `projects:read`, `metrics:read` and `metrics:update`, and `metrics delete` needs `projects:read`, `metrics:read` and `metrics:delete`. Without `environments:read`, `metrics update` and `metrics delete` name environments by ID instead of by slug. The change shows in the audit log with the source CLI.
 
@@ -466,7 +499,7 @@ It asks for no confirmation and does not check whether the code still reads the
 | `--project <slug>`            | `CONFIGDIRECTOR_PROJECT`      | Project slug. Without either, every command that reads a project uses the `project` in `configdirector.json`.                                                     |
 | `--json`                      |                               | Print JSON on stdout. Errors always go to stderr.                                                                                                                 |
 
-The command exits with 0 when it succeeds, 1 when `validate` found a problem or `configs create` found a config that already has the key, and 2 when it could not run: a usage mistake, a rejected token, a suspended service, an unreachable API, or something the command names that does not exist, such as a config key, an environment, a saved context, a segment key, a tag or a scanned repository. `segments delete` also exits with 2 when the targeting rules of a config use the segment. A CI job can therefore tell a wrong config key from an outage.
+The command exits with 0 when it succeeds, 1 when `validate` found a problem or `configs create` found a config that already has the key, and 2 when it could not run: a usage mistake, a rejected token, a suspended service, an unreachable API, or something the command names that does not exist, such as a config key, an environment, a saved context, a segment key, a tag or a scanned repository. `segments delete` also exits with 2 when the targeting rules of a config use the segment. `metrics get`, `metrics update` and `metrics delete` also exit with 2 when several metrics have the event name they are given. A CI job can therefore tell a wrong config key from an outage.
 
 ## License
 

package/dist/configdirector.mjs

@@ -7,14 +7,14 @@ import * as v from "valibot";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { mkdir, open, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { createInterface } from "node:readline";
+import { randomUUID } from "node:crypto";
+import { text } from "node:stream/consumers";
 import ignore from "ignore";
 import picomatch from "picomatch";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { randomUUID } from "node:crypto";
-import { text } from "node:stream/consumers";
 //#region package.json
-var version = "0.22.0";
+var version = "0.23.0";
 //#endregion
 //#region src/CliError.ts
 var CliError = class extends Error {
@@ -121,6 +121,48 @@ const CopyPlanSchema = v.object({
 });
 const CopyPlanResponseSchema = v.object({ plan: CopyPlanSchema });
 //#endregion
+//#region src/admin-api/metrics.ts
+const OpenRunsSchema = v.array(v.object({ environmentId: v.string() }));
+const MetricUsageSchema = v.object({
+	configKey: v.string(),
+	role: v.string(),
+	primaryKind: v.nullable(v.string()),
+	openRuns: OpenRunsSchema
+});
+const MetricFilterConditionSchema = v.object({
+	field: v.string(),
+	targetType: v.string(),
+	operator: v.string(),
+	targetValues: v.array(v.string())
+});
+const MetricFilterSchema = v.nullable(v.array(MetricFilterConditionSchema));
+const MetricSchema = v.object({
+	id: v.string(),
+	eventName: v.string(),
+	filter: MetricFilterSchema,
+	valueField: v.nullable(v.string()),
+	description: v.nullable(v.string()),
+	direction: v.string(),
+	kinds: v.array(v.string()),
+	usages: v.array(MetricUsageSchema)
+});
+const DecidingExperimentSchema = v.object({
+	configKey: v.string(),
+	primaryKind: v.string()
+});
+const MetricKindInUseBodySchema = v.object({
+	code: v.literal("METRIC_KIND_IN_USE"),
+	usages: v.array(DecidingExperimentSchema)
+});
+const ExperimentWithOpenRunsSchema = v.object({
+	configKey: v.string(),
+	openRuns: OpenRunsSchema
+});
+const MetricInUseBodySchema = v.object({
+	code: v.literal("METRIC_IN_USE"),
+	usages: v.array(ExperimentWithOpenRunsSchema)
+});
+//#endregion
 //#region src/admin-api/experiment-runs.ts
 const TimestampSchema = v.pipe(v.string(), v.isoTimestamp());
 const RolloutExposuresSchema = v.object({
@@ -164,8 +206,19 @@ const MetricKindResultSchema = v.object({
 		runLengthEstimate: v.optional(RunLengthEstimateSchema)
 	}))
 });
+const CountingSchema = v.variant("kind", [
+	v.object({ kind: v.literal("whole-run") }),
+	v.object({
+		kind: v.literal("since"),
+		since: TimestampSchema
+	}),
+	v.object({ kind: v.literal("not-counted") })
+]);
 const MetricResultSchema = v.object({
 	eventName: v.string(),
+	filter: MetricFilterSchema,
+	valueField: v.nullable(v.string()),
+	counting: CountingSchema,
 	direction: v.string(),
 	kinds: v.array(MetricKindResultSchema)
 });
@@ -206,39 +259,6 @@ const ExperimentRunSchema = v.object({
 });
 const ExperimentRunsSchema = v.array(ExperimentRunSchema);
 //#endregion
-//#region src/admin-api/metrics.ts
-const OpenRunsSchema = v.array(v.object({ environmentId: v.string() }));
-const MetricUsageSchema = v.object({
-	configKey: v.string(),
-	role: v.string(),
-	primaryKind: v.nullable(v.string()),
-	openRuns: OpenRunsSchema
-});
-const MetricSchema = v.object({
-	id: v.string(),
-	eventName: v.string(),
-	description: v.nullable(v.string()),
-	direction: v.string(),
-	kinds: v.array(v.string()),
-	usages: v.array(MetricUsageSchema)
-});
-const DecidingExperimentSchema = v.object({
-	configKey: v.string(),
-	primaryKind: v.string()
-});
-const MetricKindInUseBodySchema = v.object({
-	code: v.literal("METRIC_KIND_IN_USE"),
-	usages: v.array(DecidingExperimentSchema)
-});
-const ExperimentWithOpenRunsSchema = v.object({
-	configKey: v.string(),
-	openRuns: OpenRunsSchema
-});
-const MetricInUseBodySchema = v.object({
-	code: v.literal("METRIC_IN_USE"),
-	usages: v.array(ExperimentWithOpenRunsSchema)
-});
-//#endregion
 //#region src/admin-api/config-creation.ts
 const CreatedConfigSchema = v.object({
 	key: v.string(),
@@ -717,14 +737,16 @@ var AdminApiClient = class {
 	listMetrics(projectId) {
 		return this.get(`/v1/projects/${encodeURIComponent(projectId)}/metrics`, v.array(MetricSchema));
 	}
-	async findMetricByEventName(projectId, eventName) {
+	async listMetricsWithEventName(projectId, eventName) {
 		const { parsedBody: metrics, responseBody } = await this.get(`/v1/projects/${encodeURIComponent(projectId)}/metrics?${new URLSearchParams({ eventName })}`, v.array(MetricSchema));
-		const index = metrics.findIndex((metric) => metric.eventName === eventName);
-		const metric = metrics[index];
-		return metric === void 0 ? void 0 : {
+		const receivedMetrics = v.parse(v.array(v.unknown()), responseBody);
+		return metrics.flatMap((metric, index) => metric.eventName === eventName ? [{
 			parsedBody: metric,
-			responseBody: v.parse(v.array(v.unknown()), responseBody)[index]
-		};
+			responseBody: receivedMetrics[index]
+		}] : []);
+	}
+	getMetric(projectId, metricId) {
+		return this.getIfFound(`/v1/projects/${encodeURIComponent(projectId)}/metrics/${encodeURIComponent(metricId)}`, MetricSchema);
 	}
 	createMetric(projectId, request) {
 		return this.requestJson(`/v1/projects/${encodeURIComponent(projectId)}/metrics`, MetricSchema, {
@@ -1627,6 +1649,33 @@ const kindWords = (kind) => isMetricKind(kind) ? KIND_WORDS[kind] : kind;
 const directionWords = (direction) => isOneOf(METRIC_DIRECTIONS, direction) ? DIRECTION_WORDS[direction] : direction;
 const roleWords = (role) => isOneOf(METRIC_ROLES, role) ? ROLE_WORDS[role] : role;
 //#endregion
+//#region src/metrics/metric-label.ts
+const FILTER_TARGET_TYPES = [
+	"text",
+	"number",
+	"boolean"
+];
+const comparisonWithTargetValueList = (condition) => `${condition.operator} [${condition.targetValues.join(", ")}]`;
+const COMPARISON_WORDS = {
+	text: comparisonWithTargetValueList,
+	number: (condition) => `${condition.operator} ${condition.targetValues[0] ?? ""}`,
+	boolean: (condition) => `is ${condition.targetValues[0] ?? ""}`
+};
+const conditionWords = (condition) => {
+	const comparison = isOneOf(FILTER_TARGET_TYPES, condition.targetType) ? COMPARISON_WORDS[condition.targetType](condition) : comparisonWithTargetValueList(condition);
+	return `${condition.field} ${comparison}`;
+};
+const metricLabel = (metric) => {
+	const conditions = (metric.filter ?? []).map(conditionWords);
+	const filterWords = conditions.length === 0 ? [] : [conditions.join(" and ")];
+	const valueFieldWords = metric.valueField === null ? [] : [`value from ${metric.valueField}`];
+	return [
+		metric.eventName,
+		...filterWords,
+		...valueFieldWords
+	].join(" · ");
+};
+//#endregion
 //#region src/configs/run-results-text.ts
 const VERDICT_WORDS = {
 	"likely-better": "likely better",
@@ -1730,7 +1779,8 @@ const runLengthEstimateLines = (estimate) => {
 		"Whatever the estimate says, a run should cover at least one full week, so every day of the week is in the result."
 	];
 };
-const kindResultLines = (role, metric, kindResult, rollout, variations) => {
+const roleAndMetric = (role, metric) => `${capitalized(roleWords(role))}: ${metricLabel(metric)}`;
+const kindResultLines = (role, metric, kindResult, rollout, variations, countingLines) => {
 	const kindResultOfRollout = kindResult.rollouts.find((candidate) => candidate.ruleId === rollout.ruleId);
 	if (kindResultOfRollout === void 0) return [];
 	const variationResults = kindResultOfRollout.variations;
@@ -1742,11 +1792,23 @@ const kindResultLines = (role, metric, kindResult, rollout, variations) => {
 		showsChanceToBeBest: variationResults.some((variation) => variation.chanceToBeBest !== void 0)
 	};
 	return [
-		`${capitalized(roleWords(role))}: ${metric.eventName}, ${kindWords(kindResult.kind)}, ${directionWords(metric.direction)}`,
+		`${roleAndMetric(role, metric)}, ${kindWords(kindResult.kind)}, ${directionWords(metric.direction)}`,
+		...countingLines,
 		...alignedColumns(variationResults.map((variation) => resultRow(variation, table))).map((line) => `  ${line}`.trimEnd()),
 		...runLengthEstimateLines(kindResultOfRollout.runLengthEstimate)
 	];
 };
+const NOT_COUNTED_LINE = "  This run did not count this metric: a metric with a filter or a value field is counted from the moment it is attached to an experiment, and this one was not attached while the run was open.";
+const countedSinceLine = (since) => `  Counted since ${utcMinute(since)}, when this metric was attached to the experiment. Events reported before then are not in these numbers.`;
+const metricResultLines = (role, metric, rollout, variations) => {
+	const kindResultsWith = (countingLines) => metric.kinds.flatMap((kindResult) => kindResultLines(role, metric, kindResult, rollout, variations, countingLines));
+	const { counting } = metric;
+	switch (counting.kind) {
+		case "whole-run": return kindResultsWith([]);
+		case "since": return kindResultsWith([countedSinceLine(counting.since)]);
+		case "not-counted": return [`${roleAndMetric(role, metric)}, ${directionWords(metric.direction)}`, NOT_COUNTED_LINE];
+	}
+};
 const crossoverLines = (crossovers) => {
 	if (crossovers === 0) return [];
 	return [crossovers === 1 ? "1 context was exposed to more than one variation and is left out of every metric." : `${crossovers} contexts were exposed to more than one variation and are left out of every metric.`];
@@ -1771,7 +1833,7 @@ const rolloutResultLines = (runResults, ruleId, variations) => {
 			return [
 				...comparisonLines(comparisonOf(rollout)),
 				...crossoverLines(rollout.crossovers),
-				...METRIC_ROLES.flatMap((role) => results[role].flatMap((metric) => metric.kinds.flatMap((kindResult) => kindResultLines(role, metric, kindResult, rollout, variations))))
+				...METRIC_ROLES.flatMap((role) => results[role].flatMap((metric) => metricResultLines(role, metric, rollout, variations)))
 			];
 		}
 	}
@@ -2658,6 +2720,43 @@ const metricChangesOf = (options) => {
 	return changes;
 };
 //#endregion
+//#region src/metrics/metric-selection.ts
+const metricSelectionOf = (eventName, options) => {
+	if (eventName !== void 0 && options.id !== void 0) throw new CliError("Name the metric by its event name or by its id with --id, not both.");
+	if (eventName !== void 0) return {
+		by: "event-name",
+		eventName
+	};
+	if (options.id !== void 0) return {
+		by: "id",
+		metricId: options.id
+	};
+	throw new CliError("Name the metric by its event name, or by its id with --id.");
+};
+const noSelectedMetric = (project, selection) => {
+	switch (selection.by) {
+		case "event-name": return new CliError(`No metric in ${project.slug} has the event name "${selection.eventName}".`);
+		case "id": return new CliError(`No metric in ${project.slug} has the id "${selection.metricId}".`);
+	}
+};
+const severalMetricsWithEventName = (project, eventName, metrics) => new CliError([`${metrics.length} metrics in ${project.slug} have the event name "${eventName}". Name one with --id:`, ...alignedColumns(metrics.map((metric) => [metric.id, metricLabel(metric)])).map((line) => `  ${line}`)].join("\n"));
+const onlyMetricWithEventName = (project, selection, metricsWithEventName) => {
+	const [onlyMetric, ...otherMetrics] = metricsWithEventName;
+	if (onlyMetric === void 0) throw noSelectedMetric(project, selection);
+	if (otherMetrics.length > 0) throw severalMetricsWithEventName(project, selection.eventName, metricsWithEventName.map((metric) => metric.parsedBody));
+	return onlyMetric;
+};
+const findSelectedMetric = async (client, project, selection) => {
+	switch (selection.by) {
+		case "event-name": return onlyMetricWithEventName(project, selection, await client.listMetricsWithEventName(project.id, selection.eventName));
+		case "id": {
+			const metric = await client.getMetric(project.id, selection.metricId);
+			if (metric === void 0) throw noSelectedMetric(project, selection);
+			return metric;
+		}
+	}
+};
+//#endregion
 //#region src/metrics/metric-text.ts
 const openRunEnvironmentNames = (openRuns, environmentSlugs) => openRuns.map((run) => environmentSlugs.get(run.environmentId) ?? run.environmentId).join(", ");
 const usageLine$1 = (usage, environmentSlugs) => {
@@ -2667,7 +2766,7 @@ const usageLine$1 = (usage, environmentSlugs) => {
 };
 const usageLines = (metric, environmentSlugs) => metric.usages.length === 0 ? ["No experiment uses it."] : ["Used by", ...metric.usages.map((usage) => usageLine$1(usage, environmentSlugs))];
 const metricText = (metric, environmentSlugs) => [
-	metric.eventName,
+	metricLabel(metric),
 	...metric.description === null ? [] : [`  Description: ${metric.description}`],
 	`  Kinds: ${metric.kinds.map(kindWords).join(", ")}`,
 	`  Direction: ${directionWords(metric.direction)}`,
@@ -2676,9 +2775,49 @@ const metricText = (metric, environmentSlugs) => [
 	""
 ].join("\n");
 //#endregion
+//#region src/request-file.ts
+const STANDARD_INPUT_ARGUMENT = "-";
+const readRequestSource = async (argumentLabel, argument, invocation) => {
+	if (argument === STANDARD_INPUT_ARGUMENT) return {
+		origin: `${argumentLabel} reads stdin`,
+		contents: await text(invocation.stdin)
+	};
+	const { file, contents } = await readOptionFile(argumentLabel, argument, invocation.workingDirectory);
+	return {
+		origin: `${argumentLabel} names ${file}`,
+		contents
+	};
+};
+const readRequestJson = async (argumentLabel, argument, invocation) => {
+	const { origin, contents } = await readRequestSource(argumentLabel, argument, invocation);
+	return {
+		origin,
+		request: parseJson(contents)
+	};
+};
+const readRequestFile = async (argumentLabel, argument, invocation, expectedFormatSentence) => {
+	const { origin, request } = await readRequestJson(argumentLabel, argument, invocation);
+	if (!isJsonObject(request)) throw new CliError(`${origin}, which does not hold a JSON object. ${expectedFormatSentence}`);
+	return request;
+};
+const readRequestListFile = async (argumentLabel, argument, invocation, expectedFormatSentence) => {
+	const { origin, request } = await readRequestJson(argumentLabel, argument, invocation);
+	if (!Array.isArray(request)) throw new CliError(`${origin}, which does not hold a JSON array. ${expectedFormatSentence}`);
+	return request;
+};
+const withId = (entry) => entry.id === void 0 ? {
+	id: randomUUID(),
+	...entry
+} : entry;
+//#endregion
+//#region src/metrics/filter-file.ts
+const readFilterFile = (filterArgument, invocation) => readRequestListFile("--filter", filterArgument, invocation, "It takes the conditions an event's details must match, such as [{\"field\": \"/plan\", \"targetType\": \"text\", \"operator\": \"is one of\", \"targetValues\": [\"team\"]}], like the filter that metrics get --json prints.");
+//#endregion
 //#region src/metrics/new-metric.ts
-const newMetricOf = (options) => ({
+const newMetricOf = async (options, invocation) => ({
 	eventName: options.eventName,
+	...options.filter === void 0 ? {} : { filter: await readFilterFile(options.filter, invocation) },
+	...options.valueField === void 0 ? {} : { valueField: options.valueField },
 	kinds: options.kind,
 	direction: options.direction,
 	...options.description === void 0 ? {} : { description: options.description }
@@ -2687,13 +2826,13 @@ const newMetricOf = (options) => ({
 //#region src/commands/metrics.ts
 const usageDescription$1 = (metric) => `used by ${metric.usages.length} ${plural(metric.usages.length, "experiment", "experiments")}`;
 const METRIC_HEADER_ROW = [
-	"EVENT NAME",
+	"METRIC",
 	"KINDS",
 	"DIRECTION",
 	"USED BY"
 ];
 const metricLines = (projectSlug, metrics, options) => metrics.length === 0 ? [`No metrics found in ${projectSlug}.`] : alignedListing(METRIC_HEADER_ROW, metrics.map((metric) => [
-	metric.eventName,
+	metricLabel(metric),
 	metric.kinds.map(kindWords).join(", "),
 	directionWords(metric.direction),
 	usageDescription$1(metric)
@@ -2708,12 +2847,10 @@ const listMetrics = async (context, _commandArguments, options) => {
 	};
 };
 const openRunEnvironmentSlugsOf = async (client, project, metric) => metric.usages.some((usage) => usage.openRuns.length > 0) ? environmentSlugsById(client, project) : /* @__PURE__ */ new Map();
-const noMetricWithEventName = (project, eventName) => new CliError(`No metric in ${project.slug} has the event name "${eventName}".`);
-const getMetric = async (context, [eventName]) => {
+const getMetric = async (context, [eventName], options) => {
+	const selection = metricSelectionOf(eventName, options);
 	const { client, project } = await connectToLinkedProject(context);
-	const receivedMetric = await client.findMetricByEventName(project.id, eventName);
-	if (receivedMetric === void 0) throw noMetricWithEventName(project, eventName);
-	const { parsedBody: metric, responseBody } = receivedMetric;
+	const { parsedBody: metric, responseBody } = await findSelectedMetric(client, project, selection);
 	return {
 		json: responseBody,
 		text: metricText(metric, await openRunEnvironmentSlugsOf(client, project, metric)),
@@ -2721,57 +2858,61 @@ const getMetric = async (context, [eventName]) => {
 	};
 };
 const createMetric = async (context, _commandArguments, options) => {
+	const newMetric = await newMetricOf(options, context.invocation);
 	const { client, project } = await connectToLinkedProject(context);
-	const { parsedBody: metric, responseBody } = await client.createMetric(project.id, newMetricOf(options));
+	const { parsedBody: metric, responseBody } = await client.createMetric(project.id, newMetric);
 	return {
 		json: responseBody,
-		text: [`Created metric ${metric.eventName} in ${project.slug}.`, metricText(metric, /* @__PURE__ */ new Map())].join("\n"),
+		text: [`Created metric ${metricLabel(metric)} in ${project.slug}.`, metricText(metric, /* @__PURE__ */ new Map())].join("\n"),
 		exitCode: ExitCode.success
 	};
 };
-const kindInUseError = (eventName, experiments) => new CliError([
-	`${experiments.length} ${plural(experiments.length, "experiment decides", "experiments decide")} on a kind this change removes, so ${eventName} was not updated:`,
+const kindInUseError = (metric, experiments) => new CliError([
+	`${experiments.length} ${plural(experiments.length, "experiment decides", "experiments decide")} on a kind this change removes, so ${metricLabel(metric)} was not updated:`,
 	...experiments.map((experiment) => `  ${experiment.configKey} decides on ${kindWords(experiment.primaryKind)}`),
 	`Give ${plural(experiments.length, "it", "each of them")} another primary kind first, on the experiment's Settings tab in the dashboard.`
 ].join("\n"));
 const updateMetric = async (context, [eventName], options) => {
+	const selection = metricSelectionOf(eventName, options);
 	const changes = metricChangesOf(options);
 	const { client, project } = await connectToLinkedProject(context);
-	const currentMetric = await client.findMetricByEventName(project.id, eventName);
-	if (currentMetric === void 0) throw noMetricWithEventName(project, eventName);
-	const update = await client.updateMetric(project.id, currentMetric.parsedBody.id, changes);
+	const { parsedBody: currentMetric } = await findSelectedMetric(client, project, selection);
+	const update = await client.updateMetric(project.id, currentMetric.id, changes);
 	switch (update.outcome) {
-		case "not-found": throw noMetricWithEventName(project, eventName);
-		case "kind-in-use": throw kindInUseError(eventName, update.decidingExperiments);
+		case "not-found": throw noSelectedMetric(project, selection);
+		case "kind-in-use": throw kindInUseError(currentMetric, update.decidingExperiments);
 		case "updated": {
 			const { parsedBody: metric, responseBody } = update.metric;
 			return {
 				json: responseBody,
-				text: [`Updated metric ${eventName} in ${project.slug}.`, metricText(metric, await openRunEnvironmentSlugsOf(client, project, metric))].join("\n"),
+				text: [`Updated metric ${metricLabel(metric)} in ${project.slug}.`, metricText(metric, await openRunEnvironmentSlugsOf(client, project, metric))].join("\n"),
 				exitCode: ExitCode.success
 			};
 		}
 	}
 };
 const experimentWithOpenRunsLine = (experiment, environmentSlugs) => `  ${experiment.configKey}, running in ${openRunEnvironmentNames(experiment.openRuns, environmentSlugs)}`;
-const metricInUseError = (eventName, experiments, environmentSlugs) => new CliError([
-	`${experiments.length} ${plural(experiments.length, "experiment", "experiments")} with a run in progress ${plural(experiments.length, "uses", "use")} ${eventName}, so it was not deleted:`,
+const metricInUseError = (metric, experiments, environmentSlugs) => new CliError([
+	`${experiments.length} ${plural(experiments.length, "experiment", "experiments")} with a run in progress ${plural(experiments.length, "uses", "use")} ${metricLabel(metric)}, so it was not deleted:`,
 	...experiments.map((experiment) => experimentWithOpenRunsLine(experiment, environmentSlugs)),
 	"Ship or stop each run first, with configdirector configs ship or configs stop, or detach the metric on the experiment's Settings tab in the dashboard."
 ].join("\n"));
-const deleteMetric = async (context, [eventName]) => {
+const deleteMetric = async (context, [eventName], options) => {
+	const selection = metricSelectionOf(eventName, options);
 	const { client, project } = await connectToLinkedProject(context);
-	const currentMetric = await client.findMetricByEventName(project.id, eventName);
-	if (currentMetric === void 0) throw noMetricWithEventName(project, eventName);
-	const deletion = await client.deleteMetric(project.id, currentMetric.parsedBody.id);
+	const { parsedBody: metric } = await findSelectedMetric(client, project, selection);
+	const deletion = await client.deleteMetric(project.id, metric.id);
 	switch (deletion.outcome) {
 		case "deleted": return {
-			json: { deletedEventName: eventName },
-			text: [`Deleted metric ${eventName} from ${project.slug}.`, ""].join("\n"),
+			json: {
+				deletedMetricId: metric.id,
+				deletedEventName: metric.eventName
+			},
+			text: [`Deleted metric ${metricLabel(metric)} from ${project.slug}.`, ""].join("\n"),
 			exitCode: ExitCode.success
 		};
-		case "not-found": throw noMetricWithEventName(project, eventName);
-		case "in-use": throw metricInUseError(eventName, deletion.experimentsWithOpenRuns, await environmentSlugsById(client, project));
+		case "not-found": throw noSelectedMetric(project, selection);
+		case "in-use": throw metricInUseError(metric, deletion.experimentsWithOpenRuns, await environmentSlugsById(client, project));
 	}
 };
 //#endregion
@@ -5458,30 +5599,6 @@ const scan = async (context, [path], options) => {
 	};
 };
 //#endregion
-//#region src/request-file.ts
-const STANDARD_INPUT_ARGUMENT = "-";
-const readRequestSource = async (argumentLabel, argument, invocation) => {
-	if (argument === STANDARD_INPUT_ARGUMENT) return {
-		origin: `${argumentLabel} reads stdin`,
-		contents: await text(invocation.stdin)
-	};
-	const { file, contents } = await readOptionFile(argumentLabel, argument, invocation.workingDirectory);
-	return {
-		origin: `${argumentLabel} names ${file}`,
-		contents
-	};
-};
-const readRequestFile = async (argumentLabel, argument, invocation, expectedFormatSentence) => {
-	const { origin, contents } = await readRequestSource(argumentLabel, argument, invocation);
-	const request = parseJson(contents);
-	if (!isJsonObject(request)) throw new CliError(`${origin}, which does not hold a JSON object. ${expectedFormatSentence}`);
-	return request;
-};
-const withId = (entry) => entry.id === void 0 ? {
-	id: randomUUID(),
-	...entry
-} : entry;
-//#endregion
 //#region src/segments/segment-file.ts
 const readSegmentFile = (segmentArgument, invocation) => readRequestFile("--segment", segmentArgument, invocation, "It takes {\"key\": ..., \"name\": ..., \"groups\": [...]}, like the output of segments get --json.");
 const conditionWithId = (condition) => isJsonObject(condition) ? withId(condition) : condition;
@@ -5869,6 +5986,9 @@ const validate = async (context, [path]) => {
 //#region src/run.ts
 const DEFAULT_BASE_URL = "https://api.configdirector.com";
 const NO_HEADERS_DESCRIPTION = "leave out the header row";
+const METRIC_EVENT_NAME_DESCRIPTION = "the metric's event name, as the application passes it to track, while only one metric has it";
+const METRIC_ID_DESCRIPTION = "the metric's id, which names one of several metrics with the same event name, in place of the event name";
+const SEVERAL_METRICS_HELP = "When several metrics have the event name, the command lists them with their ids and exits with 2 without changing anything. Name one with --id.";
 const SEGMENT_FILE_DESCRIPTION = "a JSON file holding the segment as the Admin API takes it, or - to read it from stdin (required)";
 const withoutTrailingSlashes = (url) => {
 	let trimmedUrl = url;
@@ -5938,10 +6058,10 @@ const run = async (invocation) => {
 	segmentsCommand.command("delete").argument("<key>", "the segment's key").description("delete a segment and its environment overrides").addHelpText("after", "\nThe segment is deleted with no confirmation. While the targeting rules of a config use it, the deletion is refused and the configs are listed with their environments.").action(commandAction(deleteSegment));
 	const metricsCommand = program.command("metrics").description("list, show, create, update and delete the metrics a project's experiments measure");
 	metricsCommand.command("list").description("list the project's metrics with their kinds, direction and how many experiments use each").option("--no-headers", NO_HEADERS_DESCRIPTION).action(commandAction(listMetrics));
-	metricsCommand.command("get").argument("<event name>", "the metric's event name, as the application passes it to track").description("show a metric's kinds and direction, and the experiments that use it").action(commandAction(getMetric));
-	metricsCommand.command("create").description("create the project's metric for an event name the application passes to track").requiredOption("--event-name <event name>", "the event name, exactly as the application passes it to track (required)").addOption(repeatableChoiceOption("--kind <kind>", "a number the metric reports: conversion, the share of exposed contexts that sent the event; count-per-context, how many times each sent it on average; value-per-context, the value sent with it per context on average; repeatable (required)", METRIC_KINDS).makeOptionMandatory()).addOption(new Option("--direction <direction>", "whether a higher or a lower number is better (required)").choices(METRIC_DIRECTIONS).makeOptionMandatory()).option("--description <text>", "what the event means").action(commandAction(createMetric));
-	metricsCommand.command("update").argument("<event name>", "the metric's event name").description("change a metric's kinds, direction or description, leaving the others as they are").addOption(repeatableChoiceOption("--kind <kind>", "a number the metric reports; repeatable, and the kinds given replace the metric's", METRIC_KINDS)).addOption(new Option("--direction <direction>", "whether a higher or a lower number is better").choices(METRIC_DIRECTIONS)).option("--description <text>", "what the event means; --description \"\" removes it").addHelpText("after", "\nA metric keeps its event name: for another event name, create another metric. Removing a kind that an experiment's primary metric decides on is refused, and the experiments are listed.").action(commandAction(updateMetric));
-	metricsCommand.command("delete").argument("<event name>", "the metric's event name").description("delete a metric and detach it from the experiments that use it").addHelpText("after", "\nThe metric is deleted with no confirmation. While an experiment that uses it has a run in progress, the deletion is refused and the experiments are listed with the environments of their runs. Events with its name keep being counted, so a metric created again for the name and attached again shows their history.").action(commandAction(deleteMetric));
+	metricsCommand.command("get").argument("[event name]", METRIC_EVENT_NAME_DESCRIPTION).option("--id <metric id>", METRIC_ID_DESCRIPTION).description("show a metric's kinds and direction, and the experiments that use it").addHelpText("after", `\n${SEVERAL_METRICS_HELP}`).action(commandAction(getMetric));
+	metricsCommand.command("create").description("create a metric for an event name the application passes to track").requiredOption("--event-name <event name>", "the event name, exactly as the application passes it to track (required)").option("--filter <file>", "a JSON file holding the conditions an event's details must match for the event to count, or - to read them from stdin").option("--value-field <pointer>", "a JSON pointer, such as /items, to the field of the event's details holding the number that value per context sums in place of the event's value").addOption(repeatableChoiceOption("--kind <kind>", "a number the metric reports: conversion, the share of exposed contexts that sent the event; count-per-context, how many times each sent it on average; value-per-context, the value sent with it per context on average; repeatable (required)", METRIC_KINDS).makeOptionMandatory()).addOption(new Option("--direction <direction>", "whether a higher or a lower number is better (required)").choices(METRIC_DIRECTIONS).makeOptionMandatory()).option("--description <text>", "what the event means").addHelpText("after", "\nThe --filter file holds a list of 1 to 5 conditions, all of which an event must match to count, like the filter that metrics get --json prints. For the checkouts on the Team plan: [{\"field\": \"/plan\", \"targetType\": \"text\", \"operator\": \"is one of\", \"targetValues\": [\"team\"]}]. field is a JSON pointer into the details the application sends with the event. A text condition takes is one of or is NOT one of; a number condition =, !=, >, >=, < or <=, with its number as text, such as \"2\"; and a boolean condition equals, with \"true\" or \"false\". A field an event lacks reads as empty text, so is NOT one of and != count an event without it.\n\n--value-field /items sums the number each event's details hold at /items for value-per-context, in place of the event's value, and needs --kind value-per-context.\n\nA metric keeps its filter and value field for its whole life: for others, create another metric. A metric with a filter or a value field is counted from the moment it is attached to an experiment.").action(commandAction(createMetric));
+	metricsCommand.command("update").argument("[event name]", METRIC_EVENT_NAME_DESCRIPTION).option("--id <metric id>", METRIC_ID_DESCRIPTION).description("change a metric's kinds, direction or description, leaving the others as they are").addOption(repeatableChoiceOption("--kind <kind>", "a number the metric reports; repeatable, and the kinds given replace the metric's", METRIC_KINDS)).addOption(new Option("--direction <direction>", "whether a higher or a lower number is better").choices(METRIC_DIRECTIONS)).option("--description <text>", "what the event means; --description \"\" removes it").addHelpText("after", "\nA metric keeps its event name, filter and value field: for others, create another metric. Removing a kind that an experiment's primary metric decides on is refused, and the experiments are listed.\n\n" + SEVERAL_METRICS_HELP).action(commandAction(updateMetric));
+	metricsCommand.command("delete").argument("[event name]", METRIC_EVENT_NAME_DESCRIPTION).option("--id <metric id>", METRIC_ID_DESCRIPTION).description("delete a metric and detach it from the experiments that use it").addHelpText("after", "\nThe metric is deleted with no confirmation. While an experiment that uses it has a run in progress, the deletion is refused and the experiments are listed with the environments of their runs. Events with its name keep being counted, so a metric created again for the name without a filter or a value field and attached again shows their history, while one with a filter or a value field is counted from the moment it is attached.\n\n" + SEVERAL_METRICS_HELP).action(commandAction(deleteMetric));
 	const targetingRulesCommand = program.command("targeting-rules").description("replace a config's targeting rules in one environment and show the format they take");
 	targetingRulesCommand.command("set").argument("<key>", "the config's key, or an old key of it").description("replace a config's targeting rules in one environment with the rules of a JSON file").requiredOption("--environment <slug>", "slug of the environment whose targeting rules to replace (required)").requiredOption("--rules <file>", "a JSON file holding defaultValue and rules as the Admin API takes them, or - to read it from stdin (required)").addHelpText("after", "\nThe file holds {\"defaultValue\": ..., \"rules\": [...]}, like an entry of targets in configs get --json, so you can edit that output and write it back. Every rule of the environment is replaced. A rule, condition or percentage without an id gets a new one. configdirector targeting-rules reference lists the condition kinds, attributes and operators.").action(commandAction(setTargetingRules));
 	targetingRulesCommand.command("reference").description("show the format targeting rules take: the condition kinds, the attributes a condition can test and the operators").action(commandAction(showTargetingRulesReference));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@configdirector/cli",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Command line tool for ConfigDirector, the managed configuration and feature flag service.",
   "license": "MIT",
   "author": "ConfigDirector",