@configdirector/cli 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to `@configdirector/cli` are documented here. The format fol
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-10-27
+
+### Added
+
+- `configdirector configs create --new-tag <name>`, repeatable, creates a tag with that name in the project's tag catalog and assigns it to the new config, so a token with `configs:create` and `tags:create` can create a config with tags the project does not have yet. `--tag <name>` still only finds tags the project already has, so a misspelled `--tag` never creates a tag, and the two can be given together. Every `--tag` name is looked up before any tag is created. A `--new-tag` name given twice, a name given with both options, or more than 20 tags in all exits with 2 before anything is sent. A `--new-tag` name a tag already has exits with 2, creates no config, and says to use `--tag` for it. When a later step fails, for example because the key is taken, the command names the tags it created, which stay in the project's tag catalog, so you can pass them with `--tag` next time.
+- `brew install ConfigDirector/tap/configdirector` installs the CLI with Homebrew, which takes care of Node.js. The Homebrew formula is updated with every npm release, so `brew upgrade configdirector` gets the newest one.
+
+### Fixed
+
+- `configdirector scan` finds configs read in Nuxt server code through `useConfigDirectorServerClient()`, the name `@configdirector/nuxt-sdk` uses from 1.11.0. Server code that calls `useConfigDirectorClient()`, as it did with 1.10.0 and earlier, is still found.
+
+## [0.12.0] - 2026-10-19
+
+### Added
+
+- `configdirector segments create --segment <file>` creates a segment from a JSON file, or from stdin with `--segment -`. The file holds the segment's `key`, `name` and condition `groups`, exactly as the Admin API takes them, so you can save a segment with `segments get --json`, edit it and send it. `overrides` is optional and gives an environment condition groups of its own, keyed by the environment's ID, which `environments list --json` prints. A condition without an `id`, in the groups or in an override, gets a new one, and the IDs given are kept. The CLI checks only that the file holds a JSON object: ConfigDirector checks the segment, and when it refuses it, for example because another segment has its key, the command exits with 2 and lists its reasons. It prints `Created segment beta-testers in web-app.`, then the segment as `segments get` shows it, and `--json` prints the segment as the Admin API returned it. It needs `projects:read` and `segments:create`.
+- `configdirector segments update <key> --segment <file>` replaces the key, the name and the condition groups of the segment the key names with those of the file, so a different `key` renames it, and the segment keeps its own ID whatever `id` the file holds. Without `overrides` in the file, the environment overrides stay as they are; `"overrides": {}` removes them all, and a map leaves exactly those environments overridden. It prints `Updated segment beta-testers in web-app.`, then the segment, and exits with 2 when no segment in the project has the key. It needs `projects:read`, `segments:read` and `segments:update`.
+- `configdirector segments delete <key>` deletes a segment and its environment overrides with no confirmation, prints `Deleted segment beta-testers from web-app.`, and `--json` prints `{ "deletedSegmentKey": "beta-testers" }` with the key as given, as the MCP server's `delete_segment` tool does. While the targeting rules of a config use the segment, it is not deleted: the command exits with 2 and lists each config with the environments whose rules use it. It exits with 2 when no segment in the project has the key, and needs `projects:read` and `segments:delete`.
+- With `environments:read`, the three commands name environments by their slug, and without it, by their ID. The changes show in the audit log with the source CLI. `segments create`, `update` and `delete` do what the MCP server's `create_segment`, `update_segment` and `delete_segment` tools do.
+
 ## [0.11.0] - 2026-10-19
 
 ### Changed

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 configs, replaces a config's targeting rules in an environment, archives configs, 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 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.
 
 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.
 
@@ -12,6 +12,14 @@ npm install --global @configdirector/cli
 
 It needs Node.js 20 or later. If you installed `@configdirector/cli@beta` before 0.11.0, run this again: `@beta` stays on the last beta, 0.10.0-beta.1.
 
+Or install it with Homebrew, which takes care of Node.js:
+
+```bash
+brew install ConfigDirector/tap/configdirector
+```
+
+The Homebrew formula is updated with every npm release, so `brew upgrade configdirector` gets the newest one.
+
 ## Sign in
 
 Create an API token in the ConfigDirector dashboard, then run:
