Skip to content

fix(cli): name the entity an environment in every string the os environments family prints#12429

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
os-litant merged 1 commit into from
Aug 26, 2026
Merged

fix(cli): name the entity an environment in every string the os environments family prints #12429

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions .changeset/cli-environments-entity-noun.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
---
"@objectstack/cli": patch
---

fix(cli): the `os environments` family calls the entity an environment, not a project, in every string it prints (#12153)

Per ADR-0006 the v5.0 rename `project` → `environment` has no aliases, and AGENTS.md
states "Project now only means the npm/monorepo sense". #10967 (PR #11227) renamed the
**command** (`os projects …` → `os environments …`) across these same five files; the
**entity noun** inside the strings oclif prints was left behind. A user ran
`os environments switch <id>` and the tool answered `✓ Active project: …`.

25 user-visible string literals in `packages/cli/src/commands/environments/` are swapped
to the post-rename noun. No behaviour, no flag or argument names, no exit codes, and no
`--format json` / `--format yaml` payloads change — those are produced by
`formatOutput(res, …)` straight from the control-plane response and are untouched.

| where | count | printed by |
| --- | --- | --- |
| `static override description` | 5 | `os environments --help` |
| flag / arg `description` | 7 | each command's own `--help` |
| success-path console output | 9 | `list` · `bind` · `create` · `show` · `switch` |
| `examples` arg placeholder (`<project-id>` → `<environment-id>`) | 3 | `os environments bind --help` |
| the `switch` id-not-found error | 1 | `os environments switch` on a bad id |

The five `static override description` strings now read as
`content/docs/deployment/cli.mdx`'s command table has described them since the rename
("List environments visible to the current session", "Provision a new environment", …),
so the shipped `--help` and the shipped docs agree for the first time.

What is deliberately NOT renamed, because it is API surface in other packages rather than
CLI wording, and each needs its own decision: `client.projects.*` (the `@objectstack/client`
SDK method names), the `res.project` / `res.projects` response fields, the locals bound
directly from them, and the docblock comments in these files.
16 changes: 8 additions & 8 deletions packages/cli/src/commands/environments/bind.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -21,17 +21,17 @@ import { formatOutput } from '../../utils/output-formatter.js';
* reflects the latest source.
*/
export default class EnvironmentsBind extends Command {
static override description = 'Bind a local objectstack artifact to an existing project';
static override description = 'Bind a local objectstack artifact to an existing environment';

static override examples = [
'$ os environments bind <project-id> --artifact ./dist/objectstack.json',
'$ os environments bind <project-id> --artifact ./dist/objectstack.json --build',
'$ os environments bind <project-id> --reseed',
'$ os environments bind <environment-id> --artifact ./dist/objectstack.json',
'$ os environments bind <environment-id> --artifact ./dist/objectstack.json --build',
'$ os environments bind <environment-id> --reseed',
];

static override args = {
environmentId: Args.string({
description: 'Target project id (UUID)',
description: 'Target environment id (UUID)',
required: true,
}),
};
Expand DownExpand Up@@ -111,7 +111,7 @@ export default class EnvironmentsBind extends Command {
delete existingMeta.artifactBindError;
existingMeta.artifact_path = artifactAbs;

printKV('Project', args.environmentId, '🎯');
printKV('Environment', args.environmentId, '🎯');
printKV('Artifact', artifactAbs, '📦');

const res = await client.projects.update(args.environmentId, {
Expand DownExpand Up@@ -139,9 +139,9 @@ export default class EnvironmentsBind extends Command {
} else if (flags.format === 'yaml') {
await formatOutput(res, 'yaml');
} else {
console.log(`\n✓ Project bound to artifact`);
console.log(`\n✓ Environment bound to artifact`);
console.log(` ${args.environmentId} → ${artifactAbs}`);
console.log(` The next request to this project will load the new bundle.`);
console.log(` The next request to this environment will load the new bundle.`);
console.log('');
}
} catch (error: any) {
Expand Down
12 changes: 6 additions & 6 deletions packages/cli/src/commands/environments/create.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -15,7 +15,7 @@ import { readAuthConfig, writeAuthConfig } from '../../utils/auth-config.js';
* (unless `--no-activate` is passed).
*/
export default class EnvironmentsCreate extends Command {
static override description = 'Provision a new project';
static override description = 'Provision a new environment';

static override examples = [
'$ os environments create --org 00000000-0000-0000-0000-000000000000 --name Staging',
Expand All@@ -39,11 +39,11 @@ export default class EnvironmentsCreate extends Command {
// the App Marketplace instead (`os package install`, `sys_package` with
// `is_starter = true`).
artifact: Flags.string({
description: 'Path to a locally-compiled objectstack.json artifact to bind into this project',
description: 'Path to a locally-compiled objectstack.json artifact to bind into this environment',
}),
'clone-from': Flags.string({ description: 'Clone schema from an existing project id' }),
'clone-from': Flags.string({ description: 'Clone schema from an existing environment id' }),
activate: Flags.boolean({
description: 'Activate the new project for subsequent CLI calls',
description: 'Activate the new environment for subsequent CLI calls',
default: true,
allowNo: true,
}),
Expand DownExpand Up@@ -111,9 +111,9 @@ export default class EnvironmentsCreate extends Command {
await formatOutput(res, 'yaml');
} else {
const p = res?.project ?? {};
console.log(`\n✓ Project created: ${p.display_name ?? p.id} (${p.id})`);
console.log(`\n✓ Environment created: ${p.display_name ?? p.id} (${p.id})`);
if (flags.activate) {
console.log(` active project set to ${p.id}`);
console.log(` active environment set to ${p.id}`);
}
console.log('');
}
Expand Down
8 changes: 4 additions & 4 deletions packages/cli/src/commands/environments/list.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -13,7 +13,7 @@ import { formatOutput } from '../../utils/output-formatter.js';
* consistent DX.
*/
export default class EnvironmentsList extends Command {
static override description = 'List projects visible to the current session';
static override description = 'List environments visible to the current session';

static override examples = [
'$ os environments list',
Expand All@@ -25,7 +25,7 @@ export default class EnvironmentsList extends Command {
url: Flags.string({ char: 'u', description: 'Server URL', env: 'OS_CLOUD_URL' }),
token: Flags.string({ char: 't', description: 'Authentication token', env: 'OS_TOKEN' }),
org: Flags.string({ description: 'Filter by organization id' }),
status: Flags.string({ description: 'Filter by project status (active|provisioning|failed|…)' }),
status: Flags.string({ description: 'Filter by environment status (active|provisioning|failed|…)' }),
format: Flags.string({
char: 'f',
description: 'Output format',
Expand DownExpand Up@@ -57,9 +57,9 @@ export default class EnvironmentsList extends Command {
} else if (flags.format === 'yaml') {
await formatOutput(res, 'yaml');
} else {
console.log(`\nProjects (${projects.length}):\n`);
console.log(`\nEnvironments (${projects.length}):\n`);
if (projects.length === 0) {
console.log(' (no projects)');
console.log(' (no environments)');
} else {
for (const p of projects) {
const active = p.id === activeId ? ' ★' : '';
Expand Down
6 changes: 3 additions & 3 deletions packages/cli/src/commands/environments/show.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -12,15 +12,15 @@ import { formatOutput } from '../../utils/output-formatter.js';
* membership row (same shape as `client.projects.get(id)`).
*/
export default class EnvironmentsShow extends Command {
static override description = 'Show detailed information for a project';
static override description = 'Show detailed information for an environment';

static override examples = [
'$ os environments show 00000000-0000-0000-0000-000000000001',
'$ os environments show proj-123 --format json',
];

static override args = {
id: Args.string({ description: 'Project id', required: true }),
id: Args.string({ description: 'Environment id', required: true }),
};

static override flags = {
Expand DownExpand Up@@ -49,7 +49,7 @@ export default class EnvironmentsShow extends Command {
await formatOutput(res, 'yaml');
} else {
const p = res?.project ?? {};
console.log(`\nProject: ${p.display_name ?? p.id}`);
console.log(`\nEnvironment: ${p.display_name ?? p.id}`);
console.log('─'.repeat(60));
console.log(` id: ${p.id}`);
console.log(` organization: ${p.organization_id ?? '—'}`);
Expand Down
8 changes: 4 additions & 4 deletions packages/cli/src/commands/environments/switch.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -15,15 +15,15 @@ import { readAuthConfig, writeAuthConfig } from '../../utils/auth-config.js';
* project.
*/
export default class EnvironmentsSwitch extends Command {
static override description = 'Activate a project for subsequent CLI calls';
static override description = 'Activate an environment for subsequent CLI calls';

static override examples = [
'$ os environments switch 00000000-0000-0000-0000-000000000001',
'$ os environments switch proj-123 --no-remote',
];

static override args = {
id: Args.string({ description: 'Project id to activate', required: true }),
id: Args.string({ description: 'Environment id to activate', required: true }),
};

static override flags = {
Expand All@@ -47,7 +47,7 @@ export default class EnvironmentsSwitch extends Command {
const lookup = await client.projects.get(args.id);
const project = lookup?.project;
if (!project?.id) {
throw new Error(`Project ${args.id} not found`);
throw new Error(`Environment ${args.id} not found`);
}

if (flags.remote) {
Expand All@@ -59,7 +59,7 @@ export default class EnvironmentsSwitch extends Command {
cfg.lastUsedAt = new Date().toISOString();
await writeAuthConfig(cfg);

console.log(`\n✓ Active project: ${project.display_name ?? project.id}`);
console.log(`\n✓ Active environment: ${project.display_name ?? project.id}`);
console.log(` id: ${project.id}`);
if (!flags.remote) {
console.log(' (local only — server session unchanged)');
Expand Down
Loading