@configdirector/cli 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to `@configdirector/cli` are documented here. The format fol
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-10-28
+
+### Added
+
+- `--no-headers` on `configdirector projects list`, `environments list`, `configs list`, `configs activity`, `segments list` and `repositories list` leaves out the header row and prints the lines alone, as earlier versions did. A script that reads these lines can add `--no-headers`, or read `--json`, which has not changed.
+
+### Changed
+
+- `configdirector projects list`, `environments list`, `configs list`, `configs activity`, `segments list` and `repositories list` print a header row that names their columns, such as `KEY   TYPE   ROLE   LIFETIME   STATE` above the configs. The columns line up under it, so a header longer than every value in its column widens that column. An empty list still prints only its sentence, such as `No configs found in web-app.`
+
 ## [0.14.0] - 2026-10-27
 
 ### Added

package/README.md

@@ -88,16 +88,17 @@ A project holds at most 50 scanned repositories, and one upload holds at most 10
 configdirector repositories list
 ```
 
-`repositories list` lists the repositories whose scan was uploaded to the project, one per line, with the commit, when it was scanned in UTC, and how many references and dynamic references it holds, and ends with how many scanned repositories the project has out of the 50 it can hold:
+`repositories list` lists the repositories whose scan was uploaded to the project, one per line under a header row, with the commit, when it was scanned in UTC, and how many references and dynamic references it holds, and ends with how many scanned repositories the project has out of the 50 it can hold:
 
 ```txt
+REPOSITORY           COMMIT    SCANNED                REFERENCES      DYNAMIC REFERENCES
 ConfigDirector/cli   4d40f50   2026-10-17 10:00 UTC   12 references   1 dynamic reference
 acme/storefront      9f3e2a1   2026-10-16 09:12 UTC   1 reference     0 dynamic references
 
 web-app has 2 of the 50 scanned repositories a project can hold.
 ```
 
-A repository uploaded without a commit shows `no commit`. With `--json`, it prints the Admin API's response as received, which also holds each repository's remote URL and how many files its scan read. `repositories list` needs `projects:read` and `code-references:read`.
+A repository uploaded without a commit shows `no commit`, and `--no-headers` leaves out the header row. With `--json`, it prints the Admin API's response as received, which also holds each repository's remote URL and how many files its scan read. `repositories list` needs `projects:read` and `code-references:read`.
 
 ```bash
 configdirector repositories remove acme/storefront
