fix(cli): os environments runs on the os cloud login session through one resolver

createControlPlaneApiClient (utils/api-client.ts) chooses the stored
session for list, show, create, bind and switch: credentials.json's
session where it targets the server (with no --url it names it), else
cloud.json's on the same terms; an explicit url neither file names keeps
credentials.json's session as before and never gets the cloud token.
The active environment comes from the chosen file, and switch / create
--activate no longer write a cloud environment id into credentials.json
when they ran on the cloud session. The refusal with no session names
os cloud login too.

Claude-Session: https://claude.ai/code/session_01VvcEokUG1tvVxkceYfR5XB
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

.changeset/21360-environments-cloud-session.md

@@ -0,0 +1,28 @@
+---
+'@objectstack/cli': patch
+---
+
+`os environments list | show | create | bind | switch` run on the `os cloud login` session
+
+Clause-②: no
+
+The documented hosted flow is `os cloud login`, then `os environments create`. The five
+`os environments` subcommands read only `~/.objectstack/credentials.json` (the `os login`
+session), so with only `~/.objectstack/cloud.json` they exited 1 with
+`Authentication required` before sending any request, while `os login --help` sends hosted
+users to `os cloud login`.
+
+All five now choose their session in one shared resolver:
+
+- With no `--url` / `OS_CLOUD_URL`, they use the `os login` session when there is one, which
+  is the same behaviour as before. Otherwise they use the `os cloud login` session and the URL
+  it recorded.
+- With a `--url`, they use the session whose file names that server, `credentials.json` first.
+  When neither file names it, they use `credentials.json`'s session as before. The cloud token
+  is never sent to a URL other than its own.
+- The active environment sent with each request comes from the chosen session's file.
+  `os environments switch` and `create --activate` no longer write a cloud environment id into
+  `credentials.json` when they ran on the cloud session.
+
+With no session at all, the `Authentication required` message now names `os cloud login` as
+well as `os login`. `os package publish` is unchanged: it still reads only `cloud.json`.

packages/cli/README.md