@@ -220,7 +228,8 @@ Default targeting rule in every environment: false
 ```
 
 - `--key`, `--type` (`boolean`, `string`, `integer`, `float`, `timespan`, `enum`, `url` or `json`), `--role` (`config`, `flag`, `kill-switch` or `experiment`), `--lifetime` (`temporary` or `permanent`) and `--default-value` are required. `--default-value` is the default targeting rule value every environment starts with, not the in-code default value an application passes to the SDK.
-- `--description <text>`; `--client-only` or `--server-only`, without which client and server SDKs both receive the config; `--tag <name>`, repeatable, naming an existing tag of the project; and `--variation <name=value>`, repeatable, for an experiment's variations.
+- `--description <text>`; `--client-only` or `--server-only`, without which client and server SDKs both receive the config; and `--variation <name=value>`, repeatable, for an experiment's variations.
+- `--tag <name>`, repeatable, names a tag the project already has, and `--new-tag <name>`, repeatable, creates a tag with that name in the project's tag catalog. The config gets the tags of both, at most 20 in all. Every `--tag` name is looked up before any tag is created, so a misspelled `--tag` creates nothing; a name no tag has, a `--new-tag` name a tag already has, a `--new-tag` name given twice and a name given with both options exit with 2. When a later step fails, such as a key that is taken, the tags already created stay in the catalog, and the command names them so you can pass them with `--tag` next time.
 - The values of `--default-value` and `--variation` are read in the config's type: `true` or `false`, a number for an integer, float or timespan, the text as written for a string, enum or URL, and JSON for a JSON config, with `@file` reading it from a file. A value that does not fit the type is a usage error.
 - Constraints, each accepted only by its types: `--min` and `--max` (a value may equal them) for an integer, float or timespan; `--exclusive-min` and `--exclusive-max` for an integer or float; `--unit` (`milliseconds`, `seconds` or `minutes`) and `--allow-fractions` for a timespan, which needs `--unit`, `--min` and `--max`; `--allowed-value`, repeatable, and `--enum-value-type string|number` (default `string`) for an enum; `--https-only` for a URL, without which any HTTP or HTTPS URL is accepted; and `--json-schema <file>` for a JSON config. An option of another type is a usage error naming the types it belongs to. A timespan without `--unit`, `--min` or `--max` is a usage error too.
 
@@ -231,7 +240,7 @@ configdirector configs create --key checkout-timeout --type timespan --role conf
 
 When the project already has a config with the key, as its current key or an old one, nothing is created: the command prints that config's key, type, role, lifetime and lifecycle state, and exits with 1. When ConfigDirector refuses the config for another reason, it exits with 2 and lists the reasons. With `--json`, it prints the created config as received, or the existing config when the key is taken.
 
-`configs create` needs `projects:read`, `configs:create`, and `configs:read` to show the config that already has the key; `--tag` also needs `tags:read` and `config-settings:update`. The config shows in the audit log with the source CLI.
+`configs create` needs `projects:read`, `configs:create`, and `configs:read` to show the config that already has the key; `--tag` also needs `tags:read`, and `--new-tag` needs `tags:create`. The config shows in the audit log with the source CLI.
 
 ## Change targeting rules
 
@@ -274,6 +283,59 @@ 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.
 
+## Change segments
+
+```bash
+configdirector segments create --segment beta-testers.json
+configdirector segments update beta-testers --segment beta-testers.json
+configdirector segments delete beta-testers
+```
+
+`segments create` creates a segment from the file, or from stdin with `--segment -`, and `segments update <key>` replaces the segment the key names with it:
+
+```json
+{
+  "key": "beta-testers",
+  "name": "Beta testers",
+  "groups": [
+    [
+      {
+        "kind": "attribute",
+        "attribute": "traits",
+        "trait": "/email",
+        "operator": "ends with any of",
+        "targetType": "text",
+        "targetValues": ["@example.com"]
+      }
+    ]
+  ],
+  "overrides": {
+    "7e6d5c4b-3a29-4810-8f7e-6d5c4b3a2918": [
+      [
+        {
+          "kind": "attribute",
+          "attribute": "traits",
+          "trait": "/email",
+          "operator": "ends with any of",
+          "targetType": "text",
+          "targetValues": ["@staff.example.com"]
+        }
+      ]
+    ]
+  }
+}
+```
+
+- The file holds the segment's `key`, `name` and condition `groups`, exactly as the Admin API takes them. `overrides` is optional and gives an environment condition groups of its own, keyed by the environment's ID, which `environments list --json` prints. `segments get --json` prints a segment in this shape, so you can edit it and send it back; fields the Admin API does not take, such as `usages`, are ignored.
+- A condition without an `id`, in the groups or in an override, gets a new one, and the IDs given are kept.
+- `update` replaces the key, the name and the groups, so a different `key` renames the segment, and the segment keeps its own ID whatever `id` the file holds. Without `overrides` in the file, the environment overrides stay as they are; `"overrides": {}` removes them all, and a map leaves exactly those environments overridden.
+- The CLI checks only that the file holds a JSON object. ConfigDirector checks the segment, and when it refuses it, for example because another segment has its key, the command exits with 2 and lists its reasons.
+- It asks for no confirmation. It prints `Created segment beta-testers in web-app.` or `Updated segment beta-testers in web-app.`, then the segment as `segments get` shows it. With `--json`, it prints the segment as the Admin API returned it.
+
+`segments delete <key>` deletes a segment and its environment overrides, with no confirmation, and prints `Deleted segment beta-testers from web-app.`; `--json` prints `{ "deletedSegmentKey": "beta-testers" }` with the key as given. While the targeting rules of a config use the segment, in any environment, it is not deleted: the command exits with 2 and lists each config with the environments whose rules use it, so you can remove those segment conditions with `targeting-rules set` first. A key no segment has exits with 2 for `update` and `delete`.
+
+`segments create` needs `projects:read` and `segments:create`, `segments update` needs `projects:read`, `segments:read` and `segments:update`, and `segments delete` needs `projects:read` and `segments:delete`. Without `environments:read`, they name environments by ID instead of by slug. The change shows in the audit log with the source CLI.
+
 ## Archive a config
 
 ```bash
