@configdirector/cli 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to `@configdirector/cli` are documented here. The format fol
 
 ## [Unreleased]
 
+## [0.17.0] - 2026-11-01
+
+### Added
+
+- `configdirector configs copy <key> --key <new key>` copies a config under a new key, in its project or, with `--to <project slug>`, in another project of the organization. The copy gets the config's settings and tags, and every environment's targeting rules and default targeting rule value, and starts as a new config with no old keys. In another project, environments are matched by slug, tags by name and segments by key, and `--environment <destination slug>=<source slug>`, repeatable, names the environment to copy from for an environment there with no environment of its slug in the config's project. The command prints the plan: each environment with the environment its rules come from, how many rules were copied and each rule dropped because the other project has no segment with its key, the environments it skipped, and the tags matched, created and skipped. `--dry-run` prints the plan without creating anything, and `--json` prints the Admin API's response as received. A dropped rule is not a failure: the command exits with 0, and with 2 when ConfigDirector refuses the copy, for example because the key is already in use or an environment has nothing to copy from.
+
 ## [0.16.0] - 2026-10-30
 
 ### 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, 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, 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.
 
@@ -246,6 +246,35 @@ When the project already has a config with the key, as its current key or an old
 
 `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.
 
+## Copy a config
+
+```bash
+configdirector configs copy search-ranking --key search-ranking --to mobile-app --environment qa=staging
+```
+
+`configs copy` copies a config under the key `--key` gives, in its project or, with `--to <project slug>`, in another project of the organization, and prints the plan:
+
+```txt
+Copied search-ranking in web-app to search-ranking in mobile-app.
+Environments:
+  production (live)   from production   2 rules copied   rule 3 dropped: mobile-app has no segment beta-testers
+  qa                  from staging      1 rule copied
+Skipped source environments:
+  test   mobile-app has no environment with this slug; create it there to copy its rules
+Tags:
+  search   matched
+  growth   created
+```
+
+- The 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.
+- In another project, environments are matched by slug, tags by name and segments by key. An environment there with no environment of the same slug in the config's project needs `--environment <destination slug>=<source slug>`, repeatable, to name the environment it copies from; `--environment` can also replace a slug match. A source environment with no environment of its slug there is skipped.
+- A targeting rule that uses a segment the other project doesn't have is dropped, and the plan names it by its position and the segment's key. A tag the other project doesn't have is created when the token has `tags:create`, and skipped otherwise.
+- `--dry-run` prints the plan without creating anything, saying what would be copied, dropped, skipped and created.
+
+The command exits with 0 when it copied the config or printed the plan, dropped rules included, and with 2 when ConfigDirector refuses the copy, for example because the key is in use or an environment has nothing to copy from, listing the reasons it gave. With `--json`, it prints the Admin API's response as received: the plan, and the created config with its targeting rules unless `--dry-run` was given.
+
+`configs copy` needs `projects:read` and `configs:create`, and `tags:create` to create the tags another project doesn't have. The copy shows in the audit log with the source CLI.
+
 ## Change targeting rules
 
 ```bash

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.16.0";
+var version = "0.17.0";
 //#endregion
 //#region src/CliError.ts
 var CliError = class extends Error {
@@ -96,6 +96,27 @@ var UnexpectedApiResponseError = class extends CliError {
 	}
 };
 //#endregion
+//#region src/admin-api/config-copy.ts
+const CopyPlanSchema = v.object({
+	environments: v.array(v.object({
+		slug: v.string(),
+		live: v.boolean(),
+		sourceSlug: v.string(),
+		rulesCopied: v.number(),
+		droppedRules: v.array(v.object({
+			position: v.number(),
+			segmentKey: v.string()
+		}))
+	})),
+	skippedSourceEnvironments: v.array(v.string()),
+	tags: v.object({
+		matched: v.array(v.string()),
+		created: v.array(v.string()),
+		skipped: v.array(v.string())
+	})
+});
+const CopyPlanResponseSchema = v.object({ plan: CopyPlanSchema });
+//#endregion
 //#region src/admin-api/config-creation.ts
 const CreatedConfigSchema = v.object({
 	key: v.string(),
@@ -516,6 +537,12 @@ var AdminApiClient = class {
 			body: request
 		});
 	}
