@nurix/apollo 0.4.0 → 0.4.2

package/README.md

@@ -1,19 +1,12 @@
 # `@nurix/apollo` — the `apollo` CLI
 
-The consumer-side installer for the Apollo discovery plane. It implements the
-build-time integration flow of the
-[consumer journey](../../docs/discovery/consumer-journey.md): exchange your
-application key for service-scoped credentials, write them into a managed
-`.env` block, install the service's npm package, and record the `consumes`
-edge in your `apollo.service.json` (the application's bill of materials).
+The consumer-side installer for the Apollo discovery plane. It implements the build-time integration flow of the [consumer journey](../../docs/discovery/consumer-journey.md): exchange your application key for service-scoped credentials, write them into a managed `.env` block, install the service's npm package, and record the `consumes` edge in your `apollo.service.json` (the application's bill of materials).
 
 Interactive UX is built on [`@clack/prompts`](https://github.com/bombshell-dev/clack).
 
 ## Install
 
-Published to npm with **restricted access** under the `@nurix` scope — you need
-an npm account with read rights to the `nurix` org (`npm login`, then verify
-with `npm whoami`).
+Published to npm with **restricted access** under the `@nurix` scope — you need an npm account with read rights to the `nurix` org (`npm login`, then verify with `npm whoami`).
 
 ```
 npx @nurix/apollo@latest --help      # one-shot
@@ -53,37 +46,27 @@ apollo doctor                # key validity + per-credential health probes +
 apollo open <svc> [--env <name>] # open endpoint (default production) or repo URL
 ```
 
-The Apollo base URL is hardcoded to the hosted instance
-(`https://apollo.nurix-ai.co`) — there is no flag or env override.
+Global options: `--apollo-url <url>` (defaults to `$APOLLO_URL`, then the hosted instance `https://apollo.nurix-ai.co`) — the default means you never need to pass the URL; override only for a non-hosted Apollo.
 
 ### `apollo init`
 
-1. Prompts for your `APOLLO_APP_KEY` (created with your application in the
-   Apollo console) and **validates it against Apollo — no key, no install**.
-2. Writes it into the **Apollo-managed block** of `.env` (+ a placeholder in
-   `.env.example`) and makes sure `.env` is gitignored.
+1. Prompts for your `APOLLO_APP_KEY` (created with your application in the Apollo console) and **validates it against Apollo — no key, no install**.
+2. Writes it into the **Apollo-managed block** of `.env` (+ a placeholder in `.env.example`) and makes sure `.env` is gitignored.
 3. Offers to scaffold `apollo.service.json` if the repo has none.
 
 ### `apollo add <service>` — the installer
 
-1. Reads `APOLLO_APP_KEY` from the managed block (or the environment); fails
-   loudly with remediation if missing.
-2. Fetches the catalogue and resolves the service (interactive select when no
-   name is passed).
-3. `POST /api/v1/keys/exchange` → `{ endpoint, serviceKey }` — idempotent per
-   (application × service), so re-running is safe.
-4. Writes `<SERVICE>_ENDPOINT` + `<SERVICE>_KEY` into the managed `.env`
-   block, placeholders into `.env.example`.
-5. Installs the service's npm package when it ships one (package manager
-   detected from the repo's lockfile).
-6. Appends the `consumes` edge to `apollo.service.json` (offers a scaffold if
-   the manifest is missing).
+1. Reads `APOLLO_APP_KEY` from the managed block (or the environment); fails loudly with remediation if missing.
+2. Fetches the catalogue and resolves the service (interactive select when no name is passed).
+3. `POST /api/v1/keys/exchange` → `{ endpoint, serviceKey }` — idempotent per (application × service), so re-running is safe.
+4. Writes `<SERVICE>_ENDPOINT` + `<SERVICE>_KEY` into the managed `.env` block, placeholders into `.env.example`.
+5. Installs the service's npm package when it ships one (package manager detected from the repo's lockfile).
+6. Appends the `consumes` edge to `apollo.service.json` (offers a scaffold if the manifest is missing).
 7. Best-effort health probe against the issued endpoint (never blocks).
 
 ### The managed `.env` block
 
-The CLI owns **only** the delimited block — everything outside it is yours and
-is never touched:
+The CLI owns **only** the delimited block — everything outside it is yours and is never touched:
 
 ```
 MY_OWN_SECRET=untouched
@@ -95,8 +78,7 @@ EMAIL_KEY=apollo_svc_…
 # <<< apollo:managed <<<
 ```
 
