@configdirector/cli 0.18.1 → 0.20.0

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to `@configdirector/cli` are documented here. The format fol
 
 ## [Unreleased]
 
+## [0.20.0] - 2026-11-06
+
+### Changed
+
+- `configdirector evaluate` says when a percentage rollout was skipped because the context has no identifier. The rule's line ends with `rollout skipped: the context has no identifier`, where it showed `not matched` with no reason, both for a percentage rule and for a conditional rule that serves a percentage rollout once its conditions matched. The rules after it show `not evaluated` and the context gets the default targeting rule value, as before. `--json` prints the Admin API's response as received, as before.
+
+## [0.19.0] - 2026-11-04
+
+### Added
+
+- `configdirector configs runs <key> --environment <slug>` lists an experiment's runs in an environment, newest first: when each started and ended, how it ended, and, per rollout, how many distinct contexts each variation reached against the share configured when the run started, and whether the split matches those shares. `--json` prints the Admin API's response as received.
+- `configdirector configs ship <key> --environment <slug> --variation <name or id>` serves one variation to everyone in the environment and ends its run: in one save of the targeting rules, 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. `configdirector configs stop <key> --environment <slug>` ends the run without choosing a variation, keeping the default targeting rule value. Both print the rules they saved, ask for no confirmation and treat a live environment like any other. They exit with 2 when ConfigDirector refuses the change, such as a stop on a config that is not an experiment or with no percentage rollout saved in the environment, and `configs ship` exits with 2 listing the variations when `--variation` matches none, or several with the same name, and saying so when the config has no variations.
+
 ## [0.18.1] - 2026-11-03
 
 ### Fixed

package/README.md

@@ -1,6 +1,6 @@
 # ConfigDirector CLI
 