@@ -210,6 +211,8 @@ production (live)
   Default targeting rule: false
 ```
 
+`projects list`, `environments list`, `configs list`, `configs activity` and `segments list` print a header row that names their columns above their lines, such as `KEY   TYPE   ROLE   LIFETIME   STATE` for `configs list`, and `--no-headers` leaves it out. An empty list prints only a sentence, such as `No configs found in web-app.`
+
 With `--json`, each prints the Admin API's response as received, except `configs list --state`, which prints only the configs in that state. A key no config or segment has exits with 2.
 
 `projects list` needs `projects:read`. The others need `projects:read` to find the project, and `environments list` needs `environments:read`, `configs list`, `configs get` and `configs activity` need `configs:read`, plus `tags:read` for `--tag`, and `segments list` and `segments get` need `segments:read`. Without `segments:read`, `configs get` shows a segment condition's segment ID instead of its name; without `environments:read`, `segments get` names an override's environment by its ID instead of its slug.

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.14.0";
+var version = "0.15.0";
 //#endregion
 //#region src/CliError.ts
 var CliError = class extends Error {
@@ -910,6 +910,7 @@ const getApiToken = async (context) => {
 const COLUMN_GAP = "   ";
 const widestCellOf = (rows, column) => Math.max(0, ...rows.map((row) => row[column]?.length ?? 0));
 const alignedColumns = (rows) => rows.map((row) => row.map((cell, column) => column === row.length - 1 ? cell : cell.padEnd(widestCellOf(rows, column))).join(COLUMN_GAP));
+const alignedListing = (headerRow, rows, options) => alignedColumns(options.headers ? [headerRow, ...rows] : rows);
 //#endregion
 //#region src/old-key-lines.ts
 const oldKeyLines = (requestedKey, currentKey) => requestedKey === currentKey ? [] : [`${requestedKey} is an old key of ${currentKey}.`];
@@ -1289,6 +1290,13 @@ const tagFilterOf = async (client, project, options) => {
 	};
 };
 const configsInState = (listedConfigs, state) => state === void 0 ? listedConfigs : listedConfigs.filter((listedConfig) => listedConfig.config.state === state);
+const CONFIG_SUMMARY_HEADER_ROW = [
+	"KEY",
+	"TYPE",
+	"ROLE",
+	"LIFETIME",
+	"STATE"
+];
 const summaryColumnsOf = (config) => [
 	config.key,
 	config.type,
@@ -1296,13 +1304,13 @@ const summaryColumnsOf = (config) => [
 	config.lifetime,
 	config.state
 ];
-const configLines = (projectSlug, configs) => configs.length === 0 ? [`No configs found in ${projectSlug}.`] : alignedColumns(configs.map(summaryColumnsOf));
+const configLines = (projectSlug, configs, options) => configs.length === 0 ? [`No configs found in ${projectSlug}.`] : alignedListing(CONFIG_SUMMARY_HEADER_ROW, configs.map(summaryColumnsOf), options);
 const listConfigs = async (context, _commandArguments, options) => {
 	const { client, project } = await connectToLinkedProject(context);
 	const listedConfigs = configsInState(await client.listConfigs(project.id, await tagFilterOf(client, project, options)), options.state);
 	return {
 		json: listedConfigs.map((listedConfig) => listedConfig.receivedConfig),
-		text: [...configLines(project.slug, listedConfigs.map((listedConfig) => listedConfig.config)), ""].join("\n"),
+		text: [...configLines(project.slug, listedConfigs.map((listedConfig) => listedConfig.config), options), ""].join("\n"),
 		exitCode: ExitCode.success
 	};
 };
@@ -1450,36 +1458,47 @@ const archiveConfig = async (context, [configKey]) => {
 	};
 };
 const sdkDescription = (evaluation) => [evaluation.sdkName ?? "unknown SDK", ...evaluation.sdkVersion === null ? [] : [evaluation.sdkVersion]].join(" ");
-const activityLines = (configKey, activity) => activity.latestEvaluations.length === 0 ? [`No SDK evaluations of ${configKey} found.`] : alignedColumns(activity.latestEvaluations.map((evaluation) => [
+const LATEST_EVALUATION_HEADER_ROW = [
+	"ENVIRONMENT",
+	"SDK KEY",
+	"SDK",
+	"LAST EVALUATED"
+];
+const activityLines = (configKey, activity, options) => activity.latestEvaluations.length === 0 ? [`No SDK evaluations of ${configKey} found.`] : alignedListing(LATEST_EVALUATION_HEADER_ROW, activity.latestEvaluations.map((evaluation) => [
 	evaluation.environment.slug,
 	evaluation.source,
 	sdkDescription(evaluation),
 	utcMinute(evaluation.time)
-]));
-const showConfigActivity = async (context, [configKey]) => {
+]), options);
+const showConfigActivity = async (context, [configKey], options) => {
 	const { client, project } = await connectToLinkedProject(context);
 	const receivedActivity = await client.getConfigActivity(project.id, configKey);
 	if (receivedActivity === void 0) throw new CliError(`No config in ${project.slug} has the key "${configKey}".`);
 	return {
 		json: receivedActivity.responseBody,
-		text: [...activityLines(configKey, receivedActivity.parsedBody), ""].join("\n"),
+		text: [...activityLines(configKey, receivedActivity.parsedBody, options), ""].join("\n"),
 		exitCode: ExitCode.success
 	};
 };
 //#endregion
 //#region src/commands/environments.ts
+const ENVIRONMENT_HEADER_ROW = [
+	"SLUG",
+	"NAME",
+	"LIVE"
+];
 const environmentColumns = (environment) => environment.live ? [
 	environment.slug,
 	environment.name,
 	"live"
 ] : [environment.slug, environment.name];
-const environmentLines = (projectSlug, environments) => environments.length === 0 ? [`No environments found in ${projectSlug}.`] : alignedColumns(environments.map(environmentColumns));
-const listEnvironments = async (context) => {
+const environmentLines = (projectSlug, environments, options) => environments.length === 0 ? [`No environments found in ${projectSlug}.`] : alignedListing(ENVIRONMENT_HEADER_ROW, environments.map(environmentColumns), options);
+const listEnvironments = async (context, _commandArguments, options) => {
 	const { client, project } = await connectToLinkedProject(context);
 	const { parsedBody: environments, responseBody } = await client.listEnvironments(project.id);
 	return {
 		json: responseBody,
-		text: [...environmentLines(project.slug, environments), ""].join("\n"),
+		text: [...environmentLines(project.slug, environments, options), ""].join("\n"),
 		exitCode: ExitCode.success
 	};
 };
@@ -1875,15 +1894,16 @@ const logout = async (context) => {
 };
 //#endregion
 //#region src/commands/projects.ts
-const projectLines = (projects) => projects.length === 0 ? ["No projects found."] : alignedColumns(projects.map((project) => [project.slug, project.name]));
-const listProjects = async (context) => {
+const PROJECT_HEADER_ROW = ["SLUG", "NAME"];
+const projectLines = (projects, options) => projects.length === 0 ? ["No projects found."] : alignedListing(PROJECT_HEADER_ROW, projects.map((project) => [project.slug, project.name]), options);
+const listProjects = async (context, _commandArguments, options) => {
 	const { parsedBody: projects, responseBody } = await new AdminApiClient({
 		baseUrl: context.baseUrl,
 		token: (await configuredApiToken(context)).token
 	}).listProjects();
 	return {
 		json: responseBody,
-		text: [...projectLines(projects), ""].join("\n"),
+		text: [...projectLines(projects, options), ""].join("\n"),
 		exitCode: ExitCode.success
 	};
 };
@@ -1895,6 +1915,13 @@ const shortCommit = (commit) => commit.slice(0, SHORT_COMMIT_LENGTH);
 //#region src/commands/repositories.ts
 const MAX_SCANNED_REPOSITORIES_PER_PROJECT = 50;
 const commitDescription = (commit) => commit === null ? "no commit" : shortCommit(commit);
+const SCANNED_REPOSITORY_HEADER_ROW = [
+	"REPOSITORY",
+	"COMMIT",
+	"SCANNED",
+	"REFERENCES",
+	"DYNAMIC REFERENCES"
+];
 const scannedRepositoryColumnsOf = (repository) => [
 	repository.name,
 	commitDescription(repository.commit),
@@ -1902,17 +1929,17 @@ const scannedRepositoryColumnsOf = (repository) => [
 	`${repository.referenceCount} ${plural(repository.referenceCount, "reference", "references")}`,
 	`${repository.dynamicReferenceCount} ${plural(repository.dynamicReferenceCount, "dynamic reference", "dynamic references")}`
 ];
-const scannedRepositoryLines = (projectSlug, repositories) => repositories.length === 0 ? [`No scanned repositories found in ${projectSlug}. Run configdirector scan --upload in a repository to upload its code references.`] : [
-	...alignedColumns(repositories.map(scannedRepositoryColumnsOf)),
+const scannedRepositoryLines = (projectSlug, repositories, options) => repositories.length === 0 ? [`No scanned repositories found in ${projectSlug}. Run configdirector scan --upload in a repository to upload its code references.`] : [
+	...alignedListing(SCANNED_REPOSITORY_HEADER_ROW, repositories.map(scannedRepositoryColumnsOf), options),
 	"",
 	`${projectSlug} has ${repositories.length} of the ${MAX_SCANNED_REPOSITORIES_PER_PROJECT} scanned repositories a project can hold.`
 ];
-const listScannedRepositories = async (context) => {
+const listScannedRepositories = async (context, _commandArguments, options) => {
 	const { client, project } = await connectToLinkedProject(context);
 	const { parsedBody: repositories, responseBody } = await client.listScannedRepositories(project.id);
 	return {
 		json: responseBody,
-		text: [...scannedRepositoryLines(project.slug, repositories), ""].join("\n"),
+		text: [...scannedRepositoryLines(project.slug, repositories, options), ""].join("\n"),
 		exitCode: ExitCode.success
 	};
 };
@@ -4601,17 +4628,22 @@ const segmentText = (segment, environmentSlugs) => [
 //#endregion
 //#region src/commands/segments.ts
 const usageDescription = (segment) => `used by ${segment.usages.length} ${plural(segment.usages.length, "config", "configs")}`;
-const segmentLines = (projectSlug, segments) => segments.length === 0 ? [`No segments found in ${projectSlug}.`] : alignedColumns(segments.map((segment) => [
+const SEGMENT_HEADER_ROW = [
+	"KEY",
+	"NAME",
+	"USED BY"
+];
+const segmentLines = (projectSlug, segments, options) => segments.length === 0 ? [`No segments found in ${projectSlug}.`] : alignedListing(SEGMENT_HEADER_ROW, segments.map((segment) => [
 	segment.key,
 	segment.name,
 	usageDescription(segment)
-]));
-const listSegments = async (context) => {
+]), options);
+const listSegments = async (context, _commandArguments, options) => {
 	const { client, project } = await connectToLinkedProject(context);
 	const { parsedBody: segments, responseBody } = await client.listSegments(project.id);
 	return {
 		json: responseBody,
-		text: [...segmentLines(project.slug, segments), ""].join("\n"),
+		text: [...segmentLines(project.slug, segments, options), ""].join("\n"),
 		exitCode: ExitCode.success
 	};
 };
@@ -4958,6 +4990,7 @@ const validate = async (context, [path]) => {
 //#endregion
 //#region src/run.ts
 const DEFAULT_BASE_URL = "https://api.configdirector.com";
+const NO_HEADERS_DESCRIPTION = "leave out the header row";
 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;
@@ -5003,16 +5036,16 @@ const run = async (invocation) => {
 	program.command("validate").argument("[path]", "directory or file to check (default: the current directory)").description("check every config key the code reads against the project's configs, exiting 1 when one is wrong").action(commandAction(validate));
 	program.command("evaluate").argument("<key>", "the config's key").description("show the value a context gets for a config in an environment, and why").requiredOption("--environment <slug>", "slug of the environment whose targeting rules to evaluate (required)").option("--context-kind <kind>", "context kind of the context to evaluate for (default: user)").option("--context-id <identifier>", "identifier of the context").option("--context-name <name>", "name of the context").option("--context-trait <name=value>", "a trait of the context, as a string, or name:=<json> for a number, boolean, array or object; repeatable", repeatedOption).option("--context-json <json>", "the whole context as a JSON object, or @<file> to read it from a file").option("--saved-context <kind:identifier>", "a context ConfigDirector saved from SDK evaluations in the environment, such as user:123").addHelpText("after", "\nGive the context with the --context-* options, with --context-json, or with --saved-context. Without any of them, the config is evaluated for an empty context, as an SDK given none would.").action(commandAction(evaluate));
 	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").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").action(commandAction(listEnvironments));
+	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");
-	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("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").action(commandAction(showConfigActivity));
+	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)").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));
+	segmentsCommand.command("list").description("list the project's segments with how many configs use each").option("--no-headers", NO_HEADERS_DESCRIPTION).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));
@@ -5021,7 +5054,7 @@ const run = async (invocation) => {
 	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));
 	const repositoriesCommand = program.command("repositories").description("list a project's scanned repositories and remove one");
-	repositoriesCommand.command("list").description("list the repositories whose scan was uploaded to the project, with their commit, scan time and reference counts").action(commandAction(listScannedRepositories));
+	repositoriesCommand.command("list").description("list the repositories whose scan was uploaded to the project, with their commit, scan time and reference counts").option("--no-headers", NO_HEADERS_DESCRIPTION).action(commandAction(listScannedRepositories));
 	repositoriesCommand.command("remove").argument("<name>", "the repository's name, as repositories list shows it, such as ConfigDirector/cli").description("remove a scanned repository and its code references from the project").addHelpText("after", "\nThe repository is removed with no confirmation, and the dashboard stops showing its code references. The next scan --upload from it adds it back.").action(commandAction(removeScannedRepository));
 	try {
 		await program.parseAsync(invocation.commandLineArguments, { from: "user" });

package/package.json

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