@@ -300,7 +362,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. 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. A CI job can therefore tell a wrong config key from an outage.
 
 ## License
 

package/dist/configdirector.mjs

@@ -12,7 +12,7 @@ import { promisify } from "node:util";
 import { randomUUID } from "node:crypto";
 import { text } from "node:stream/consumers";
 //#region package.json
-var version = "0.11.0";
+var version = "0.13.0";
 //#endregion
 //#region src/CliError.ts
 var CliError = class extends Error {
@@ -246,11 +246,20 @@ const SegmentSchema = v.object({
 	usages: v.array(v.unknown())
 });
 const SegmentDefinitionSchema = v.object({
+	id: v.string(),
 	key: v.string(),
 	name: v.string(),
 	groups: v.array(ConditionGroupSchema),
 	overrides: v.record(v.string(), v.array(ConditionGroupSchema))
 });
+const SegmentUsageSchema = v.object({
+	configKey: v.string(),
+	environmentIds: v.array(v.string())
+});
+const SegmentInUseBodySchema = v.object({
+	code: v.literal("SEGMENT_IN_USE"),
+	usages: v.array(SegmentUsageSchema)
+});
 //#endregion
 //#region src/admin-api/targeting-rules-reference.ts
 const TargetingRulesReferenceSchema = v.object({
@@ -386,7 +395,10 @@ const ConfigActivitySchema = v.object({ latestEvaluations: v.array(v.object({
 	sdkVersion: v.nullable(v.string()),
 	time: v.pipe(v.string(), v.isoTimestamp())
 })) });
-const TagSchema = v.object({ id: v.string() });
+const TagSchema = v.object({
+	id: v.string(),
+	name: v.string()
+});
 const tagFilterQuery = (tagFilter) => {
 	switch (tagFilter.form) {
 		case "every-config": return "";
@@ -426,6 +438,16 @@ const failureFor = (url, response, body) => {
 	}
 };
 const isMissingResource = (received) => received.response.status === 404 && v.is(MissingResourceBodySchema, received.body);
+const isSegmentInUse = (received) => received.response.status === 409 && v.is(SegmentInUseBodySchema, received.body);
+const segmentDeletionOutcomeOf = (received) => {
+	if (isMissingResource(received)) return { outcome: "not-found" };
+	if (isSegmentInUse(received)) return {
+		outcome: "in-use",
+		usages: received.body.usages
+	};
+	if (!received.response.ok) throw failureFor(received.url, received.response, received.body);
+	return { outcome: "deleted" };
+};
 const parsedResponseOf = ({ url, response, body }, schema) => {
 	if (!response.ok) throw failureFor(url, response, body);
 	const parsedBody = v.safeParse(schema, body);
@@ -468,9 +490,30 @@ var AdminApiClient = class {
 	getSegment(projectId, segmentKey) {
 		return this.getIfFound(`/v1/projects/${encodeURIComponent(projectId)}/segments/${encodeURIComponent(segmentKey)}`, SegmentDefinitionSchema);
 	}
+	createSegment(projectId, request) {
+		return this.requestJson(`/v1/projects/${encodeURIComponent(projectId)}/segments`, SegmentDefinitionSchema, {
+			method: "POST",
+			body: request
+		});
+	}
+	updateSegment(projectId, segmentKey, request) {
+		return this.requestIfFound(`/v1/projects/${encodeURIComponent(projectId)}/segments/${encodeURIComponent(segmentKey)}`, SegmentDefinitionSchema, {
+			method: "PUT",
+			body: request
+		});
+	}
+	async deleteSegment(projectId, segmentKey) {
+		return segmentDeletionOutcomeOf(await this.send(`/v1/projects/${encodeURIComponent(projectId)}/segments/${encodeURIComponent(segmentKey)}`, { method: "DELETE" }));
+	}
 	async findTagByName(projectId, name) {
 		return (await this.getIfFound(`/v1/projects/${encodeURIComponent(projectId)}/tags/by-name?${new URLSearchParams({ name })}`, TagSchema))?.parsedBody;
 	}
+	async createTag(projectId, name) {
+		return (await this.requestJson(`/v1/projects/${encodeURIComponent(projectId)}/tags`, TagSchema, {
+			method: "POST",
+			body: { name }
+		})).parsedBody;
+	}
 	createConfig(projectId, request) {
 		return this.requestJson(`/v1/projects/${encodeURIComponent(projectId)}/configs`, CreatedConfigSchema, {
 			method: "POST",
@@ -1168,6 +1211,9 @@ const newConfigOf = async (options, workingDirectory) => {
 	};
 };
 //#endregion
+//#region src/plural.ts
+const plural = (count, singular, pluralForm) => count === 1 ? singular : pluralForm;
+//#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.");
@@ -1321,13 +1367,78 @@ const creationOutput = (project, newConfig, creation) => {
 		};
 	}
 };
+const MAXIMUM_CONFIG_TAGS = 20;
+const sameTagName = (name, otherName) => name.toLowerCase() === otherName.toLowerCase();
+const configTagNamesOf = (options) => {
+	const existingTagNames = options.tag ?? [];
+	const newTagNames = options.newTag ?? [];
+	const repeatedNewTagName = newTagNames.find((name, index) => newTagNames.slice(0, index).some((earlierName) => sameTagName(earlierName, name)));
+	if (repeatedNewTagName !== void 0) throw new CliError(`--new-tag gives the tag name "${repeatedNewTagName}" more than once. Case doesn't matter in tag names.`);
+	const nameInBothOptions = newTagNames.find((name) => existingTagNames.some((existingTagName) => sameTagName(existingTagName, name)));
+	if (nameInBothOptions !== void 0) throw new CliError(`--tag and --new-tag both give the tag name "${nameInBothOptions}". Case doesn't matter in tag names. Use --tag for a tag the project has and --new-tag for a tag to create.`);
+	const tagCount = existingTagNames.length + newTagNames.length;
+	if (tagCount > MAXIMUM_CONFIG_TAGS) throw new CliError(`--tag and --new-tag give ${tagCount} tags, but a config can have at most ${MAXIMUM_CONFIG_TAGS}.`);
+	return {
+		existingTagNames,
+		newTagNames
+	};
+};
+const createNewTag = async (client, project, name) => {
+	try {
+		return await client.createTag(project.id, name);
+	} catch (error) {
+		if (error instanceof ApiValidationError) throw new CliError(`${error.message}\nTo assign a tag the project already has, use --tag instead of --new-tag.`);
+		throw error;
+	}
+};
+const CREATED_TAGS_LEFT_UNASSIGNED = {
+	created: false,
+	"key-taken": true,
+	failed: true
+};
+const unassignedTagsNoticeOf = (createdTags, ending) => {
+	const [firstTag, ...laterTags] = createdTags;
+	return firstTag !== void 0 && CREATED_TAGS_LEFT_UNASSIGNED[ending] ? {
+		form: "tags-left-unassigned",
+		tags: [firstTag, ...laterTags]
+	} : { form: "none" };
+};
+const quotedTagName = (tag) => `"${tag.name}"`;
+const quotedTagNames = ([firstTag, ...laterTags]) => {
+	const lastTag = laterTags.at(-1);
+	return lastTag === void 0 ? quotedTagName(firstTag) : `${[firstTag, ...laterTags.slice(0, -1)].map(quotedTagName).join(", ")} and ${quotedTagName(lastTag)}`;
+};
+const unassignedTagsText = (project, tags) => {
+	const count = tags.length;
+	return `Created the ${plural(count, "tag", "tags")} ${quotedTagNames(tags)}. ${plural(count, "It stays", "They stay")} in ${project.slug}'s tag catalog, so pass ${plural(count, "it", "them")} with --tag next time.`;
+};
+const writeUnassignedTagsNotice = (context, project, createdTags, ending) => {
+	const notice = unassignedTagsNoticeOf(createdTags, ending);
+	switch (notice.form) {
+		case "none": return;
+		case "tags-left-unassigned":
+			context.invocation.stderr.write(`${unassignedTagsText(project, notice.tags)}\n`);
+			return;
+	}
+};
 const createConfig = async (context, _commandArguments, options) => {
 	const newConfig = await newConfigOf(options, context.invocation.workingDirectory);
+	const tagNames = configTagNamesOf(options);
 	const { client, project } = await connectToLinkedProject(context);
-	return creationOutput(project, newConfig, await requestCreation(client, project, {
-		...newConfig,
-		tagIds: await tagIdsNamed(client, project, options.tag ?? [])
-	}));
+	const existingTagIds = await tagIdsNamed(client, project, tagNames.existingTagNames);
+	const createdTags = [];
+	try {
+		for (const name of tagNames.newTagNames) createdTags.push(await createNewTag(client, project, name));
+		const creation = await requestCreation(client, project, {
+			...newConfig,
+			tagIds: [...existingTagIds, ...createdTags.map((tag) => tag.id)]
+		});
+		writeUnassignedTagsNotice(context, project, createdTags, creation.outcome);
+		return creationOutput(project, newConfig, creation);
+	} catch (error) {
+		writeUnassignedTagsNotice(context, project, createdTags, "failed");
+		throw error;
+	}
 };
 const archiveConfig = async (context, [configKey]) => {
 	const { client, project } = await connectToLinkedProject(context);
@@ -1777,9 +1888,6 @@ const listProjects = async (context) => {
 	};
 };
 //#endregion
-//#region src/plural.ts
-const plural = (count, singular, pluralForm) => count === 1 ? singular : pluralForm;
-//#endregion
 //#region src/scanned-repository/short-commit.ts
 const SHORT_COMMIT_LENGTH = 7;
 const shortCommit = (commit) => commit.slice(0, SHORT_COMMIT_LENGTH);
@@ -3257,7 +3365,7 @@ const sdkFamilies = {
 	"nuxt-server": {
 		sdkType: "server",
 		extensions: javascriptExtensions,
-		importMarkers: ["useConfigDirectorClient"],
+		importMarkers: ["useConfigDirectorServerClient", "useConfigDirectorClient"],
 		projectArea: "nuxt-server",
 		calls: javascriptClientCalls
 	},
@@ -4440,6 +4548,42 @@ 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;
+const conditionGroupWithIds = (group) => Array.isArray(group) ? group.map(conditionWithId) : group;
+const conditionGroupsWithIds = (groups) => groups.map(conditionGroupWithIds);
+const overridesWithIds = (overrides) => Object.fromEntries(Object.entries(overrides).map(([environmentId, groups]) => [environmentId, Array.isArray(groups) ? conditionGroupsWithIds(groups) : groups]));
+const withGeneratedConditionIds = (segment) => ({
+	...segment,
+	...Array.isArray(segment.groups) ? { groups: conditionGroupsWithIds(segment.groups) } : {},
+	...isJsonObject(segment.overrides) ? { overrides: overridesWithIds(segment.overrides) } : {}
+});
+//#endregion
 //#region src/segments/segment-text.ts
 const conditionGroupLines = (heading, groups) => [
 	"",
@@ -4470,22 +4614,72 @@ const listSegments = async (context) => {
 		exitCode: ExitCode.success
 	};
 };
-const environmentSlugsFor = async (client, project, segment) => {
-	if (Object.keys(segment.overrides).length === 0) return /* @__PURE__ */ new Map();
+const environmentSlugsById = async (client, project) => {
 	const environments = await ifPermitted(client.listEnvironments(project.id));
 	return new Map((environments?.parsedBody ?? []).map((environment) => [environment.id, environment.slug]));
 };
+const overrideEnvironmentSlugsOf = async (client, project, segment) => Object.keys(segment.overrides).length === 0 ? /* @__PURE__ */ new Map() : environmentSlugsById(client, project);
+const noSegmentWithKey = (project, segmentKey) => new CliError(`No segment in ${project.slug} has the key "${segmentKey}".`);
 const getSegment = async (context, [segmentKey]) => {
 	const { client, project } = await connectToLinkedProject(context);
 	const receivedSegment = await client.getSegment(project.id, segmentKey);
-	if (receivedSegment === void 0) throw new CliError(`No segment in ${project.slug} has the key "${segmentKey}".`);
+	if (receivedSegment === void 0) throw noSegmentWithKey(project, segmentKey);
 	const { parsedBody: segment, responseBody } = receivedSegment;
 	return {
 		json: responseBody,
-		text: segmentText(segment, await environmentSlugsFor(client, project, segment)),
+		text: segmentText(segment, await overrideEnvironmentSlugsOf(client, project, segment)),
+		exitCode: ExitCode.success
+	};
+};
+const createSegment = async (context, _commandArguments, options) => {
+	const requestedSegment = withGeneratedConditionIds(await readSegmentFile(options.segment, context.invocation));
+	const { client, project } = await connectToLinkedProject(context);
+	const { parsedBody: segment, responseBody } = await client.createSegment(project.id, requestedSegment);
+	return {
+		json: responseBody,
+		text: [`Created segment ${segment.key} in ${project.slug}.`, segmentText(segment, await overrideEnvironmentSlugsOf(client, project, segment))].join("\n"),
+		exitCode: ExitCode.success
+	};
+};
+const updateSegment = async (context, [segmentKey], options) => {
+	const requestedSegment = withGeneratedConditionIds(await readSegmentFile(options.segment, context.invocation));
+	const { client, project } = await connectToLinkedProject(context);
+	const currentSegment = await client.getSegment(project.id, segmentKey);
+	if (currentSegment === void 0) throw noSegmentWithKey(project, segmentKey);
+	const updatedSegment = await client.updateSegment(project.id, segmentKey, {
+		...requestedSegment,
+		id: currentSegment.parsedBody.id
+	});
+	if (updatedSegment === void 0) throw noSegmentWithKey(project, segmentKey);
+	const { parsedBody: segment, responseBody } = updatedSegment;
+	return {
+		json: responseBody,
+		text: [`Updated segment ${segmentKey} in ${project.slug}.`, segmentText(segment, await overrideEnvironmentSlugsOf(client, project, segment))].join("\n"),
 		exitCode: ExitCode.success
 	};
 };
+const usageLine = (usage, environmentSlugs) => {
+	const environmentNames = usage.environmentIds.map((environmentId) => environmentSlugs.get(environmentId) ?? environmentId);
+	return `  ${usage.configKey} in ${environmentNames.join(", ")}`;
+};
+const segmentInUseError = (segmentKey, usages, environmentSlugs) => new CliError([
+	`The targeting rules of ${usages.length} ${plural(usages.length, "config use", "configs use")} the segment ${segmentKey}, so it was not deleted:`,
+	...usages.map((usage) => usageLine(usage, environmentSlugs)),
+	"Remove those segment conditions first, with configdirector targeting-rules set."
+].join("\n"));
+const deleteSegment = async (context, [segmentKey]) => {
+	const { client, project } = await connectToLinkedProject(context);
+	const deletion = await client.deleteSegment(project.id, segmentKey);
+	switch (deletion.outcome) {
+		case "deleted": return {
+			json: { deletedSegmentKey: segmentKey },
+			text: [`Deleted segment ${segmentKey} from ${project.slug}.`, ""].join("\n"),
+			exitCode: ExitCode.success
+		};
+		case "not-found": throw noSegmentWithKey(project, segmentKey);
+		case "in-use": throw segmentInUseError(segmentKey, deletion.usages, await environmentSlugsById(client, project));
+	}
+};
 //#endregion
 //#region src/targeting-rules/reference-text.ts
 const headedListLines = (heading, items) => [heading, ...items.map((item) => `  ${item}`)];
@@ -4505,28 +4699,7 @@ const targetingRulesReferenceText = (reference) => [
 ].join("\n");
 //#endregion
 //#region src/targeting-rules/targeting-rules-file.ts
-const STANDARD_INPUT_ARGUMENT = "-";
-const readRulesSource = async (rulesArgument, invocation) => {
-	if (rulesArgument === STANDARD_INPUT_ARGUMENT) return {
-		origin: "--rules reads stdin",
-		contents: await text(invocation.stdin)
-	};
-	const { file, contents } = await readOptionFile("--rules", rulesArgument, invocation.workingDirectory);
-	return {
-		origin: `--rules names ${file}`,
-		contents
-	};
-};
-const readTargetingRulesFile = async (rulesArgument, invocation) => {
-	const { origin, contents } = await readRulesSource(rulesArgument, invocation);
-	const targetingRules = parseJson(contents);
-	if (!isJsonObject(targetingRules)) throw new CliError(`${origin}, which does not hold a JSON object. It takes {"defaultValue": ..., "rules": [...]}, like an entry of targets in configs get --json.`);
-	return targetingRules;
-};
-const withId = (entry) => entry.id === void 0 ? {
-	id: randomUUID(),
-	...entry
-} : entry;
+const readTargetingRulesFile = (rulesArgument, invocation) => readRequestFile("--rules", rulesArgument, invocation, "It takes {\"defaultValue\": ..., \"rules\": [...]}, like an entry of targets in configs get --json.");
 const conditionOrPercentageWithId = (conditionOrPercentage) => isJsonObject(conditionOrPercentage) ? withId(conditionOrPercentage) : conditionOrPercentage;
 const conditionsOrPercentagesWithIds = (rule, field) => {
 	const conditionsOrPercentages = rule[field];
@@ -4784,6 +4957,7 @@ const validate = async (context, [path]) => {
 //#endregion
 //#region src/run.ts
 const DEFAULT_BASE_URL = "https://api.configdirector.com";
+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;
 	while (trimmedUrl.endsWith("/")) trimmedUrl = trimmedUrl.slice(0, -1);
@@ -4834,11 +5008,14 @@ const run = async (invocation) => {
 	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)).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").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)").choices(CONFIG_LIFETIMES).makeOptionMandatory()).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("--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("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)").choices(CONFIG_LIFETIMES).makeOptionMandatory()).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("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 a project's segments and show one segment");
+	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").action(commandAction(listSegments));
 	segmentsCommand.command("get").argument("<key>", "the segment's key").description("show a segment's condition groups and its environment overrides").action(commandAction(getSegment));
+	segmentsCommand.command("create").description("create a segment from a JSON file").requiredOption("--segment <file>", SEGMENT_FILE_DESCRIPTION).addHelpText("after", "\nThe file holds {\"key\": ..., \"name\": ..., \"groups\": [...], \"overrides\": {...}}, like the output of segments get --json, so you can edit that output and send it. groups lists the condition groups, and a context is in the segment when every condition of any one group matches. overrides is optional: it maps an environment's id, which environments list --json shows, to the condition groups used there instead. A condition without an id gets a new one.").action(commandAction(createSegment));
+	segmentsCommand.command("update").argument("<key>", "the segment's key").description("replace a segment's key, name and condition groups with a JSON file, and its environment overrides when the file has them").requiredOption("--segment <file>", SEGMENT_FILE_DESCRIPTION).addHelpText("after", "\nThe file takes the same form as for segments create, and the segment keeps its id whatever id the file holds. Its key, name and condition groups are replaced, so a different key renames it. Without overrides in the file, the environment overrides stay as they are; with \"overrides\": {} they are all removed, and a map leaves exactly those environments overridden. A condition without an id gets a new one.").action(commandAction(updateSegment));
+	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 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.11.0",
+  "version": "0.13.0",
   "description": "Command line tool for ConfigDirector, the managed configuration and feature flag service.",
   "license": "MIT",
   "author": "ConfigDirector",