+	copyConfig(projectId, configKey, request) {
+		return this.requestIfFound(`/v1/projects/${encodeURIComponent(projectId)}/configs/${encodeURIComponent(configKey)}/copy`, CopyPlanResponseSchema, {
+			method: "POST",
+			body: request
+		});
+	}
 	async evaluateConfig(projectId, configKey, request) {
 		const { responseBody, parsedBody } = await this.requestJson(`/v1/projects/${encodeURIComponent(projectId)}/configs/${encodeURIComponent(configKey)}/evaluate`, ConfigEvaluationSchema, {
 			method: "POST",
@@ -973,9 +1000,9 @@ const settingLines = (config) => [
 	`Lifecycle state: ${config.state}`,
 	...config.tags.length === 0 ? [] : [`Tags: ${config.tags.map((tag) => tag.name).join(", ")}`]
 ];
-const environmentHeading = (targetingRules) => targetingRules.environment.live ? `${targetingRules.environment.slug} (live)` : targetingRules.environment.slug;
+const environmentLabel = (environment) => environment.live ? `${environment.slug} (live)` : environment.slug;
 const targetingRuleLines = (targetingRules, segments) => [
-	environmentHeading(targetingRules),
+	environmentLabel(targetingRules.environment),
 	...targetingRules.rules.map((rule, index) => `  ${index + 1}. ${describeRule(rule, segments)}`),
 	`  Default targeting rule: ${targetingRules.defaultValue}`
 ];
@@ -987,6 +1014,89 @@ const configText = (config, requestedKey, segments) => [
 	""
 ].join("\n");
 //#endregion
+//#region src/plural.ts
+const plural = (count, singular, pluralForm) => count === 1 ? singular : pluralForm;
+//#endregion
+//#region src/same-slug.ts
+const sameSlug = (slug, otherSlug) => slug.toLowerCase() === otherSlug.toLowerCase();
+//#endregion
+//#region src/configs/copy-plan-text.ts
+const PLAN_WORDING = {
+	copy: {
+		headline: (copying) => `Copied ${copying.sourceKey} in ${copying.sourceProject.slug} to ${copying.copyKey} in ${copying.destinationProject.slug}.`,
+		rulesCopied: "copied",
+		ruleDropped: "dropped",
+		skippedSourceEnvironmentsHeading: "Skipped source environments:",
+		tagCreated: "created",
+		tagSkipped: "skipped"
+	},
+	"dry-run": {
+		headline: (copying) => `Nothing was created: this is the plan for copying ${copying.sourceKey} in ${copying.sourceProject.slug} to ${copying.copyKey} in ${copying.destinationProject.slug}.`,
+		rulesCopied: "would be copied",
+		ruleDropped: "would be dropped",
+		skippedSourceEnvironmentsHeading: "Source environments that would be skipped:",
+		tagCreated: "would be created",
+		tagSkipped: "would be skipped"
+	}
+};
+const droppedRuleDescription = (wordedPlan, droppedRule) => `rule ${droppedRule.position} ${wordedPlan.wording.ruleDropped}: ${wordedPlan.destinationProjectSlug} has no segment ${droppedRule.segmentKey}`;
+const environmentColumnsOf = (wordedPlan, environment) => [
+	environmentLabel(environment),
+	`from ${environment.sourceSlug}`,
+	`${environment.rulesCopied} ${plural(environment.rulesCopied, "rule", "rules")} ${wordedPlan.wording.rulesCopied}`,
+	...environment.droppedRules.length === 0 ? [] : [environment.droppedRules.map((droppedRule) => droppedRuleDescription(wordedPlan, droppedRule)).join("; ")]
+];
+const skippedSourceEnvironmentReasonOf = (plan, slug) => {
+	const destinationEnvironment = plan.environments.find((environment) => sameSlug(environment.slug, slug));
+	return destinationEnvironment === void 0 ? { reason: "no-destination-environment" } : {
+		reason: "destination-copies-another-source",
+		destinationEnvironment
+	};
+};
+const skippedSourceEnvironmentDescription = (destinationProjectSlug, slug, skipped) => {
+	switch (skipped.reason) {
+		case "no-destination-environment": return `${destinationProjectSlug} has no environment with this slug; create it there to copy its rules`;
+		case "destination-copies-another-source": return `${skipped.destinationEnvironment.slug} in ${destinationProjectSlug} copies from ${skipped.destinationEnvironment.sourceSlug} instead; --environment ${skipped.destinationEnvironment.slug}=${slug} copies this one`;
+	}
+};
+const skippedSourceEnvironmentRowsOf = ({ plan, destinationProjectSlug }) => plan.skippedSourceEnvironments.map((slug) => [slug, skippedSourceEnvironmentDescription(destinationProjectSlug, slug, skippedSourceEnvironmentReasonOf(plan, slug))]);
+const tagRowsOf = ({ plan, wording }) => [
+	...plan.tags.matched.map((name) => [name, "matched"]),
+	...plan.tags.created.map((name) => [name, wording.tagCreated]),
+	...plan.tags.skipped.map((name) => [name, `${wording.tagSkipped}: the API token cannot create tags`])
+];
+const sectionLines = (heading, rows) => rows.length === 0 ? [] : [heading, ...alignedColumns(rows).map((line) => `  ${line}`)];
+const copyPlanText = (copying, plan, mode) => {
+	const wordedPlan = {
+		plan,
+		destinationProjectSlug: copying.destinationProject.slug,
+		wording: PLAN_WORDING[mode]
+	};
+	return [
+		wordedPlan.wording.headline(copying),
+		...sectionLines("Environments:", plan.environments.map((environment) => environmentColumnsOf(wordedPlan, environment))),
+		...sectionLines(wordedPlan.wording.skippedSourceEnvironmentsHeading, skippedSourceEnvironmentRowsOf(wordedPlan)),
+		...sectionLines("Tags:", tagRowsOf(wordedPlan)),
+		""
+	].join("\n");
+};
+//#endregion
+//#region src/configs/environment-mapping.ts
+const MAPPING_SEPARATOR = "=";
+const mappedSlugsOf = (mapping) => {
+	const separatorIndex = mapping.indexOf(MAPPING_SEPARATOR);
+	const destinationSlug = mapping.slice(0, separatorIndex);
+	const sourceSlug = mapping.slice(separatorIndex + 1);
+	if (separatorIndex === -1 || destinationSlug === "" || sourceSlug === "") throw new CliError(`--environment takes <destination slug>=<source slug>, not ${mapping}.`);
+	return [destinationSlug, sourceSlug];
+};
+const environmentMappingOf = (mappings) => {
+	const mappedSlugs = (mappings ?? []).map(mappedSlugsOf);
+	const repeatedDestinationSlug = mappedSlugs.find(([destinationSlug], index) => mappedSlugs.slice(0, index).some(([earlierDestinationSlug]) => sameSlug(earlierDestinationSlug, destinationSlug)))?.[0];
+	if (repeatedDestinationSlug !== void 0) throw new CliError(`--environment maps the destination environment "${repeatedDestinationSlug}" more than once. Case doesn't matter in slugs.`);
+	return Object.fromEntries(mappedSlugs);
+};
+//#endregion
 //#region src/configs/new-config.ts
 const CONFIG_TYPES = [
 	"boolean",
@@ -1237,9 +1347,6 @@ 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.");
@@ -1250,8 +1357,7 @@ const requireLinkedProjectSlug = (context, settings) => {
 	if (slug === void 0) throw new CliError("Name the project with --project <slug>, CONFIGDIRECTOR_PROJECT, or `project` in configdirector.json, which `configdirector init` writes.");
 	return slug;
 };
-const findProjectBySlug = async (client, slug) => {
-	const { parsedBody: projects } = await client.listProjects();
+const projectWithSlug = (projects, slug) => {
 	const project = projects.find((listedProject) => listedProject.slug === slug);
 	if (project === void 0) throw new CliError(`No project in the API token's organization has the slug "${slug}".`);
 	return project;
@@ -1279,11 +1385,13 @@ const connectToLinkedProject = async (context) => {
 		baseUrl: context.baseUrl,
 		token: apiToken.token
 	});
-	const project = await findProjectBySlug(client, projectSlug);
+	const { parsedBody: organizationProjects } = await client.listProjects();
+	const project = projectWithSlug(organizationProjects, projectSlug);
 	refuseProjectOfAnotherOrganization(project, settings, apiToken);
 	return {
 		client,
 		project,
+		organizationProjects,
 		settings
 	};
 };
@@ -1473,6 +1581,29 @@ const createConfig = async (context, _commandArguments, options) => {
 		throw error;
 	}
 };
+const copyConfig = async (context, [configKey], options) => {
+	const environmentMapping = environmentMappingOf(options.environment);
+	const mode = options.dryRun ? "dry-run" : "copy";
+	const { client, project, organizationProjects } = await connectToLinkedProject(context);
+	const copying = {
+		sourceKey: configKey,
+		sourceProject: project,
+		copyKey: options.key,
+		destinationProject: options.to === void 0 ? project : projectWithSlug(organizationProjects, options.to)
+	};
+	const receivedPlan = await client.copyConfig(project.id, configKey, {
+		projectId: copying.destinationProject.id,
+		key: copying.copyKey,
+		environments: environmentMapping,
+		dryRun: mode === "dry-run"
+	});
+	if (receivedPlan === void 0) throw new CliError(`No config in ${project.slug} has the key "${configKey}".`);
+	return {
+		json: receivedPlan.responseBody,
+		text: copyPlanText(copying, receivedPlan.parsedBody.plan, mode),
+		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}".`);
@@ -5064,11 +5195,12 @@ 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 and archive a project's configs");
+	const configsCommand = program.command("configs").description("list, show, create, copy and archive a project's configs");
 	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("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.16.0",
+  "version": "0.17.0",
   "description": "Command line tool for ConfigDirector, the managed configuration and feature flag service.",
   "license": "MIT",
   "author": "ConfigDirector",