-Inside the block the server is the source of truth (manual edits get
-overwritten); outside it, nothing is ever rewritten.
+Inside the block the server is the source of truth (manual edits get overwritten); outside it, nothing is ever rewritten.
 
 ## Development
 
@@ -106,20 +88,10 @@ pnpm --filter @nurix/apollo typecheck
 node packages/cli/dist/index.js --help         # run from the repo root
 ```
 
-ESM, Node ≥ 22, strict TypeScript. `bin` is `dist/index.js` (`apollo`).
-Releases ship via `.github/workflows/publish-cli-to-npm.yml` — merges to `dev`
-touching `packages/cli/**` auto-publish a patch; dispatch the workflow for
-minor/major.
+ESM, Node ≥ 22, strict TypeScript. `bin` is `dist/index.js` (`apollo`). Releases ship via `.github/workflows/publish-cli-to-npm.yml` — merges to `dev` touching `packages/cli/**` auto-publish a patch; dispatch the workflow for minor/major.
 
 ## Current limitations
 
-- The hosted catalogue is empty until the registry read path lands
-  (consumer-journey.md R3) — `list`/`describe`/`graph`/`open` degrade with a
-  clear message; `apollo add <name>` still works for services seeded into the
-  KV catalogue, since the exchange resolves endpoints server-side.
-- `apollo sync` needs `GET /api/v1/keys/credentials` (journey R7) — the route
-  is in the worker code; it goes live with the next worker deploy.
-- Exchange still returns `{endpoint, serviceKey}` together; once it slims to
-  credential-only with Apollo-served definitions (journey §9.2–§9.3), the
-  client picks the endpoint up from the definition instead
-  (`src/lib/apollo_client.ts` is the seam).
+- The hosted catalogue is empty until the registry read path lands (consumer-journey.md R3) — `list`/`describe`/`graph`/`open` degrade with a clear message; `apollo add <name>` still works for services seeded into the KV catalogue, since the exchange resolves endpoints server-side.
+- `apollo sync` needs `GET /api/v1/keys/credentials` (journey R7) — the route is in the worker code; it goes live with the next worker deploy.
+- Exchange still returns `{endpoint, serviceKey}` together; once it slims to credential-only with Apollo-served definitions (journey §9.2–§9.3), the client picks the endpoint up from the definition instead (`src/lib/apollo_client.ts` is the seam).

package/dist/commands/add.js

@@ -4,14 +4,15 @@
 // records the consumes edge (consumer-journey.md §4–§5).
 import path from "node:path";
 import * as p from "@clack/prompts";
-import { APOLLO_URL, exchangeServiceCredential, fetchCatalogue, } from "../lib/apollo_client.js";
+import { exchangeServiceCredential, fetchCatalogue, resolveApolloUrl, } from "../lib/apollo_client.js";
 import { readManagedValues, upsertManagedValues } from "../lib/env_file.js";
 import { detectPackageManager, installPackage } from "../lib/package_manager.js";
 import { appendConsumesEdge, hasManifest, scaffoldManifest } from "../lib/manifest.js";
 import { confirmOrFallback, isInteractive } from "../lib/interactive.js";
 // Run the installer flow end to end for one service.
-export async function runAdd(serviceArg) {
+export async function runAdd(serviceArg, options) {
     const cwd = process.cwd();
+    const baseUrl = resolveApolloUrl(options);
     p.intro(`apollo add${serviceArg ? ` ${serviceArg}` : ""}`);
     const managedValues = await readManagedValues(path.join(cwd, ".env"));
     const appKey = managedValues.APOLLO_APP_KEY ?? process.env.APOLLO_APP_KEY;
@@ -23,7 +24,7 @@ export async function runAdd(serviceArg) {
     }
     const spinner = p.spinner();
     spinner.start("Fetching the catalogue");
-    const catalogue = await fetchCatalogue(APOLLO_URL).catch(() => null);
+    const catalogue = await fetchCatalogue(baseUrl).catch(() => null);
     const services = catalogue?.services ?? [];
     spinner.stop(`Catalogue loaded: ${services.length} service(s)`);
     const serviceName = serviceArg ?? (await pickService(services));
@@ -39,7 +40,7 @@ export async function runAdd(serviceArg) {
     spinner.start(`Exchanging credentials for '${serviceName}'`);
     let credential;
     try {
-        credential = await exchangeServiceCredential(APOLLO_URL, appKey, serviceName);
+        credential = await exchangeServiceCredential(baseUrl, appKey, serviceName);
     }
     catch (error) {
         spinner.stop("Exchange failed", 1);

package/dist/commands/bootstrap.js

@@ -3,14 +3,15 @@
 // rejected, runs the login flow, then finishes with init's manifest scaffold.
 import path from "node:path";
 import * as p from "@clack/prompts";
-import { APOLLO_URL, validateAppKey } from "../lib/apollo_client.js";
+import { resolveApolloUrl, validateAppKey } from "../lib/apollo_client.js";
 import { readManagedValues } from "../lib/env_file.js";
 import { isInteractive } from "../lib/interactive.js";
 import { performDeviceLogin } from "./login.js";
 import { finishInit } from "./init.js";
 // Run the bootstrap flow: ensure a valid app key (login when needed), then init.
-export async function runBootstrap() {
+export async function runBootstrap(options) {
     const cwd = process.cwd();
+    const baseUrl = resolveApolloUrl(options);
     p.intro("apollo");
     if (!isInteractive()) {
         p.log.error("Bare `apollo` needs an interactive terminal (browser sign-in + prompts).");
@@ -23,7 +24,7 @@ export async function runBootstrap() {
     if (managedValues.APOLLO_APP_KEY) {
         const spinner = p.spinner();
         spinner.start("Checking the stored APOLLO_APP_KEY against Apollo");
-        isSignedIn = await validateAppKey(APOLLO_URL, managedValues.APOLLO_APP_KEY).catch(() => false);
+        isSignedIn = await validateAppKey(baseUrl, managedValues.APOLLO_APP_KEY).catch(() => false);
         spinner.stop(isSignedIn
             ? "Signed in — the stored key is valid"
             : "Stored key rejected — signing in again", isSignedIn ? 0 : 1);
@@ -31,7 +32,7 @@ export async function runBootstrap() {
     else {
         p.log.info("No APOLLO_APP_KEY in the managed .env block — signing in");
     }
-    if (!isSignedIn && !(await performDeviceLogin(cwd))) {
+    if (!isSignedIn && !(await performDeviceLogin(baseUrl, cwd))) {
         p.outro("Sign-in failed — nothing was written. Run `apollo` again, or `apollo login` to retry.");
         process.exitCode = 1;
         return;

package/dist/commands/describe.js

@@ -1,13 +1,14 @@
 // packages/cli/src/commands/describe.ts - `apollo describe <service>`: the full
 // catalogue entry for one service, prettified or raw JSON.
 import * as p from "@clack/prompts";
-import { APOLLO_URL, fetchCatalogue } from "../lib/apollo_client.js";
+import { fetchCatalogue, resolveApolloUrl } from "../lib/apollo_client.js";
 // Print one catalogue entry; --json emits the raw object for piping.
-export async function runDescribe(serviceName, options) {
-    const catalogue = await fetchCatalogue(APOLLO_URL);
+export async function runDescribe(serviceName, options, globals) {
+    const baseUrl = resolveApolloUrl(globals);
+    const catalogue = await fetchCatalogue(baseUrl);
     const entry = (catalogue.services ?? []).find((service) => service.name === serviceName);
     if (!entry) {
-        p.log.error(`'${serviceName}' is not in the catalogue at ${APOLLO_URL} (${catalogue.services?.length ?? 0} services listed).`);
+        p.log.error(`'${serviceName}' is not in the catalogue at ${baseUrl} (${catalogue.services?.length ?? 0} services listed).`);
         process.exitCode = 1;
         return;
     }

package/dist/commands/doctor.js

@@ -5,19 +5,20 @@
 import path from "node:path";
 import { readFile } from "node:fs/promises";
 import * as p from "@clack/prompts";
-import { APOLLO_URL, fetchCatalogue, validateAppKey } from "../lib/apollo_client.js";
+import { fetchCatalogue, resolveApolloUrl, validateAppKey, } from "../lib/apollo_client.js";
 import { readManagedValues } from "../lib/env_file.js";
 import { hasManifest, manifestPath } from "../lib/manifest.js";
 import { loadSchema, validateManifest } from "../lib/schema_validator.js";
 // Run every check; exit 1 when any error (not warning) was found.
-export async function runDoctor() {
+export async function runDoctor(globals) {
     const cwd = process.cwd();
+    const baseUrl = resolveApolloUrl(globals);
     p.intro("apollo doctor");
     const counters = { errors: 0, warnings: 0 };
     const managedValues = await readManagedValues(path.join(cwd, ".env"));
-    await checkAppKey(managedValues, counters);
+    await checkAppKey(managedValues, baseUrl, counters);
     await checkServiceCredentials(managedValues, counters);
-    await checkManifest(cwd, counters);
+    await checkManifest(cwd, baseUrl, counters);
     const summary = `${counters.errors} error(s), ${counters.warnings} warning(s)`;
     if (counters.errors > 0) {
         p.outro(`Unhealthy — ${summary}.`);
@@ -28,14 +29,14 @@ export async function runDoctor() {
     }
 }
 // Check the APOLLO_APP_KEY exists and is still accepted by Apollo.
-async function checkAppKey(managedValues, counters) {
+async function checkAppKey(managedValues, baseUrl, counters) {
     const appKey = managedValues.APOLLO_APP_KEY ?? process.env.APOLLO_APP_KEY;
     if (!appKey) {
         p.log.error("APOLLO_APP_KEY missing — run `apollo init`.");
         counters.errors += 1;
         return;
     }
-    const isValid = await validateAppKey(APOLLO_URL, appKey).catch(() => false);
+    const isValid = await validateAppKey(baseUrl, appKey).catch(() => false);
     if (isValid) {
         p.log.success("APOLLO_APP_KEY accepted by Apollo");
     }
@@ -80,7 +81,7 @@ async function checkServiceCredentials(managedValues, counters) {
     }
 }
 // Validate the manifest and cross-check its consumes edges against the catalogue.
-async function checkManifest(cwd, counters) {
+async function checkManifest(cwd, baseUrl, counters) {
     if (!hasManifest(cwd)) {
         p.log.warn("No apollo.service.json — the app has no bill of materials. `apollo init` scaffolds one.");
         counters.warnings += 1;
@@ -109,7 +110,7 @@ async function checkManifest(cwd, counters) {
     const edges = (manifest.services ?? []).flatMap((service) => service.consumes ?? []);
     if (edges.length === 0)
         return;
-    const catalogue = await fetchCatalogue(APOLLO_URL).catch(() => null);
+    const catalogue = await fetchCatalogue(baseUrl).catch(() => null);
     const services = catalogue?.services ?? [];
     if (services.length === 0) {
         p.log.info("Catalogue empty — consumes edges not cross-checked.");

package/dist/commands/graph.js

@@ -1,9 +1,10 @@
 // packages/cli/src/commands/graph.ts - `apollo graph`: render the catalogue's
 // consumes-graph as an ascii edge list or a mermaid block.
-import { APOLLO_URL, fetchCatalogue } from "../lib/apollo_client.js";
+import { fetchCatalogue, resolveApolloUrl } from "../lib/apollo_client.js";
 // Print every consumes edge in the catalogue; --mermaid emits `graph LR`.
-export async function runGraph(options) {
-    const catalogue = await fetchCatalogue(APOLLO_URL);
+export async function runGraph(options, globals) {
+    const baseUrl = resolveApolloUrl(globals);
+    const catalogue = await fetchCatalogue(baseUrl);
     const services = catalogue.services ?? [];
     const edges = services.flatMap((service) => (service.consumes ?? []).map((edge) => ({
         from: service.name,
@@ -11,7 +12,7 @@ export async function runGraph(options) {
         via: edge.via ?? "http",
     })));
     if (services.length === 0) {
-        console.log(`Catalogue at ${APOLLO_URL} is empty — nothing to graph.`);
+        console.log(`Catalogue at ${baseUrl} is empty — nothing to graph.`);
         return;
     }
     if (edges.length === 0) {

package/dist/commands/init.js

@@ -3,14 +3,15 @@
 // gitignore .env, and scaffold the repo manifest.
 import path from "node:path";
 import * as p from "@clack/prompts";
-import { APOLLO_URL, validateAppKey } from "../lib/apollo_client.js";
+import { resolveApolloUrl, validateAppKey } from "../lib/apollo_client.js";
 import { ensureEnvGitignored, readManagedValues, upsertManagedValues } from "../lib/env_file.js";
 import { hasManifest, scaffoldManifest } from "../lib/manifest.js";
 import { isInteractive } from "../lib/interactive.js";
 import { performDeviceLogin } from "./login.js";
 // Run the init flow: collect + validate the key, write managed blocks, scaffold.
-export async function runInit() {
+export async function runInit(options) {
     const cwd = process.cwd();
+    const baseUrl = resolveApolloUrl(options);
     p.intro("apollo init");
     if (!isInteractive()) {
         p.log.error("apollo init needs an interactive terminal (it prompts for the key).");
@@ -32,7 +33,7 @@ export async function runInit() {
         message: "Sign in via the browser to create your application & key? (No = paste a key)",
     });
     if (!p.isCancel(viaBrowser) && viaBrowser) {
-        if (!(await performDeviceLogin(cwd))) {
+        if (!(await performDeviceLogin(baseUrl, cwd))) {
             p.outro("Sign-in failed — re-run `apollo init`, or pick the paste option.");
             process.exitCode = 1;
             return;
@@ -41,7 +42,7 @@ export async function runInit() {
         return;
     }
     const appKey = await p.password({
-        message: `Paste your APOLLO_APP_KEY (create an application in the Apollo console: ${APOLLO_URL})`,
+        message: `Paste your APOLLO_APP_KEY (create an application in the Apollo console: ${baseUrl})`,
         validate: (value) => value?.startsWith("apollo_app_") ? undefined : "Expected a key starting with apollo_app_",
     });
     if (p.isCancel(appKey)) {
@@ -50,7 +51,7 @@ export async function runInit() {
     }
     const spinner = p.spinner();
     spinner.start("Validating the key against Apollo");
-    const isValid = await validateAppKey(APOLLO_URL, appKey).catch(() => false);
+    const isValid = await validateAppKey(baseUrl, appKey).catch(() => false);
     if (!isValid) {
         spinner.stop("Key rejected by Apollo", 1);
         p.outro("No key, no install — fix the key and re-run `apollo init`.");

package/dist/commands/list.js

@@ -1,12 +1,13 @@
 // packages/cli/src/commands/list.ts - `apollo list`: print the discovery
 // catalogue, one line per service.
-import { APOLLO_URL, fetchCatalogue } from "../lib/apollo_client.js";
+import { fetchCatalogue, resolveApolloUrl } from "../lib/apollo_client.js";
 // Print the catalogue as aligned columns: name, classifier, status, description.
-export async function runList() {
-    const catalogue = await fetchCatalogue(APOLLO_URL);
+export async function runList(options) {
+    const baseUrl = resolveApolloUrl(options);
+    const catalogue = await fetchCatalogue(baseUrl);
     const services = catalogue.services ?? [];
     if (services.length === 0) {
-        console.log(`Catalogue at ${APOLLO_URL} is empty — the registry read path / refresh isn't wired yet.`);
+        console.log(`Catalogue at ${baseUrl} is empty — the registry read path / refresh isn't wired yet.`);
         return;
     }
     for (const service of services) {

package/dist/commands/login.js

@@ -5,7 +5,7 @@
 // the managed .env block — no key pasting.
 import path from "node:path";
 import * as p from "@clack/prompts";
-import { APOLLO_URL } from "../lib/apollo_client.js";
+import { resolveApolloUrl } from "../lib/apollo_client.js";
 import { ensureEnvGitignored, readManagedValues, upsertManagedValues } from "../lib/env_file.js";
 import { launchBrowser } from "../lib/browser_opener.js";
 import { getOrCreateDeviceId } from "../lib/device_identity.js";
@@ -13,9 +13,9 @@ import { pollDeviceOnce, pollUntilIssued, startDeviceTrust, } from "../lib/devic
 // Browser-approval wait cap; the trust window itself is 24h server-side.
 const APPROVAL_TIMEOUT_SECONDS = 10 * 60;
 // Run the login flow and write the issued key; returns false on failure.
-export async function performDeviceLogin(cwd, flags = {}) {
+export async function performDeviceLogin(baseUrl, cwd, flags = {}) {
     const deviceId = await getOrCreateDeviceId();
-    const start = await startDeviceTrust(APOLLO_URL, deviceId);
+    const start = await startDeviceTrust(baseUrl, deviceId);
     const managedValues = await readManagedValues(path.join(cwd, ".env"));
     const pollParams = {
         deviceCode: start.device_code,
@@ -26,7 +26,7 @@ export async function performDeviceLogin(cwd, flags = {}) {
     // Trusted-device fast path: an approval inside the 24h window is not
     // consumed, so a single poll may already succeed with no browser at all.
     let issued = null;
-    const firstAttempt = await pollDeviceOnce(APOLLO_URL, pollParams);
+    const firstAttempt = await pollDeviceOnce(baseUrl, pollParams);
     if (firstAttempt.kind === "issued") {
         issued = firstAttempt.issued;
         p.log.success("Device already trusted — no browser approval needed");
@@ -43,7 +43,7 @@ export async function performDeviceLogin(cwd, flags = {}) {
         const spinner = p.spinner();
         spinner.start("Waiting for approval in the browser");
         try {
-            issued = await pollUntilIssued(APOLLO_URL, pollParams, start.interval, Math.min(start.expires_in, APPROVAL_TIMEOUT_SECONDS));
+            issued = await pollUntilIssued(baseUrl, pollParams, start.interval, Math.min(start.expires_in, APPROVAL_TIMEOUT_SECONDS));
         }
         catch (error) {
             spinner.stop("Sign-in failed", 1);
@@ -68,10 +68,11 @@ export async function performDeviceLogin(cwd, flags = {}) {
     return true;
 }
 // `apollo login` — the standalone command wrapper.
-export async function runLogin(flags = {}) {
+export async function runLogin(options, flags = {}) {
     const cwd = process.cwd();
+    const baseUrl = resolveApolloUrl(options);
     p.intro("apollo login");
-    const didLogin = await performDeviceLogin(cwd, flags);
+    const didLogin = await performDeviceLogin(baseUrl, cwd, flags);
     if (!didLogin) {
         p.outro("Nothing was written.");
         process.exitCode = 1;

package/dist/commands/open.js

@@ -1,14 +1,15 @@
 // packages/cli/src/commands/open.ts - `apollo open <service>`: open the
 // service's endpoint (or repository) in the default browser.
 import * as p from "@clack/prompts";
-import { APOLLO_URL, fetchCatalogue } from "../lib/apollo_client.js";
+import { fetchCatalogue, resolveApolloUrl } from "../lib/apollo_client.js";
 import { launchBrowser } from "../lib/browser_opener.js";
 // Resolve the URL to open (chosen endpoint > production > any > repository) and launch it.
-export async function runOpen(serviceName, options) {
-    const catalogue = await fetchCatalogue(APOLLO_URL);
+export async function runOpen(serviceName, options, globals) {
+    const baseUrl = resolveApolloUrl(globals);
+    const catalogue = await fetchCatalogue(baseUrl);
     const entry = (catalogue.services ?? []).find((service) => service.name === serviceName);
     if (!entry) {
-        p.log.error(`'${serviceName}' is not in the catalogue at ${APOLLO_URL}.`);
+        p.log.error(`'${serviceName}' is not in the catalogue at ${baseUrl}.`);
         process.exitCode = 1;
         return;
     }

package/dist/commands/sync.js

@@ -4,11 +4,12 @@
 // credentials disappear).
 import path from "node:path";
 import * as p from "@clack/prompts";
-import { APOLLO_URL, fetchAppCredentials } from "../lib/apollo_client.js";
+import { fetchAppCredentials, resolveApolloUrl } from "../lib/apollo_client.js";
 import { readManagedValues, upsertManagedValues, writeManagedValues } from "../lib/env_file.js";
 // Run the sync flow: fetch the projection, rewrite the managed block wholly.
-export async function runSync() {
+export async function runSync(options) {
     const cwd = process.cwd();
+    const baseUrl = resolveApolloUrl(options);
     p.intro("apollo sync");
     const managedValues = await readManagedValues(path.join(cwd, ".env"));
     const appKey = managedValues.APOLLO_APP_KEY ?? process.env.APOLLO_APP_KEY;
@@ -22,7 +23,7 @@ export async function runSync() {
     spinner.start("Fetching the application's credential projection");
     let projection;
     try {
-        projection = await fetchAppCredentials(APOLLO_URL, appKey);
+        projection = await fetchAppCredentials(baseUrl, appKey);
     }
     catch (error) {
         spinner.stop("Projection failed", 1);

package/dist/index.js

@@ -21,14 +21,15 @@ program
     .name("apollo")
     .description("Bootstrap NuStack services into your repo via the Apollo discovery plane.")
     .version(version)
+    .option("--apollo-url <url>", "Apollo base URL (defaults to $APOLLO_URL, then the hosted instance)")
     // Bare `apollo`: bootstrap — check sign-in, login if needed, then init.
-    .action(async () => runBootstrap());
+    .action(async () => runBootstrap(program.opts()));
 program.addHelpText("after", "\nRun `apollo` with no command to bootstrap: it checks your sign-in, runs login if needed, then init.");
 program
     .command("login")
     .description("Sign in via the browser (24h device trust) and issue your APOLLO_APP_KEY")
     .option("--no-open", "don't auto-open the browser; just print the approval URL")
-    .action(async (options) => runLogin(options));
+    .action(async (options) => runLogin(program.opts(), options));
 program
     .command("logout")
     .description("Sign out: remove APOLLO_APP_KEY from the managed .env block and sever device trust")
@@ -36,24 +37,24 @@ program
 program
     .command("init")
     .description("Store your APOLLO_APP_KEY in the managed .env block and scaffold the manifest")
-    .action(async () => runInit());
+    .action(async () => runInit(program.opts()));
 program
     .command("add [service]")
     .description("Install a stack service: exchange credentials, write .env, install the package")
-    .action(async (service) => runAdd(service));
+    .action(async (service) => runAdd(service, program.opts()));
 program
     .command("list")
     .description("List the services in the Apollo catalogue")
-    .action(async () => runList());
+    .action(async () => runList(program.opts()));
 program
     .command("sync")
     .description("Re-project all credentials issued to this application into the managed .env block")
-    .action(async () => runSync());
+    .action(async () => runSync(program.opts()));
 program
     .command("describe <service>")
     .description("Show the full catalogue entry for a service")
     .option("--json", "emit the raw catalogue entry as JSON")
-    .action(async (service, options) => runDescribe(service, options));
+    .action(async (service, options) => runDescribe(service, options, program.opts()));
 program
     .command("validate [manifest]")
     .description("Validate an apollo.service.json (path or URL) against the apollo.dev/v1 schema")
@@ -63,14 +64,14 @@ program
     .command("graph")
     .description("Render the catalogue's consumes-graph")
     .option("--mermaid", "emit a mermaid `graph LR` block instead of ascii")
-    .action(async (options) => runGraph(options));
+    .action(async (options) => runGraph(options, program.opts()));
 program
     .command("doctor")
     .description("Check key validity, credential health, and manifest conformance")
-    .action(async () => runDoctor());
+    .action(async () => runDoctor(program.opts()));
 program
     .command("open <service>")
     .description("Open the service's endpoint (or repository) in the browser")
     .option("--env <name>", "pick a specific endpoint environment (default: production)")
-    .action(async (service, options) => runOpen(service, options));
+    .action(async (service, options) => runOpen(service, options, program.opts()));
 await program.parseAsync(process.argv);

package/dist/lib/apollo_client.js

@@ -1,9 +1,11 @@
 // packages/cli/src/lib/apollo_client.ts - HTTP client for the Apollo discovery
 // plane: catalogue fetch + credential exchange + key validation.
-// The discovery plane lives at one hosted location (consumer-journey §9.1 —
-// location baked in). Hardcoded; no flag or env override.
-export const APOLLO_URL = "https://apollo.nurix-ai.co";
+const DEFAULT_APOLLO_URL = "https://apollo.nurix-ai.co";
 const REQUEST_TIMEOUT_MS = 10_000;
+// Resolve the Apollo base URL: --apollo-url flag > APOLLO_URL env > hosted default.
+export function resolveApolloUrl(options) {
+    return (options.apolloUrl ?? process.env.APOLLO_URL ?? DEFAULT_APOLLO_URL).replace(/\/+$/, "");
+}
 // Fetch the public discovery catalogue.
 export async function fetchCatalogue(baseUrl) {
     const response = await fetch(`${baseUrl}/api/catalog.json`, {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nurix/apollo",
-    "version": "0.4.0",
+    "version": "0.4.2",
     "description": "The apollo CLI — bootstrap NuStack services into a repo via the Apollo discovery plane.",
     "type": "module",
     "private": false,