@@ -96,14 +96,19 @@ Typical flow (build → publish → install into an environment, seeding sample
 
 ```bash
 os compile                                 # → dist/objectstack.json
-os cloud login                             # one-time; the session os package publish reads
-os environments create --org "$ORG" --name "Dev" --activate   # does NOT read that session — see below
+os cloud login                             # one-time; the session os package publish and os environments read
+os environments create --org "$ORG" --name "Dev" --activate
 os package publish --env <env-id> --install --seed-sample-data
 ```
 
-`os environments create` does not use the session `os cloud login` stored: give
-it `--url` and `--token` (or `OS_CLOUD_URL` / `OS_TOKEN`), or an `os login`
-session. Without either it exits 1 with `Authentication required`.
+`os environments` runs on either stored session. With no `--url` it talks to
+the server of the `os login` session (`credentials.json`) when there is one,
+else to the server of the `os cloud login` session (`cloud.json`), with that
+session's token. A `--url` (or `OS_CLOUD_URL`) picks the session that names
+that server, `credentials.json`'s first — so with both stored, a `--url` naming
+the cloud uses the cloud session. A `--url` neither file names gets
+`credentials.json`'s token as before, never `cloud.json`'s. With no session and
+no `--token` / `OS_TOKEN`, it exits 1 with `Authentication required`.
 
 `os package publish` registers a `sys_package` (keyed by a reverse-domain
 `--manifest-id`, derived from the artifact when omitted), snapshots the
@@ -124,7 +129,7 @@ Two stored sessions exist, and each command authenticates with one of them:
 | `os cloud login` | `-u, --url` (env `OS_CLOUD_URL`, default `https://cloud.objectos.ai`) | none — `-e, --email` / `-p, --password`, or the browser device flow | writes `~/.objectstack/cloud.json` |
 | `os cloud whoami` / `os cloud logout` | — | — | reads / deletes `~/.objectstack/cloud.json` |
 | `os package publish`, `os plugin publish` | `-s, --server` (env `OS_CLOUD_URL`); else the URL in `cloud.json`; else `https://cloud.objectos.ai` | `-t, --token` (env `OS_CLOUD_API_KEY`, then `OS_TOKEN`) | `~/.objectstack/cloud.json` — the `os cloud login` session |
-| `os environments list` / `show` / `create` / `bind` / `switch` | `-u, --url` (env `OS_CLOUD_URL`); else the URL in `credentials.json`; else `http://localhost:3000` | `-t, --token` (env `OS_TOKEN`) | `~/.objectstack/credentials.json` — the `os login` session, **not** `os cloud login`'s |
+| `os environments list` / `show` / `create` / `bind` / `switch` | `-u, --url` (env `OS_CLOUD_URL`); else the URL of the stored session it uses; else `http://localhost:3000` | `-t, --token` (env `OS_TOKEN`) | No `--url`: `~/.objectstack/credentials.json` (the `os login` session), else `~/.objectstack/cloud.json` (the `os cloud login` session). With `--url`: the file that names that server, `credentials.json` first; when neither does, `credentials.json` as before. `cloud.json`'s token is never sent to another URL |
 
 `os package install` is not a cloud command: it installs into a running runtime
 (`-r, --runtime`, env `OS_RUNTIME_URL`, default `http://localhost:3000`) and signs

packages/cli/src/commands/environments/bind.ts

@@ -5,7 +5,7 @@ import path from 'node:path';
 import fs from 'node:fs/promises';
 import { spawnSync } from 'node:child_process';
 import { printError, printStep, printKV, emitJson, isExitSignal, errorCodeFields } from '../../utils/format.js';
-import { createApiClient, requireAuth } from '../../utils/api-client.js';
+import { createControlPlaneApiClient, requireControlPlaneAuth } from '../../utils/api-client.js';
 import { formatOutput } from '../../utils/output-formatter.js';
 
 /**
@@ -99,8 +99,8 @@ export default class EnvironmentsBind extends Command {
         this.exit(1);
       }
 
-      const { client, token } = await createApiClient({ url: flags.url, token: flags.token });
-      requireAuth(token);
+      const { client, token } = await createControlPlaneApiClient({ url: flags.url, token: flags.token });
+      requireControlPlaneAuth(token);
 
       // Fetch existing metadata so we don't blow it away.
       const current = await client.environments.get(args.environmentId);

packages/cli/src/commands/environments/create-clone-from.test.ts

@@ -52,7 +52,7 @@ vi.mock('../../utils/api-client.js', async (importOriginal) => {
   const actual = await importOriginal<typeof import('../../utils/api-client.js')>();
   return {
     ...actual,
-    createApiClient: async () => ({ client: stub.client, token: stub.token, baseUrl: 'https://door.test' }),
+    createControlPlaneApiClient: async () => ({ client: stub.client, token: stub.token, baseUrl: 'https://door.test' }),
   };
 });
 

packages/cli/src/commands/environments/create.ts

@@ -2,7 +2,7 @@
 
 import { Command, Flags } from '@oclif/core';
 import { printError, emitJson, isExitSignal, errorCodeFields } from '../../utils/format.js';
-import { createApiClient, requireAuth } from '../../utils/api-client.js';
+import { createControlPlaneApiClient, requireControlPlaneAuth } from '../../utils/api-client.js';
 import { formatOutput } from '../../utils/output-formatter.js';
 import { readAuthConfig, writeAuthConfig } from '../../utils/auth-config.js';
 import { recordCloudActiveEnvironmentId } from '../../utils/active-environment.js';
@@ -18,12 +18,18 @@ import { recordCloudActiveEnvironmentId } from '../../utils/active-environment.j
  * lives in a repo this one never compiles against, so a class name here rots
  * with nothing to catch it.
  *
+ * Authenticates through `createControlPlaneApiClient` — `credentials.json`'s
+ * session where it targets the server, else `cloud.json`'s (the order is
+ * written once, there).
+ *
  * On success, optionally activates the new environment for the current session
  * and persists `activeEnvironmentId` into `~/.objectstack/credentials.json`
- * (unless `--no-activate` is passed). When the control plane it just talked
- * to IS the one `~/.objectstack/cloud.json` records, the same id is written
- * there as well, so `os package publish --install` can install into the
- * environment you just created without repeating the uuid.
+ * (unless `--no-activate` is passed, or the create ran on `cloud.json`'s
+ * session, whose server is not the one `credentials.json` names). When the
+ * control plane it just talked to IS the one `~/.objectstack/cloud.json`
+ * records, the same id is written there as well, so `os package publish
+ * --install` can install into the environment you just created without
+ * repeating the uuid.
  *
  * `os environments switch` records it through the SAME helper. An environment
  * id is only meaningful against the server that issued it, and that gate is
@@ -79,8 +85,8 @@ export default class EnvironmentsCreate extends Command {
     const { flags } = await this.parse(EnvironmentsCreate);
 
     try {
-      const { client, token, baseUrl } = await createApiClient({ url: flags.url, token: flags.token });
-      requireAuth(token);
+      const { client, token, baseUrl, session } = await createControlPlaneApiClient({ url: flags.url, token: flags.token });
+      requireControlPlaneAuth(token);
 
       // Resolve the artifact to an absolute path so the server can read it
       // regardless of its CWD. Bail early if the file is missing — better
@@ -123,7 +129,9 @@ export default class EnvironmentsCreate extends Command {
           // a second copy of it.
           recordedForCloud = await recordCloudActiveEnvironmentId(res.environment.id, baseUrl);
 
-          const cfg = await readAuthConfig().catch(() => null);
+          // Runtime store — skipped on `cloud.json`'s session, for the reason
+          // `os environments switch` gives: that server is not credentials.json's.
+          const cfg = session === 'cloud' ? null : await readAuthConfig().catch(() => null);
           if (cfg) {
             cfg.activeEnvironmentId = res.environment.id;
             cfg.lastUsedAt = new Date().toISOString();

packages/cli/src/commands/environments/list.ts

@@ -2,7 +2,7 @@
 
 import { Command, Flags } from '@oclif/core';
 import { printError, emitJson, errorCodeFields } from '../../utils/format.js';
-import { createApiClient, requireAuth } from '../../utils/api-client.js';
+import { createControlPlaneApiClient, requireControlPlaneAuth } from '../../utils/api-client.js';
 import { formatOutput } from '../../utils/output-formatter.js';
 
 /**
@@ -38,12 +38,12 @@ export default class EnvironmentsList extends Command {
     const { flags } = await this.parse(EnvironmentsList);
 
     try {
-      const { client, token, environmentId: activeId } = await createApiClient({
+      const { client, token, environmentId: activeId } = await createControlPlaneApiClient({
         url: flags.url,
         token: flags.token,
       });
 
-      requireAuth(token);
+      requireControlPlaneAuth(token);
 
       const res = await client.environments.list({
         organization_id: flags.org,

packages/cli/src/commands/environments/show.ts

@@ -2,7 +2,7 @@
 
 import { Args, Command, Flags } from '@oclif/core';
 import { printError, emitJson, errorCodeFields } from '../../utils/format.js';
-import { createApiClient, requireAuth } from '../../utils/api-client.js';
+import { createControlPlaneApiClient, requireControlPlaneAuth } from '../../utils/api-client.js';
 import { formatOutput } from '../../utils/output-formatter.js';
 
 /**
@@ -38,8 +38,8 @@ export default class EnvironmentsShow extends Command {
     const { args, flags } = await this.parse(EnvironmentsShow);
 
     try {
-      const { client, token } = await createApiClient({ url: flags.url, token: flags.token });
-      requireAuth(token);
+      const { client, token } = await createControlPlaneApiClient({ url: flags.url, token: flags.token });
+      requireControlPlaneAuth(token);
 
       const res = await client.environments.get(args.id);
 

packages/cli/src/commands/environments/switch.ts

@@ -2,18 +2,21 @@
 
 import { Args, Command, Flags } from '@oclif/core';
 import { printError } from '../../utils/format.js';
-import { createApiClient, requireAuth } from '../../utils/api-client.js';
+import { createControlPlaneApiClient, requireControlPlaneAuth } from '../../utils/api-client.js';
 import { readAuthConfig, writeAuthConfig } from '../../utils/auth-config.js';
 import { recordCloudActiveEnvironmentId } from '../../utils/active-environment.js';
 
 /**
  * `os environments switch <id>` — set the active environment for this CLI session.
  *
- * Calls `POST /api/v1/cloud/environments/:id/activate` to update the
- * server-side session, then persists `activeEnvironmentId` into
+ * Authenticates through `createControlPlaneApiClient` — `credentials.json`'s
+ * session where it targets the server, else `cloud.json`'s (the order is
+ * written once, there). Calls `POST /api/v1/cloud/environments/:id/activate`
+ * to update the server-side session, then persists `activeEnvironmentId` into
  * `~/.objectstack/credentials.json` so subsequent CLI commands (and any
  * client they create via `createApiClient`) automatically target this
- * environment.
+ * environment — unless the switch ran on `cloud.json`'s session, whose server
+ * is not the one `credentials.json` names.
  *
  * When the control plane it just talked to IS the one `~/.objectstack/cloud.json`
  * records, the same id is written there as well, so `os package publish --install`
@@ -48,8 +51,8 @@ export default class EnvironmentsSwitch extends Command {
     const { args, flags } = await this.parse(EnvironmentsSwitch);
 
     try {
-      const { client, token, baseUrl } = await createApiClient({ url: flags.url, token: flags.token });
-      requireAuth(token);
+      const { client, token, baseUrl, session } = await createControlPlaneApiClient({ url: flags.url, token: flags.token });
+      requireControlPlaneAuth(token);
 
       // Sanity-check the id resolves — fail fast before writing the cred file
       const lookup = await client.environments.get(args.id);
@@ -68,10 +71,12 @@ export default class EnvironmentsSwitch extends Command {
       // `credentials.json` at all).
       const recordedForCloud = await recordCloudActiveEnvironmentId(environment.id, baseUrl);
 
-      // Runtime store: unchanged behaviour. This is the copy `createApiClient`
-      // reads, so the `data` / `meta` / `environments` families keep targeting
-      // the environment you just switched to.
-      const cfg = await readAuthConfig().catch(() => null);
+      // Runtime store: the copy `createApiClient` reads, so the `data` / `meta`
+      // families keep targeting the environment you just switched to. Skipped
+      // when this switch ran on `cloud.json`'s session: the server it talked to
+      // is cloud.json's, and the environment would not resolve on the server
+      // `credentials.json` names.
+      const cfg = session === 'cloud' ? null : await readAuthConfig().catch(() => null);
       if (cfg) {
         cfg.activeEnvironmentId = environment.id;
         cfg.lastUsedAt = new Date().toISOString();