-`configdirector` is the command line tool for [ConfigDirector](https://www.configdirector.com), the managed configuration and feature flag service. Commands and output may change before 1.0. This release signs in to one or more organizations, links a repository to a project, lists where the repository's code reads config keys, checks those keys against the project's configs, shows the value a context gets for a config and why, reads a project's environments, configs, targeting rules and segments, creates and copies configs, replaces a config's targeting rules in an environment, archives configs, creates, updates and deletes segments, uploads the repository's code references to the project, and lists and removes the project's scanned repositories.
+`configdirector` is the command line tool for [ConfigDirector](https://www.configdirector.com), the managed configuration and feature flag service. Commands and output may change before 1.0. This release signs in to one or more organizations, links a repository to a project, lists where the repository's code reads config keys, checks those keys against the project's configs, shows the value a context gets for a config and why, reads a project's environments, configs, targeting rules and segments, creates and copies configs, replaces a config's targeting rules in an environment, lists an experiment's runs and ships or stops them, archives configs, creates, updates and deletes segments, uploads the repository's code references to the project, and lists and removes the project's scanned repositories.
 
 The [CLI page of the ConfigDirector docs](https://docs.configdirector.com/integrations/cli) covers the API token, CI setup for GitHub Actions and GitLab, and what each problem `validate` reports means for your build.
 
@@ -159,7 +159,7 @@ true, served by rule 2
 Default targeting rule: false
 ```
 
-A rule that did not match names the first condition that failed and the context's value for it, as in `plan is one of pro, team, but it is "free"`, or the bucket a percentage rollout put the context in. A rule after the one that served the value is not evaluated, and a rule that could not be evaluated is shown as errored.
+A rule that did not match names the first condition that failed and the context's value for it, as in `plan is one of pro, team, but it is "free"`, or the bucket a percentage rollout put the context in. A context without an identifier gets no bucket: the first percentage rollout it reaches shows `rollout skipped: the context has no identifier`, and the context gets the default targeting rule value. A rule after the one that served the value, or after a skipped rollout, is not evaluated, and a rule that could not be evaluated is shown as errored.
 
 `--environment` takes the environment's slug and is required. Give the context one of three ways:
 
@@ -318,6 +318,35 @@ configdirector targeting-rules set new-checkout --environment production --rules
 
 `targeting-rules set` needs `projects:read`, `environments:read` and `config-targeting-rules:update`. `targeting-rules reference` needs only a valid token and no project.
 
+## Experiment runs
+
+```bash
+configdirector configs runs checkout-cta-copy --environment production
+configdirector configs ship checkout-cta-copy --environment production --variation treatment-a
+configdirector configs stop checkout-cta-copy --environment production
+```
+
+A run is a period during which an experiment's targeting rules in one environment split traffic between its variations. `configs runs` lists the experiment's runs in an environment, newest first, with how many distinct contexts each variation reached, called exposures, against the share configured when the run started:
+
+```txt
+Runs of checkout-cta-copy in production (live), newest first:
+
+Running since 2026-11-03 12:00 UTC
+  Rollout: everyone not caught by a rule above
+    control (Start free trial)              412 exposures   configured 50%
+    treatment-a (Try it free for 14 days)   398 exposures   configured 50%
+    810 contexts exposed, 3201 evaluations. The split matches the configured shares.
+```
+
+- `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.
+
+Both print the rules they saved, ask for no confirmation and treat a live environment like any other, so check the environment before you run them.
+
+`configs ship` exits with 2 when `--variation` matches none of the experiment's variations, or several with the same name, and lists them with their IDs, and when the config has no variations, since only an experiment has them. `configs stop` exits with 2 when the config is not an experiment or the environment holds no percentage rollout. All three exit with 2 when no config has the key or no environment has the slug. With `--json`, they print the Admin API's response as received.
+
+`configs runs` needs `projects:read`, `environments:read` and `configs:read`. `configs ship` also needs `config-targeting-rules:update`, and `configs stop` needs `projects:read`, `environments:read` and `config-targeting-rules:update`. Shipped and stopped runs show in the audit log with the source CLI.
+
 ## Change segments
 
 ```bash

package/dist/configdirector.mjs

@@ -14,7 +14,7 @@ import { promisify } from "node:util";
 import { randomUUID } from "node:crypto";
 import { text } from "node:stream/consumers";
 //#region package.json
-var version = "0.18.1";
+var version = "0.20.0";
 //#endregion
 //#region src/CliError.ts
 var CliError = class extends Error {
@@ -121,6 +121,36 @@ const CopyPlanSchema = v.object({
 });
 const CopyPlanResponseSchema = v.object({ plan: CopyPlanSchema });
 //#endregion
+//#region src/admin-api/experiment-runs.ts
+const TimestampSchema = v.pipe(v.string(), v.isoTimestamp());
+const RolloutExposuresSchema = v.object({
+	ruleId: v.string(),
+	exposures: v.number(),
+	evaluations: v.number(),
+	verdict: v.string(),
+	variations: v.array(v.object({
+		variationId: v.string(),
+		percentage: v.number(),
+		exposures: v.number()
+	}))
+});
+const ExperimentRunSchema = v.object({
+	startedAt: TimestampSchema,
+	endedAt: v.optional(TimestampSchema),
+	outcome: v.optional(v.string()),
+	shippedVariationId: v.optional(v.string()),
+	rollouts: v.array(v.object({
+		ruleId: v.string(),
+		conditions: v.optional(v.string())
+	})),
+	exposures: v.object({
+		rollouts: v.array(RolloutExposuresSchema),
+		evaluationsWithoutIdentifier: v.number(),
+		evaluationsFromSdksNotReportingExposures: v.number()
+	})
+});
+const ExperimentRunsSchema = v.array(ExperimentRunSchema);
+//#endregion
 //#region src/admin-api/config-creation.ts
 const CreatedConfigSchema = v.object({
 	key: v.string(),
@@ -217,7 +247,8 @@ const RuleSchema = v.variant("type", [v.variant("target", [v.object({
 //#region src/admin-api/variations.ts
 const VariationSchema = v.object({
 	id: v.string(),
-	name: v.nullish(v.string())
+	name: v.nullish(v.string()),
+	value: RuleValueSchema
 });
 //#endregion
 //#region src/admin-api/config-with-targeting-rules.ts
@@ -368,7 +399,6 @@ const ConditionExplanationSchema = v.union([
 	SegmentConditionExplanationSchema
 ]);
 const BucketSchema = v.object({
-	defaultedToPredefinedBucket: v.boolean(),
 	assignedPercentage: v.number(),
 	shares: v.array(v.object({
 		percentageId: v.string(),
@@ -386,7 +416,8 @@ const RuleExplanationSchema = v.object({
 		"errored"
 	]),
 	conditions: v.array(ConditionExplanationSchema),
-	bucket: v.optional(BucketSchema)
+	bucket: v.optional(BucketSchema),
+	rolloutSkippedNoIdentifier: v.boolean()
 });
 const ConfigEvaluationSchema = v.object({
 	key: v.string(),
@@ -594,6 +625,21 @@ var AdminApiClient = class {
 			body: request
 		});
 	}
+	listRuns(projectId, configKey, environmentId) {
+		return this.getIfFound(`/v1/projects/${encodeURIComponent(projectId)}/configs/${encodeURIComponent(configKey)}/environments/${encodeURIComponent(environmentId)}/runs`, ExperimentRunsSchema);
+	}
+	shipVariation(projectId, configKey, environmentId, variationId) {
+		return this.requestIfFound(`/v1/projects/${encodeURIComponent(projectId)}/configs/${encodeURIComponent(configKey)}/environments/${encodeURIComponent(environmentId)}/ship`, ConfigWithTargetingRulesSchema, {
+			method: "POST",
+			body: { variationId }
+		});
+	}
+	stopRun(projectId, configKey, environmentId) {
+		return this.requestIfFound(`/v1/projects/${encodeURIComponent(projectId)}/configs/${encodeURIComponent(configKey)}/environments/${encodeURIComponent(environmentId)}/stop`, ConfigWithTargetingRulesSchema, {
+			method: "POST",
+			body: {}
+		});
+	}
 	async evaluateConfig(projectId, configKey, request) {
 		const { responseBody, parsedBody } = await this.requestJson(`/v1/projects/${encodeURIComponent(projectId)}/configs/${encodeURIComponent(configKey)}/evaluate`, ConfigEvaluationSchema, {
 			method: "POST",
@@ -1018,6 +1064,7 @@ const describeCondition = (condition, segments) => {
 	}
 };
 const valueWithVariationName = (value, variationName) => variationName ? `${variationName} (${String(value)})` : String(value);
+const describeVariation = (variation) => valueWithVariationName(variation.value, variation.name);
 const describeValue = (value, variationId, variations) => valueWithVariationName(value, variations.find((variation) => variation.id === variationId)?.name);
 const describePercentages = (percentages, variations) => percentages.map((percentage) => `${formatPercentage(percentage.percentage)}% get ${describeValue(percentage.value, percentage.variationId, variations)}`).join(", ");
 const describeRule = (rule, segments, variations) => {
@@ -1405,6 +1452,85 @@ const newConfigOf = async (options, workingDirectory) => {
 	};
 };
 //#endregion
+//#region src/configs/run-text.ts
+const OUTCOME_LABELS = {
+	shipped: "Shipped",
+	stopped: "Stopped",
+	replaced: "Replaced"
+};
+const VERDICT_SENTENCES = {
+	matches: "The split matches the configured shares.",
+	mismatch: "The split does not match the configured shares. This usually means some contexts evaluate without a stable identifier, or a rule above the split catches part of the traffic. Results from this run are not reliable.",
+	"needs-more-exposures": "The run needs more exposures before the split can be checked against the configured shares."
+};
+const variationDescription = (variationId, variations) => {
+	const variation = variations.find((candidate) => candidate.id === variationId);
+	return variation && describeVariation(variation);
+};
+const runHeadline = (run, variations) => {
+	if (run.outcome === void 0 || run.endedAt === void 0) return `Running since ${utcMinute(run.startedAt)}`;
+	const outcomeLabel = OUTCOME_LABELS[run.outcome] ?? run.outcome;
+	const shippedVariation = run.shippedVariationId && variationDescription(run.shippedVariationId, variations);
+	return `${shippedVariation ? `${outcomeLabel} ${shippedVariation}` : outcomeLabel}, ${utcMinute(run.startedAt)} to ${utcMinute(run.endedAt)}`;
+};
+const rolloutAudience = (run, rollout) => run.rollouts.find((candidate) => candidate.ruleId === rollout.ruleId)?.conditions ?? "everyone not caught by a rule above";
+const rolloutSummary = (rollout) => `${rollout.exposures} ${plural(rollout.exposures, "context exposed", "contexts exposed")}, ${rollout.evaluations} ${plural(rollout.evaluations, "evaluation", "evaluations")}. ` + (VERDICT_SENTENCES[rollout.verdict] ?? rollout.verdict);
+const rolloutLines = (run, rollout, variations) => [
+	`Rollout: ${rolloutAudience(run, rollout)}`,
+	...alignedColumns(rollout.variations.map((variation) => [
+		variationDescription(variation.variationId, variations) ?? "a variation no longer listed",
+		`${variation.exposures} ${plural(variation.exposures, "exposure", "exposures")}`,
+		`configured ${formatPercentage(variation.percentage)}%`
+	])).map((line) => `  ${line}`),
+	`  ${rolloutSummary(rollout)}`
+];
+const uncountedEvaluationsLines = (evaluations, one, several) => {
+	if (evaluations === 0) return [];
+	return [evaluations === 1 ? `1 evaluation ${one}` : `${evaluations} evaluations ${several}`];
+};
+const runLines = (run, variations) => [runHeadline(run, variations), ...[
+	...run.exposures.rollouts.flatMap((rollout) => rolloutLines(run, rollout, variations)),
+	...uncountedEvaluationsLines(run.exposures.evaluationsFromSdksNotReportingExposures, "came from an SDK version that does not report exposures yet. It is not counted above; update that SDK to count it.", "came from SDK versions that do not report exposures yet. They are not counted above; update those SDKs to count them."),
+	...uncountedEvaluationsLines(run.exposures.evaluationsWithoutIdentifier, "came from a context without an identifier and was served the default targeting rule value. It skips the split and is not an exposure.", "came from contexts without an identifier and were served the default targeting rule value. They skip the split and are not exposures.")
+].map((line) => `  ${line}`)];
+const runsText = (config, requestedKey, environment, runs) => {
+	const environmentName = environmentLabel(environment);
+	return [
+		...oldKeyLines(requestedKey, config.key),
+		...runs.length === 0 ? [`No runs of ${config.key} in ${environmentName}.`] : [`Runs of ${config.key} in ${environmentName}, newest first:`, ...runs.flatMap((run) => ["", ...runLines(run, config.variations)])],
+		""
+	].join("\n");
+};
+const savedRulesText = ({ config, requestedKey, environment, segments }, headline) => [
+	...oldKeyLines(requestedKey, config.key),
+	headline,
+	"",
+	...config.targets.filter((targetingRules) => targetingRules.environment.slug === environment.slug).flatMap((targetingRules) => targetingRuleLines(targetingRules, segments, config.variations)),
+	""
+].join("\n");
+const shippedVariationText = (savedRules, variation) => savedRulesText(savedRules, `Shipped ${describeVariation(variation)} in ${environmentLabel(savedRules.environment)}.`);
+const stoppedRunText = (savedRules) => savedRulesText(savedRules, `Stopped the run of ${savedRules.config.key} in ${environmentLabel(savedRules.environment)}.`);
+//#endregion
+//#region src/configs/variation-selection.ts
+const variationListing = (variations) => alignedColumns(variations.map((variation) => [describeVariation(variation), variation.id])).map((line) => `  ${line}`);
+const findVariationToShip = (config, nameOrId) => {
+	if (config.variations.length === 0) throw new CliError(`${config.key} has no variations to ship. Only an experiment has variations.`);
+	const matches = config.variations.filter((variation) => variation.id === nameOrId || variation.name === nameOrId);
+	const [onlyMatch, ...otherMatches] = matches;
+	if (onlyMatch === void 0) throw new CliError([`${config.key} has no variation named or with the id "${nameOrId}". Its variations are:`, ...variationListing(config.variations)].join("\n"));
+	if (otherMatches.length > 0) throw new CliError([`Several variations of ${config.key} are named "${nameOrId}". Give the id of the one to ship:`, ...variationListing(matches)].join("\n"));
+	return onlyMatch;
+};
+//#endregion
+//#region src/environment-selection.ts
+const environmentSlugsSentence = (environments) => environments.length === 0 ? "The project has no environments." : `Its environments are ${environments.map((environment) => environment.slug).join(", ")}.`;
+const findEnvironmentBySlug = async (client, project, slug) => {
+	const { parsedBody: environments } = await client.listEnvironments(project.id);
+	const environment = environments.find((listedEnvironment) => listedEnvironment.slug === slug);
+	if (environment === void 0) throw new CliError(`No environment in ${project.slug} has the slug "${slug}". ${environmentSlugsSentence(environments)}`);
+	return environment;
+};
+//#endregion
 //#region src/project-selection.ts
 const requireProjectSlug = (context) => {
 	if (context.projectSlug === void 0) throw new CliError("Name the project with --project <slug> or CONFIGDIRECTOR_PROJECT.");
@@ -1666,6 +1792,55 @@ const copyConfig = async (context, [configKey], options) => {
 		exitCode: ExitCode.success
 	};
 };
+const showConfigRuns = async (context, [configKey], options) => {
+	const { client, project } = await connectToLinkedProject(context);
+	const environment = await findEnvironmentBySlug(client, project, options.environment);
+	const receivedConfig = await client.getConfig(project.id, configKey);
+	const receivedRuns = receivedConfig && await client.listRuns(project.id, configKey, environment.id);
+	if (receivedConfig === void 0 || receivedRuns === void 0) throw new CliError(`No config in ${project.slug} has the key "${configKey}".`);
+	return {
+		json: receivedRuns.responseBody,
+		text: runsText(receivedConfig.parsedBody, configKey, environment, receivedRuns.parsedBody),
+		exitCode: ExitCode.success
+	};
+};
+const shipVariation = async (context, [configKey], options) => {
+	const { client, project } = await connectToLinkedProject(context);
+	const environment = await findEnvironmentBySlug(client, project, options.environment);
+	const receivedConfig = await client.getConfig(project.id, configKey);
+	if (receivedConfig === void 0) throw new CliError(`No config in ${project.slug} has the key "${configKey}".`);
+	const variation = findVariationToShip(receivedConfig.parsedBody, options.variation);
+	const savedConfig = await client.shipVariation(project.id, configKey, environment.id, variation.id);
+	if (savedConfig === void 0) throw new CliError(`No config in ${project.slug} has the key "${configKey}".`);
+	const segments = await segmentNamesFor(client, project, savedConfig.parsedBody);
+	return {
+		json: savedConfig.responseBody,
+		text: shippedVariationText({
+			config: savedConfig.parsedBody,
+			requestedKey: configKey,
+			environment,
+			segments
+		}, variation),
+		exitCode: ExitCode.success
+	};
+};
+const stopRun = async (context, [configKey], options) => {
+	const { client, project } = await connectToLinkedProject(context);
+	const environment = await findEnvironmentBySlug(client, project, options.environment);
+	const savedConfig = await client.stopRun(project.id, configKey, environment.id);
+	if (savedConfig === void 0) throw new CliError(`No config in ${project.slug} has the key "${configKey}".`);
+	const segments = await segmentNamesFor(client, project, savedConfig.parsedBody);
+	return {
+		json: savedConfig.responseBody,
+		text: stoppedRunText({
+			config: savedConfig.parsedBody,
+			requestedKey: configKey,
+			environment,
+			segments
+		}),
+		exitCode: ExitCode.success
+	};
+};
 const archiveConfig = async (context, [configKey]) => {
 	const { client, project } = await connectToLinkedProject(context);
 	if (await client.archiveConfig(project.id, configKey) === "not-found") throw new CliError(`No config in ${project.slug} has the key "${configKey}".`);
@@ -1721,15 +1896,6 @@ const listEnvironments = async (context, _commandArguments, options) => {
 	};
 };
 //#endregion
-//#region src/environment-selection.ts
-const environmentSlugsSentence = (environments) => environments.length === 0 ? "The project has no environments." : `Its environments are ${environments.map((environment) => environment.slug).join(", ")}.`;
-const findEnvironmentBySlug = async (client, project, slug) => {
-	const { parsedBody: environments } = await client.listEnvironments(project.id);
-	const environment = environments.find((listedEnvironment) => listedEnvironment.slug === slug);
-	if (environment === void 0) throw new CliError(`No environment in ${project.slug} has the slug "${slug}". ${environmentSlugsSentence(environments)}`);
-	return environment;
-};
-//#endregion
 //#region src/evaluate/context-form.ts
 const DEFAULT_CONTEXT_KIND = "user";
 const TYPED_TRAIT_MARKER = ":";
@@ -1843,8 +2009,7 @@ const bucketPlacement = (bucket) => {
 	if (selectedShare !== void 0) return `${assigned} is in ${describeShareRange(selectedShare.from, selectedShare.to)}`;
 	return `${assigned} is outside ${describeShareRange(0, bucket.shares.at(-1)?.to ?? 0)}`;
 };
-const describeBucket = (bucket) => bucket.defaultedToPredefinedBucket ? `no identifier, so ${bucketPlacement(bucket)}` : bucketPlacement(bucket);
-const withBucket = (outcome, bucket) => bucket === void 0 ? outcome : `${outcome}: ${describeBucket(bucket)}`;
+const withBucket = (outcome, bucket) => bucket === void 0 ? outcome : `${outcome}: ${bucketPlacement(bucket)}`;
 const conditionsOf = (rule) => rule?.type === "conditional" ? rule.conditions : [];
 const segmentMismatchEvidence = (explanation) => {
 	if (!explanation.segmentFound) return "the segment was not found";
@@ -1866,17 +2031,19 @@ const describeNotMatched = (explanation, conditions, segments) => {
 	const failingCondition = failingConditionDescription(explanation, conditions, segments);
 	return failingCondition === void 0 ? withBucket("not matched", explanation.bucket) : `not matched: ${failingCondition}`;
 };
+const evaluatorRuleOutcomeOf = (explanation) => explanation.rolloutSkippedNoIdentifier ? "rollout-skipped-no-identifier" : explanation.outcome;
 const RULE_OUTCOME_DESCRIPTIONS = {
 	matched: (explanation) => withBucket("matched", explanation.bucket),
 	"not-matched": describeNotMatched,
 	"not-evaluated": () => "not evaluated",
-	errored: () => "errored"
+	errored: () => "errored",
+	"rollout-skipped-no-identifier": () => "rollout skipped: the context has no identifier"
 };
 const ruleLines = (evaluation) => {
 	const rulesById = new Map(evaluation.targetingRules.rules.map((rule) => [rule.id, rule]));
 	return alignedColumns(evaluation.rules.map((explanation, index) => {
 		const rule = rulesById.get(explanation.ruleId);
-		return [`${index + 1}. ${rule === void 0 ? explanation.ruleId : describeRule(rule, evaluation.segments, evaluation.variations)}`, RULE_OUTCOME_DESCRIPTIONS[explanation.outcome](explanation, conditionsOf(rule), evaluation.segments)];
+		return [`${index + 1}. ${rule === void 0 ? explanation.ruleId : describeRule(rule, evaluation.segments, evaluation.variations)}`, RULE_OUTCOME_DESCRIPTIONS[evaluatorRuleOutcomeOf(explanation)](explanation, conditionsOf(rule), evaluation.segments)];
 	}));
 };
 const evaluationText = (evaluation, requested) => [
@@ -5258,12 +5425,15 @@ const run = async (invocation) => {
 	program.command("api-token").description("describe the API token a command here would use").command("get").description("show the token's organization, name, permissions and expiration, and where it came from; never the token itself").action(commandAction(getApiToken));
 	program.command("projects").description("list the projects of the API token's organization").command("list").description("list the organization's projects, whatever project is selected").option("--no-headers", NO_HEADERS_DESCRIPTION).action(commandAction(listProjects));
 	program.command("environments").description("list the project's environments").command("list").description("list the project's environments with their slugs, marking the live ones").option("--no-headers", NO_HEADERS_DESCRIPTION).action(commandAction(listEnvironments));
-	const configsCommand = program.command("configs").description("list, show, create, copy and archive a project's configs");
+	const configsCommand = program.command("configs").description("list, show, create, copy and archive a project's configs, and list, ship and stop an experiment's runs");
 	configsCommand.command("list").description("list the project's configs with their type, role, lifetime and lifecycle state").option("--tag <name>", "list only the configs that have this tag; repeatable, for configs with any of them", repeatedOption).addOption(new Option("--untagged", "list only the configs without tags").conflicts("tag")).addOption(new Option("--state <state>", "list only the configs in this lifecycle state").choices(LIFECYCLE_STATES)).option("--no-headers", NO_HEADERS_DESCRIPTION).action(commandAction(listConfigs));
 	configsCommand.command("get").argument("<key>", "the config's key, or an old key of it").description("show a config's settings and its targeting rules in every environment").action(commandAction(getConfig));
 	configsCommand.command("activity").argument("<key>", "the config's key, or an old key of it").description("show when SDKs last evaluated a config, per environment, SDK key kind, SDK name and SDK version").option("--no-headers", NO_HEADERS_DESCRIPTION).action(commandAction(showConfigActivity));
 	configsCommand.command("create").description("create a config from options that mirror the Admin API's fields").requiredOption("--key <key>", "the config's key (required)").option("--description <text>", "a description shown with the config in the dashboard").addOption(new Option("--type <type>", "the type of the config's values (required)").choices(CONFIG_TYPES).makeOptionMandatory()).addOption(new Option("--role <role>", "what the config is for (required)").choices(CONFIG_ROLES).makeOptionMandatory()).addOption(new Option("--lifetime <lifetime>", "whether the config is expected to be removed; required with --role config, while a feature flag and an experiment are always temporary and a kill switch always permanent").choices(CONFIG_LIFETIMES)).requiredOption("--default-value <value>", "the default targeting rule value every environment starts with, in the type given by --type; not the in-code default value an application passes to the SDK (required)").option("--client-only", "serve the config to client SDKs only (default: client and server SDKs)").addOption(new Option("--server-only", "serve the config to server SDKs only (default: client and server SDKs)").conflicts("clientOnly")).option("--tag <name>", "assign the project's tag with this name; repeatable", repeatedOption).option("--new-tag <name>", "create a tag with this name in the project's tag catalog and assign it; repeatable", repeatedOption).option("--variation <name=value>", "a variation of an experiment, its value in the type given by --type; repeatable", repeatedOption).addOption(new Option("--min <number>", "the smallest value allowed, included").helpGroup(typeConstraintHelpGroup("min"))).addOption(new Option("--max <number>", "the largest value allowed, included").helpGroup(typeConstraintHelpGroup("max"))).addOption(new Option("--exclusive-min <number>", "values must be greater than this number").conflicts("min").helpGroup(typeConstraintHelpGroup("exclusiveMin"))).addOption(new Option("--exclusive-max <number>", "values must be less than this number").conflicts("max").helpGroup(typeConstraintHelpGroup("exclusiveMax"))).addOption(new Option("--unit <unit>", "the unit of the number the SDKs receive (required)").choices(TIMESPAN_UNITS).helpGroup(typeConstraintHelpGroup("unit"))).addOption(new Option("--allow-fractions", "allow values with a fraction of the unit").helpGroup(typeConstraintHelpGroup("allowFractions"))).addOption(new Option("--allowed-value <value>", "a value the config can take; repeatable").argParser(repeatedOption).helpGroup(typeConstraintHelpGroup("allowedValue"))).addOption(new Option("--enum-value-type <type>", "whether the allowed values are strings or numbers (default: string)").choices(ENUM_VALUE_TYPES).helpGroup(typeConstraintHelpGroup("enumValueType"))).addOption(new Option("--https-only", "allow only HTTPS URLs").helpGroup(typeConstraintHelpGroup("httpsOnly"))).addOption(new Option("--json-schema <file>", "a file holding the JSON Schema every value must match").helpGroup(typeConstraintHelpGroup("jsonSchema"))).action(commandAction(createConfig));
 	configsCommand.command("copy").argument("<key>", "the key of the config to copy, or an old key of it").description("copy a config under a new key, in its project or in another project of the organization, and print the plan").requiredOption("--key <key>", "the copy's key (required)").option("--to <project slug>", "slug of the project to copy the config into, another project of the organization (default: the config's project)").option("--environment <destination slug>=<source slug>", "the source environment whose targeting rules an environment of the destination project starts with, needed for each destination environment with no source environment of its slug; repeatable", repeatedOption).option("--dry-run", "print the plan without creating anything").addHelpText("after", "\nThe copy gets the config's role, lifetime, type, constraints, variations, SDK availability, description and tags, and every environment's targeting rules and default targeting rule value. It starts as a new config, with no old keys, evaluations or code references, and shares nothing with the config it came from. An archived config cannot be copied; restore it first. In another project, environments are matched by slug, tags by name and segments by key: a source environment with no environment of its slug there is skipped, and an environment there with no source environment of its slug needs --environment. A targeting rule that uses a segment the other project doesn't have is dropped. A tag it doesn't have is created when the API token can create tags, and skipped otherwise. The plan names every skipped environment, dropped rule and tag; --dry-run shows it without creating anything.").action(commandAction(copyConfig));
+	configsCommand.command("runs").argument("<key>", "the experiment's key, or an old key of it").description("list an experiment's runs in an environment with their exposures, newest first").requiredOption("--environment <slug>", "slug of the environment to list the runs of (required)").action(commandAction(showConfigRuns));
+	configsCommand.command("ship").argument("<key>", "the experiment's key, or an old key of it").description("serve one variation of an experiment to everyone in an environment, ending its run").requiredOption("--environment <slug>", "slug of the environment to ship the variation in (required)").requiredOption("--variation <variation>", "the name or id of the variation to ship (required)").addHelpText("after", "\nIn one targeting rules save, 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. It asks for no confirmation and treats a live environment like any other.").action(commandAction(shipVariation));
+	configsCommand.command("stop").argument("<key>", "the experiment's key, or an old key of it").description("end an experiment's run in an environment without choosing a variation").requiredOption("--environment <slug>", "slug of the environment to stop the run in (required)").addHelpText("after", "\nIn one targeting rules save, every percentage rollout is removed, including one a conditional rule serves, the default targeting rule value stays, and a conditional rule serving a single value stays. It asks for no confirmation and treats a live environment like any other. When the config is not an experiment, or no percentage rollout is saved in the environment, there is no run to stop, and the command exits with 2.").action(commandAction(stopRun));
 	configsCommand.command("archive").argument("<key>", "the config's key, or an old key of it").description("archive a config, so SDKs stop receiving it; the dashboard can restore it for 30 days").addHelpText("after", "\nThe config is archived with no confirmation and no check of whether the code still reads its key, so run configdirector scan first. Applications that still read it get their in-code default value.").action(commandAction(archiveConfig));
 	const segmentsCommand = program.command("segments").description("list, show, create, update and delete a project's segments");
 	segmentsCommand.command("list").description("list the project's segments with how many configs use each").option("--no-headers", NO_HEADERS_DESCRIPTION).action(commandAction(listSegments));

package/package.json

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