@configdirector/cli 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to `@configdirector/cli` are documented here. The format fol
 
 ## [Unreleased]
 
+## [0.14.0] - 2026-10-27
+
+### Added
+
+- `configdirector scan` and `validate` find configs read through `evaluate`, which the JavaScript SDKs added in `@configdirector/client-sdk`, `react-web-sdk`, `vue-sdk` and `react-native-sdk` 1.10.0, `server-sdk` 1.12.0, and `nextjs-sdk` and `nuxt-sdk` 1.13.0. A call such as `client.evaluate("new-checkout", false)` is reported and checked as `client.getValue("new-checkout", false)` is, with its in-code default value, so `validate` fails on a wrong key or type there too.
+
+## [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

package/README.md

@@ -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
 

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.12.0";
+var version = "0.14.0";
 //#endregion
 //#region src/CliError.ts
 var CliError = class extends Error {
@@ -395,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 "";
@@ -505,6 +508,12 @@ var AdminApiClient = class {
 	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",
@@ -1202,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.");
@@ -1355,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);
@@ -1811,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);
@@ -3152,6 +3226,7 @@ const testAnnotation = (name) => ({
 });
 const javascriptClientCalls = [
 	read("getValue"),
+	read("evaluate"),
 	read("watch"),
 	keyOnly("unwatch")
 ];
@@ -3291,7 +3366,7 @@ const sdkFamilies = {
 	"nuxt-server": {
 		sdkType: "server",
 		extensions: javascriptExtensions,
-		importMarkers: ["useConfigDirectorClient"],
+		importMarkers: ["useConfigDirectorServerClient", "useConfigDirectorClient"],
 		projectArea: "nuxt-server",
 		calls: javascriptClientCalls
 	},
@@ -4934,7 +5009,7 @@ 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, 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));

package/package.json

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