@hobble-env/cli 3.1.0 → 3.3.0

package/README.md

@@ -34,30 +34,30 @@ npm run hobble -- <command>
 
 ## Getting Started
 
-### 1. Create an API Key
-
-Generate an API key from the dashboard under **Settings > API Keys**.
-
-### 2. Log In
+One command does it all:
 
 ```bash
-hobble login
+hobble init --url https://secrets.your-company.dev
 ```
 
-You'll be prompted for your API key and the dashboard URL (defaults to `http://localhost:3000`).
+If you aren't signed in to that instance yet (or your session expired), `init` starts the browser login first, then walks you through selecting a project and environment, saves the choice to a `.hobble` file in your current directory, and pins the instance URL in it. Drop that line in a project README and a new teammate is set up in one step.
 
-### 3. Initialize a Project
+Without `--url`, `init` targets your default instance (`http://localhost:3000` until you've logged in somewhere). You can switch project/environment later with:
 
 ```bash
-hobble init
+hobble switch my-project/staging
 ```
 
-This walks you through selecting a project and environment, then saves the choice to a `.hobble` file in your current directory. You can switch later with:
+### Logging in separately
 
 ```bash
-hobble switch my-project/staging
+hobble login                   # browser device flow; prompts for the URL
+hobble login --url https://secrets.your-company.dev
+hobble login --api-key         # paste a long-lived API key instead
 ```
 
+API keys are generated from the dashboard under **Settings > API Keys**. Credentials are stored per instance, so logging in to a second instance doesn't sign you out of the first.
+
 ## Commands
 
 ### Secrets
@@ -122,24 +122,41 @@ hobble env push -i .env.local  # Push from a custom path
 ### Account
 
 ```bash
-hobble whoami                  # Show current user and org info
-hobble logout                  # Remove stored credentials
+hobble whoami                  # Show current user, org, and instance info
+hobble logout                  # Remove credentials for the current instance
+hobble logout --all            # Remove credentials for every instance
 ```
 
 ## Configuration
 
 ### Global Config
 
-Stored at `~/.config/hobble/config.json` after `hobble login`. Contains your API key and dashboard URL.
+Stored at `~/.config/hobble/config.json` after `hobble login` or `hobble init`. Holds your default instance URL and one credential per instance:
+
+```json
+{
+  "apiUrl": "https://secrets.your-company.dev",
+  "credentials": {
+    "https://secrets.your-company.dev": { "type": "session", "token": "…", "expiresAt": "…" },
+    "http://localhost:3000": { "type": "apiKey", "token": "…" }
+  }
+}
+```
 
 Override with environment variables:
 
-- `HOBBLE_API_KEY` -- override the stored API key
-- `HOBBLE_API_URL` -- override the stored dashboard URL
+- `HOBBLE_API_KEY` -- override the stored credential
+- `HOBBLE_API_URL` -- override the instance URL
 
 ### Project Config
 
-The `.hobble` file in your project directory stores the default project and environment. Add it to `.gitignore` -- `hobble init` will offer to do this for you.
+The `.hobble` file in your project directory stores the default project and environment, and optionally pins an instance URL (written by `hobble init --url`):
+
+```json
+{ "project": "my-app", "environment": "staging", "apiUrl": "https://secrets.your-company.dev" }
+```
+
+A pinned `apiUrl` takes precedence over the global default (but not over `HOBBLE_API_URL`), so different checkouts can talk to different instances. Credentials never live in `.hobble`. Add it to `.gitignore` -- `hobble init` will offer to do this for you.
 
 Override per-command with flags:
 

package/SKILL.md

@@ -5,6 +5,10 @@ description: Use when a repository contains a `.hobble` file, references the hob
 
 # Using the hobble CLI
 
+> **Living document.** This file is the canonical agent-facing reference for the hobble CLI surface. Per the gate in `AGENTS.md`, any feature work that changes the CLI surface (commands, flags, arguments, output formats, exit behavior, env vars, or config files) MUST update this file in the same change, and it must be verified current before every PR. Source of truth: `cli/bin/hobble.ts` and `cli/commands/*.ts`.
+
+<!-- documented-version: 3.2.0 — keep in sync with cli/bin/hobble.ts -->
+
 ## Overview
 
 `hobble` fetches secrets from a remote hobble dashboard and makes them available to local processes. Secrets are never stored on disk unless a user explicitly runs `hobble env pull`. The safe default is in-memory injection via `hobble run`.
@@ -12,13 +16,15 @@ description: Use when a repository contains a `.hobble` file, references the hob
 ## Detecting hobble in a Repo
 
 Treat a repo as a hobble consumer if any of these are true:
-- A `.hobble` file exists in the repo root. It is JSON: `{ "project": "...", "environment": "..." }`.
+- A `.hobble` file exists in the repo root. It is JSON: `{ "project": "...", "environment": "..." }`, optionally with an `"apiUrl"` pinning the instance for that directory.
 - `.gitignore` lists `.hobble`.
 - Scripts, Makefiles, or docs invoke `hobble ...`.
 - `package.json` has a script wrapping `hobble run`.
 
 If none of these are present, the repo is not a hobble consumer — do not introduce `hobble` without asking.
 
+In this repo, the CLI runs from source: `npm run hobble -- <command>` (or `npx tsx cli/bin/hobble.ts <command>`). Elsewhere it is the globally installed `hobble` binary from `@hobble-env/cli`.
+
 ## Critical Rules
 
 1. **Never commit `.hobble`, `.env`, `.env.local`, or any file produced by `hobble env pull`.** Before running pull, confirm `.gitignore` covers the output path.
@@ -31,22 +37,71 @@ If none of these are present, the repo is not a hobble consumer — do not intro
 5. **Do not run interactive commands unprompted.** `hobble login`, `hobble init`, and `hobble switch` modify user or repo state. Ask the user to run them, or explicitly confirm before doing so.
 6. **Never run `hobble env push -y` without showing the diff first.** Omit `-y` (or run once without it) so the user can review create/update/delete counts.
 
-## Quick Reference
-
-| Task | Command |
-|------|---------|
-| Run code with secrets injected | `hobble run -- <cmd>` |
-| List secret names (no values) | `hobble list` |
-| Read one value | `hobble get KEY` |
-| Create or update a secret | `printf '%s' "$v" \| hobble set KEY -` |
-| Delete a secret | `hobble delete KEY -y` |
-| Write `.env` file (use sparingly) | `hobble env pull` |
-| Upload local `.env` to dashboard | `hobble env push` (review diff before `-y`) |
-| Change bound project/env | `hobble switch <project>/<env>` |
-| Who am I / which org | `hobble whoami` |
+## Command Surface (v3.2.0)
+
+Global options: `-v, --verbose` (debug output on stderr), `-V, --version`.
+
+| Command | Arguments / flags | Notes |
+|---------|-------------------|-------|
+| `login` | `--url <url>`, `--api-key`, `--no-browser` | Interactive. Browser device flow by default; `--api-key` for a long-lived key. `--url` targets an instance and skips the URL prompt. Credentials are stored per instance URL in `~/.config/hobble/config.json`; the URL becomes the global default. |
+| `logout` | `--all` | Removes stored credentials for the effective instance only; other instances stay logged in. `--all` removes every credential. |
+| `whoami` | — | User, org, role, effective instance URL, and auth type (api key vs. session + expiry). |
+| `init` | `--url <url>` | Interactive one-stop setup: signs in first when not authenticated (or session expired) against the effective instance, then selects project/env, writes `.hobble`, offers to gitignore it. `--url` pins the instance into `.hobble` (`"apiUrl"`). Non-TTY without credentials exits 1 with `Not logged in to <url>`. |
+| `switch <project>/<env>` | — | Rewrites `.hobble` after validating both exist. Preserves an `"apiUrl"` pin. |
+| `list` | `--project`, `--env`, `--json`, `--tag <name>` (repeatable) | Names + tags + dates, never values. `--tag` is an AND filter, case-insensitive. |
+| `get <key>` | `--project`, `--env`, `--json` | Decrypted value. Output shape depends on TTY — see Composition. |
+| `set <key> [value\|-]` | `--project`, `--env`, `--comment <text>`, `--tag <name>` (repeatable) | Create-or-update. `-` or omitted value reads stdin (trailing whitespace trimmed). `--tag` **replaces** all existing tags. `--comment ""` clears the comment. |
+| `tags` | `--project`, `--env`, `--json` | Tags available to the project (name + color). `--env` accepted but unused. |
+| `delete <key>` | `--project`, `--env`, `-y` | Confirmation prompt unless `-y`. |
+| `run <cmd...>` | `--project`, `--env` | Injects all secrets into a subprocess (in-memory, `shell: true`). Use `--` before the command so its flags aren't parsed by hobble. Exits with the child's exit code. |
+| `shell` | `--project`, `--env` | Interactive subshell with secrets injected. Sets `HOBBLE_PROJECT`, `HOBBLE_ENVIRONMENT`, `HOBBLE_SHELL=<project>/<env>`; prefixes bash/zsh prompts. Interactive — don't run unprompted. |
+| `env pull` | `--project`, `--env`, `--force`, `-o <path>` (default `.env`) | Writes plaintext secrets + comments to disk. Refuses to overwrite without `--force`. Use sparingly (Rule 2). |
+| `env push` | `--project`, `--env`, `-y`, `-i <path>` (default `.env`) | Diffs file against server, prints create/update/delete lists, confirms unless `-y`. **An empty value (`KEY=`) deletes that secret on the server.** Contiguous `# ...` lines above a key become its comment; comments are only sent when changed. |
 
 All data commands accept `--project <name> --env <name>` to override `.hobble` for a single invocation. Prefer flags over `hobble switch` for one-off reads.
 
+## Composition: Retrieving Items for Other Commands
+
+The CLI is designed to be piped. The contract:
+
+- **stdout carries only data** — JSON (with `--json`) or a raw secret value (`get` when piped).
+- **stderr carries everything human-facing** — tables, `✓`/`ℹ`/`⚠` status lines, and `--verbose` debug output.
+
+So `--json` output and `2>/dev/null`-free piping are always safe; you never need to strip decoration from stdout.
+
+`hobble get KEY` is TTY-sensitive:
+- Piped / captured (non-TTY): writes the **raw value only, no trailing newline** — safe for command substitution.
+- Interactive terminal: prints `KEY=value` plus a `# tags: ...` line.
+
+Patterns:
+
+```bash
+# Feed a value directly to a consumer — never through echo or a variable you print
+hobble get DB_PASS | docker login --password-stdin -u "$user"
+
+# Enumerate keys for scripting
+hobble list --json | jq -r '.[].key'
+
+# Keys carrying a given tag (server-side list, client-side AND filter)
+hobble list --tag database --json | jq -r '.[].key'
+
+# Structured single-secret read: {"key", "value", "tags": [...]}
+hobble get DB_HOST --json | jq -r '.value'
+
+# Tag inventory for a project
+hobble tags --json | jq -r '.[].name'
+
+# Copy one secret between environments without it touching disk or argv
+hobble get API_KEY --env staging | hobble set API_KEY - --env production
+```
+
+JSON shapes:
+- `list --json`: array of `{ id, key, createdAt, updatedAt, tags: [{ id, name, color }] }` — no values.
+- `get --json`: `{ key, value, tags: [name, ...] }`.
+- `tags --json`: array of `{ id, name, color }`.
+
+All commands exit `0` on success and `1` on any failure (not found, auth, network), with the reason on stderr.
+
 ## Context Resolution
 
 Each data command needs a `project` and `environment`, resolved in order:
@@ -58,9 +113,11 @@ If you hit that error, stop and ask the user. Do not run `hobble init` on their
 
 ## Authentication
 
-- Stored config: `~/.config/hobble/config.json` (written by `hobble login`).
+- Stored config: `~/.config/hobble/config.json` (written by `hobble login` / `hobble init`). Shape: `{ "apiUrl": "<default instance>", "credentials": { "<instance url>": { "type": "apiKey" | "session", ... } } }` — one credential per instance URL, so logins to multiple instances coexist. Older single-credential config files migrate automatically on first read.
+- Instance URL resolution order: `HOBBLE_API_URL` env var > `"apiUrl"` in `.hobble` > global default in config.json > `http://localhost:3000`. The credential used is the one stored for the resolved URL (`HOBBLE_API_KEY` overrides everything).
 - Overrides via env vars: `HOBBLE_API_KEY`, `HOBBLE_API_URL`. Prefer these in CI.
-- A 401 error means the key is stale — tell the user to run `hobble login` rather than re-running it yourself.
+- A 401 means the credential is stale or expired — tell the user to run `hobble login` rather than re-running it yourself. `hobble whoami` shows the effective instance, auth type, and session expiry.
+- `HOBBLE_ASSUME_TTY=1` makes `init` treat piped stdin as interactive (test harness escape hatch — do not use it to bypass Rule 5).
 
 ## Common Mistakes
 
@@ -68,10 +125,13 @@ If you hit that error, stop and ask the user. Do not run `hobble init` on their
 |---------|------------------|
 | `hobble set KEY "mysecret"` | `printf '%s' "$v" \| hobble set KEY -` — args leak to shell history |
 | `hobble env pull` to "inspect" secrets | Use `hobble list` for keys; `hobble get KEY` piped to the consumer for one value |
+| Parsing `hobble list` table output | Tables go to stderr and aren't stable. Use `--json` + `jq` |
+| `hobble set KEY - --tag new` to "add" a tag | `--tag` replaces the full tag set — pass every tag the secret should keep |
+| Pushing a `.env` containing `KEY=` lines | Empty value = **delete on server**. Review the diff (no `-y`) before confirming |
 | `git add -A` after `hobble env pull` | Verify `.gitignore`, then stage files by name |
 | Running `hobble login` / `hobble init` to "set things up" | Ask the user — both are interactive and user-scoped |
 | Committing `.hobble` because it has no secrets | It binds the repo to a project/env and should always be gitignored |
-| `hobble env push -y` on a dirty `.env` | Run without `-y` first to see the create/update/delete diff |
+| `hobble run npm test -- --grep foo` flag confusion | Put `--` after `run`: `hobble run -- npm test` so hobble doesn't eat the flags |
 
 ## Running Tests That Need Secrets
 
@@ -89,3 +149,13 @@ hobble env pull && npm test
 ## When hobble Is Missing
 
 If `hobble` is not installed but the repo needs it, tell the user rather than guessing. Installation is user-specific (global npm vs. per-repo), and the dashboard URL and API key must be set up interactively via `hobble login`.
+
+## Maintaining This Document
+
+When CLI feature work lands, update in the same change:
+1. The **Command Surface** table (new command, flag, argument, or default).
+2. **Composition** (any change to stdout/stderr behavior, JSON shapes, TTY handling, or exit codes — these are load-bearing for scripts).
+3. **Critical Rules / Common Mistakes** if the change creates a new way to leak a secret or a new footgun.
+4. The version marker at the top of this file (match `cli/bin/hobble.ts`).
+
+Verify claims against the source, not memory: `cli/bin/hobble.ts` registers commands; each `cli/commands/*.ts` defines its flags; `cli/lib/output.ts` defines the stdout/stderr contract; `cli/lib/config.ts` and `cli/lib/api.ts` define auth and env-var overrides.

package/dist/bin/hobble.js

@@ -19,7 +19,7 @@ const program = new Command();
 program
     .name("hobble")
     .description("CLI for managing secrets via the secret-management-dash API")
-    .version("3.0.1")
+    .version("3.2.0")
     .enablePositionalOptions()
     .option("-v, --verbose", "Show debug output for troubleshooting");
 program.hook("preAction", (thisCommand) => {

package/dist/commands/init.js

@@ -1,12 +1,21 @@
 import { Command } from "commander";
 import inquirer from "inquirer";
-import { api } from "../lib/api.js";
-import { saveProjectConfig, addToGitignore, isHobbleInGitignore, } from "../lib/project-config.js";
+import { api, setApiUrlOverride } from "../lib/api.js";
+import { ensureAuthenticated } from "../lib/auth-flow.js";
+import { loadProjectConfig, saveProjectConfig, addToGitignore, isHobbleInGitignore, } from "../lib/project-config.js";
 import { success, error } from "../lib/output.js";
 export const initCommand = new Command("init")
-    .description("Configure project and environment for this directory")
-    .action(async () => {
+    .description("Configure project and environment for this directory (signs you in first if needed)")
+    .option("--url <url>", "Hobble instance URL — logs in against it and pins it in .hobble")
+    .action(async (opts) => {
     try {
+        // One-stop setup: authenticate (or re-authenticate) against the
+        // effective instance before touching the API.
+        const apiUrl = await ensureAuthenticated({ url: opts.url });
+        // Pin every API call in this run to the instance we just verified —
+        // .hobble doesn't exist yet to carry the override.
+        setApiUrlOverride(apiUrl);
+        const existing = await loadProjectConfig();
         // Fetch projects
         const projectData = (await api.get("/api/v1/projects"));
         if (projectData.projects.length === 0) {
@@ -42,9 +51,13 @@ export const initCommand = new Command("init")
                 })),
             },
         ]);
+        // Pin the instance in .hobble when --url named one explicitly, and
+        // preserve a pin a previous init/switch already wrote.
+        const pinnedUrl = opts.url ? apiUrl : existing?.apiUrl;
         await saveProjectConfig({
             project: selectedProject.name,
             environment: envName,
+            ...(pinnedUrl ? { apiUrl: pinnedUrl } : {}),
         });
         // Offer to add .hobble to .gitignore — but only if it's not already there
         const alreadyIgnored = await isHobbleInGitignore();
@@ -61,7 +74,9 @@ export const initCommand = new Command("init")
                 await addToGitignore();
             }
         }
-        success(`Configured: ${selectedProject.name}/${envName}`);
+        success(pinnedUrl
+            ? `Configured: ${selectedProject.name}/${envName} @ ${pinnedUrl}`
+            : `Configured: ${selectedProject.name}/${envName}`);
     }
     catch (err) {
         error(err.message);

package/dist/commands/login.js

@@ -1,223 +1,16 @@
 import { Command } from "commander";
-import inquirer from "inquirer";
-import { loadConfig, saveConfig, normalizeApiUrl, } from "../lib/config.js";
-import { success, error, debug, info } from "../lib/output.js";
-import { requestDeviceCode, pollForToken, normalizeExpiresAt, DeviceFlowDeniedError, DeviceFlowExpiredError, } from "../lib/browser-login.js";
-const DEFAULT_API_URL = "http://localhost:3000";
-async function getDefaultApiUrl() {
-    const existing = await loadConfig();
-    return existing?.apiUrl ?? DEFAULT_API_URL;
-}
-async function fetchWhoami(apiUrl, headers) {
-    const url = `${apiUrl}/api/v1/whoami`;
-    debug(`GET ${url}`);
-    const res = await fetch(url, { headers });
-    debug(`${res.status} ${res.statusText}`);
-    if (!res.ok)
-        throw new Error(`whoami failed (${res.status})`);
-    return (await res.json());
-}
-function printSuccess(data) {
-    const membership = data.memberships[0];
-    if (membership) {
-        success(`Logged in as ${data.user.email} (${membership.name ?? membership.organizationId}, ${membership.role})`);
-    }
-    else {
-        success(`Logged in as ${data.user.email}`);
-    }
-}
-async function readStdinLines(n) {
-    return new Promise((resolve) => {
-        const lines = [];
-        let buf = "";
-        process.stdin.setEncoding("utf-8");
-        process.stdin.on("data", (chunk) => {
-            buf += chunk;
-            const parts = buf.split("\n");
-            buf = parts.pop() ?? "";
-            for (const line of parts) {
-                lines.push(line);
-                if (lines.length >= n) {
-                    process.stdin.pause();
-                    resolve(lines);
-                    return;
-                }
-            }
-        });
-        process.stdin.on("end", () => {
-            if (buf.length > 0)
-                lines.push(buf);
-            resolve(lines);
-        });
-        process.stdin.resume();
-    });
-}
-async function loginWithApiKey() {
-    let answers;
-    const defaultApiUrl = await getDefaultApiUrl();
-    if (!process.stdin.isTTY) {
-        // Non-interactive mode: read two lines from stdin (apiKey, apiUrl)
-        const lines = await readStdinLines(2);
-        const apiKey = lines[0] ?? "";
-        const rawApiUrl = lines[1]?.trim() || defaultApiUrl;
-        if (!apiKey) {
-            error("API key is required");
-            process.exit(1);
-        }
-        answers = { apiKey, apiUrl: normalizeApiUrl(rawApiUrl) };
-    }
-    else {
-        const prompted = await inquirer.prompt([
-            {
-                type: "password",
-                name: "apiKey",
-                message: "API Key:",
-                mask: "*",
-                validate: (v) => (v.length > 0 ? true : "API key is required"),
-            },
-            {
-                type: "input",
-                name: "apiUrl",
-                message: "API URL:",
-                default: defaultApiUrl,
-            },
-        ]);
-        answers = { apiKey: prompted.apiKey, apiUrl: normalizeApiUrl(prompted.apiUrl) };
-    }
-    const headers = {
-        "x-api-key": answers.apiKey,
-        "Content-Type": "application/json",
-    };
-    let data;
-    try {
-        data = await fetchWhoami(answers.apiUrl, headers);
-    }
-    catch (err) {
-        const msg = err.message;
-        if (msg.includes("401") || msg.toLowerCase().includes("invalid")) {
-            error("API key is invalid or expired.");
-            process.exit(1);
-        }
-        if (msg.includes("fetch") ||
-            msg.includes("ECONNREFUSED") ||
-            msg.includes("ENOTFOUND")) {
-            error(`Could not reach the server at ${answers.apiUrl}. Check the URL and try again.`);
-            process.exit(1);
-        }
-        error(`Login failed: ${msg}`);
-        process.exit(1);
-    }
-    const credential = { type: "apiKey", token: answers.apiKey };
-    await saveConfig({ apiUrl: answers.apiUrl, auth: credential });
-    printSuccess(data);
-}
-async function loginWithBrowser(opts) {
-    const defaultApiUrl = await getDefaultApiUrl();
-    const { apiUrl: rawApiUrl } = await inquirer.prompt([
-        {
-            type: "input",
-            name: "apiUrl",
-            message: "API URL:",
-            default: defaultApiUrl,
-        },
-    ]);
-    const apiUrl = normalizeApiUrl(rawApiUrl);
-    let codeRes;
-    try {
-        codeRes = await requestDeviceCode(apiUrl);
-    }
-    catch (err) {
-        const msg = err.message;
-        if (msg.includes("fetch") ||
-            msg.includes("ECONNREFUSED") ||
-            msg.includes("ENOTFOUND")) {
-            error(`Could not reach the server at ${apiUrl}. Check the URL and try again.`);
-            process.exit(1);
-        }
-        error(`Could not start device login: ${msg}`);
-        process.exit(1);
-    }
-    const verificationUrl = codeRes.verification_uri_complete ?? codeRes.verification_uri;
-    const absoluteUrl = verificationUrl.startsWith("http")
-        ? verificationUrl
-        : `${apiUrl}${verificationUrl}`;
-    info(`First copy your one-time code: ${codeRes.user_code}`);
-    if (opts.noBrowser) {
-        info(`Open this URL in your browser to continue:`);
-        info(absoluteUrl);
-    }
-    else {
-        info(`Press Enter to open ${absoluteUrl} in your browser…`);
-        await inquirer.prompt([{ type: "input", name: "_", message: "" }]);
-        if (process.env.HOBBLE_NO_OPEN !== "1") {
-            try {
-                const { default: open } = await import("open");
-                await open(absoluteUrl);
-            }
-            catch (err) {
-                debug(`open() failed: ${err.message}`);
-                // URL is already on stdout — no further action needed
-            }
-        }
-    }
-    info(`Waiting for authorization…`);
-    let token;
-    try {
-        token = await pollForToken({
-            apiUrl,
-            deviceCode: codeRes.device_code,
-            intervalSeconds: codeRes.interval ?? 5,
-        });
-    }
-    catch (err) {
-        if (err instanceof DeviceFlowDeniedError) {
-            error("Authorization denied.");
-            process.exit(1);
-        }
-        if (err instanceof DeviceFlowExpiredError) {
-            error("The login code expired. Run `hobble login` to try again.");
-            process.exit(1);
-        }
-        error(`Login failed: ${err.message}`);
-        process.exit(1);
-    }
-    // Better-Auth's device token endpoint returns `expires_in` (seconds) rather than
-    // `expires_at`. Fall back to computing the absolute expiry from `expires_in` when
-    // `expires_at` is absent.
-    const rawExpiresAt = token.expires_at !== undefined
-        ? token.expires_at
-        : token.expires_in !== undefined
-            ? Date.now() / 1000 + token.expires_in
-            : Date.now() / 1000 + 604800; // default: 7 days
-    const expiresAt = normalizeExpiresAt(rawExpiresAt);
-    const headers = {
-        Authorization: `Bearer ${token.access_token}`,
-        "Content-Type": "application/json",
-    };
-    let data;
-    try {
-        data = await fetchWhoami(apiUrl, headers);
-    }
-    catch (err) {
-        error(`Token validation failed: ${err.message}`);
-        process.exit(1);
-    }
-    await saveConfig({
-        apiUrl,
-        auth: { type: "session", token: token.access_token, expiresAt },
-    });
-    printSuccess(data);
-}
+import { loginWithApiKey, loginWithBrowser } from "../lib/auth-flow.js";
 export const loginCommand = new Command("login")
     .description("Authenticate with the secret management API")
+    .option("--url <url>", "Instance URL to sign in to (skips the URL prompt)")
     .option("--api-key", "Sign in with a long-lived API key (instead of browser session)")
     .option("--no-browser", "Skip opening the browser; print the URL only")
     .action(async (opts) => {
     // Commander represents `--no-browser` as `opts.browser === false`
     const noBrowser = opts.browser === false;
     if (opts.apiKey) {
-        await loginWithApiKey();
+        await loginWithApiKey({ url: opts.url });
         return;
     }
-    await loginWithBrowser({ noBrowser });
+    await loginWithBrowser({ url: opts.url, noBrowser });
 });

package/dist/commands/logout.js

@@ -1,25 +1,56 @@
 import { Command } from "commander";
 import inquirer from "inquirer";
-import { deleteConfig, loadConfig } from "../lib/config.js";
+import { deleteConfig, getApiUrl, loadConfig, removeCredential, } from "../lib/config.js";
+import { loadProjectConfig } from "../lib/project-config.js";
 import { success, info } from "../lib/output.js";
 export const logoutCommand = new Command("logout")
-    .description("Remove stored credentials")
-    .action(async () => {
+    .description("Remove stored credentials for the current instance")
+    .option("--all", "Remove stored credentials for every instance")
+    .action(async (opts) => {
     const config = await loadConfig();
-    if (!config) {
+    const instances = config ? Object.keys(config.credentials) : [];
+    if (!config || instances.length === 0) {
         info("Not logged in.");
         return;
     }
+    if (opts.all) {
+        const { confirm } = await inquirer.prompt([
+            {
+                type: "confirm",
+                name: "confirm",
+                message: `Remove stored credentials for ${instances.length === 1 ? "1 instance" : `${instances.length} instances`}?`,
+                default: false,
+            },
+        ]);
+        if (!confirm)
+            return;
+        await deleteConfig();
+        success("Logged out everywhere.");
+        return;
+    }
+    const projectConfig = await loadProjectConfig();
+    const apiUrl = getApiUrl(config, projectConfig?.apiUrl ?? null);
+    if (!config.credentials[apiUrl]) {
+        info(`Not logged in to ${apiUrl}.`);
+        if (instances.length > 0) {
+            info(`Stored credentials exist for: ${instances.join(", ")} — use \`hobble logout --all\` to remove them.`);
+        }
+        return;
+    }
     const { confirm } = await inquirer.prompt([
         {
             type: "confirm",
             name: "confirm",
-            message: "Remove stored credentials?",
+            message: `Remove stored credentials for ${apiUrl}?`,
             default: false,
         },
     ]);
     if (!confirm)
         return;
-    await deleteConfig();
-    success("Logged out.");
+    await removeCredential(apiUrl);
+    const remaining = instances.filter((u) => u !== apiUrl);
+    success(`Logged out of ${apiUrl}.`);
+    if (remaining.length > 0) {
+        info(`Still logged in to: ${remaining.join(", ")} — use \`hobble logout --all\` to remove everything.`);
+    }
 });

package/dist/commands/switch.js

@@ -1,6 +1,6 @@
 import { Command } from "commander";
 import { api } from "../lib/api.js";
-import { saveProjectConfig } from "../lib/project-config.js";
+import { loadProjectConfig, saveProjectConfig } from "../lib/project-config.js";
 import { success, error } from "../lib/output.js";
 export const switchCommand = new Command("switch")
     .description("Switch project and environment")
@@ -27,7 +27,13 @@ export const switchCommand = new Command("switch")
             error(`Environment "${envName}" not found in project "${projectName}".`);
             process.exit(1);
         }
-        await saveProjectConfig({ project: projectName, environment: envName });
+        // Keep an instance pin from a previous `init --url` intact.
+        const existing = await loadProjectConfig();
+        await saveProjectConfig({
+            project: projectName,
+            environment: envName,
+            ...(existing?.apiUrl ? { apiUrl: existing.apiUrl } : {}),
+        });
         success(`Switched to ${projectName}/${envName}`);
     }
     catch (err) {

package/dist/commands/whoami.js

@@ -1,6 +1,7 @@
 import { Command } from "commander";
 import { api } from "../lib/api.js";
-import { loadConfig } from "../lib/config.js";
+import { getApiUrl, loadConfig } from "../lib/config.js";
+import { loadProjectConfig } from "../lib/project-config.js";
 import { error } from "../lib/output.js";
 function describeExpiry(expiresAt) {
     const ms = Date.parse(expiresAt);
@@ -31,10 +32,16 @@ export const whoamiCommand = new Command("whoami")
             console.log("Org:   (no memberships)");
         }
         const config = await loadConfig();
-        if (config?.auth.type === "session") {
-            console.log(`Auth:  session (${describeExpiry(config.auth.expiresAt)})`);
+        const projectConfig = await loadProjectConfig();
+        const apiUrl = getApiUrl(config, projectConfig?.apiUrl ?? null);
+        console.log(`Instance: ${apiUrl}`);
+        const credential = process.env.HOBBLE_API_KEY
+            ? { type: "apiKey" }
+            : config?.credentials[apiUrl];
+        if (credential?.type === "session") {
+            console.log(`Auth:  session (${describeExpiry(credential.expiresAt)})`);
         }
-        else if (config?.auth.type === "apiKey") {
+        else if (credential?.type === "apiKey") {
             console.log(`Auth:  api key`);
         }
     }

package/dist/lib/api.d.ts

@@ -2,6 +2,12 @@ export declare class ApiError extends Error {
     status: number;
     constructor(status: number, message: string);
 }
+/**
+ * Pin the instance URL for the rest of this process. Used by `hobble init
+ * --url` so its API calls hit the instance it just authenticated against,
+ * before any .hobble file exists to record it.
+ */
+export declare function setApiUrlOverride(url: string): void;
 export declare const api: {
     get: (path: string) => Promise<unknown>;
     post: (path: string, body: unknown) => Promise<unknown>;

package/dist/lib/api.js

@@ -1,4 +1,5 @@
 import { loadConfig, getApiUrl, getAuthCredential } from "./config.js";
+import { loadProjectConfig } from "./project-config.js";
 import { debug } from "./output.js";
 export class ApiError extends Error {
     status;
@@ -8,8 +9,17 @@ export class ApiError extends Error {
         this.name = "ApiError";
     }
 }
-async function getHeaders() {
-    const credential = await getAuthCredential();
+let apiUrlOverride = null;
+/**
+ * Pin the instance URL for the rest of this process. Used by `hobble init
+ * --url` so its API calls hit the instance it just authenticated against,
+ * before any .hobble file exists to record it.
+ */
+export function setApiUrlOverride(url) {
+    apiUrlOverride = url;
+}
+async function getHeaders(baseUrl) {
+    const credential = await getAuthCredential(baseUrl);
     if (credential.type === "apiKey") {
         return {
             headers: {
@@ -29,13 +39,24 @@ async function getHeaders() {
 }
 let _baseUrlLogged = false;
 async function getBaseUrl() {
+    if (apiUrlOverride) {
+        if (!_baseUrlLogged) {
+            _baseUrlLogged = true;
+            debug(`Config: API URL pinned for this run (${apiUrlOverride})`);
+        }
+        return apiUrlOverride;
+    }
     const config = await loadConfig();
-    const url = getApiUrl(config);
+    const projectConfig = await loadProjectConfig();
+    const url = getApiUrl(config, projectConfig?.apiUrl ?? null);
     if (!_baseUrlLogged) {
         _baseUrlLogged = true;
         if (process.env.HOBBLE_API_URL) {
             debug(`Config: API URL from HOBBLE_API_URL (${url})`);
         }
+        else if (projectConfig?.apiUrl) {
+            debug(`Config: API URL from .hobble (${url})`);
+        }
         else if (config?.apiUrl) {
             debug(`Config: API URL from ~/.config/hobble/config.json (${url})`);
         }
@@ -47,7 +68,7 @@ async function getBaseUrl() {
 }
 async function request(method, path, body) {
     const baseUrl = await getBaseUrl();
-    const { headers, credentialType } = await getHeaders();
+    const { headers, credentialType } = await getHeaders(baseUrl);
     const fullUrl = `${baseUrl}${path}`;
     debug(`${method} ${fullUrl}`);
     let res;

package/dist/lib/auth-flow.d.ts

@@ -0,0 +1,21 @@
+export declare function loginWithApiKey(opts?: {
+    url?: string;
+}): Promise<void>;
+export declare function loginWithBrowser(opts?: {
+    url?: string;
+    noBrowser?: boolean;
+}): Promise<void>;
+/**
+ * Make sure the user is authenticated against the effective instance,
+ * starting the browser login flow inline when they aren't.
+ *
+ * Resolution order for the instance: explicit `url` (e.g. `init --url`) >
+ * HOBBLE_API_URL > .hobble apiUrl > global default. Returns the resolved URL.
+ *
+ * Only prompts on a TTY — non-interactive callers (CI) get the classic
+ * "Not logged in" error instead of a hung device-flow poll. HOBBLE_ASSUME_TTY=1
+ * lets the e2e harness exercise the interactive path through pipes.
+ */
+export declare function ensureAuthenticated(opts?: {
+    url?: string;
+}): Promise<string>;

package/dist/lib/auth-flow.js

@@ -0,0 +1,255 @@
+import inquirer from "inquirer";
+import { DEFAULT_API_URL, findCredential, getApiUrl, isExpired, loadConfig, normalizeApiUrl, saveCredential, } from "./config.js";
+import { loadProjectConfig } from "./project-config.js";
+import { success, error, debug, info } from "./output.js";
+import { requestDeviceCode, pollForToken, normalizeExpiresAt, DeviceFlowDeniedError, DeviceFlowExpiredError, } from "./browser-login.js";
+async function getDefaultApiUrl() {
+    const existing = await loadConfig();
+    return existing?.apiUrl ?? DEFAULT_API_URL;
+}
+async function fetchWhoami(apiUrl, headers) {
+    const url = `${apiUrl}/api/v1/whoami`;
+    debug(`GET ${url}`);
+    const res = await fetch(url, { headers });
+    debug(`${res.status} ${res.statusText}`);
+    if (!res.ok)
+        throw new Error(`whoami failed (${res.status})`);
+    return (await res.json());
+}
+function printSuccess(data) {
+    const membership = data.memberships[0];
+    if (membership) {
+        success(`Logged in as ${data.user.email} (${membership.name ?? membership.organizationId}, ${membership.role})`);
+    }
+    else {
+        success(`Logged in as ${data.user.email}`);
+    }
+}
+async function readStdinLines(n) {
+    return new Promise((resolve) => {
+        const lines = [];
+        let buf = "";
+        process.stdin.setEncoding("utf-8");
+        process.stdin.on("data", (chunk) => {
+            buf += chunk;
+            const parts = buf.split("\n");
+            buf = parts.pop() ?? "";
+            for (const line of parts) {
+                lines.push(line);
+                if (lines.length >= n) {
+                    process.stdin.pause();
+                    resolve(lines);
+                    return;
+                }
+            }
+        });
+        process.stdin.on("end", () => {
+            if (buf.length > 0)
+                lines.push(buf);
+            resolve(lines);
+        });
+        process.stdin.resume();
+    });
+}
+/**
+ * Resolve the URL a login flow should target: an explicit `--url` wins and
+ * skips the prompt entirely; otherwise the user is prompted with the saved
+ * default pre-filled.
+ */
+async function resolveLoginUrl(url) {
+    if (url)
+        return normalizeApiUrl(url);
+    const defaultApiUrl = await getDefaultApiUrl();
+    const { apiUrl: rawApiUrl } = await inquirer.prompt([
+        {
+            type: "input",
+            name: "apiUrl",
+            message: "API URL:",
+            default: defaultApiUrl,
+        },
+    ]);
+    return normalizeApiUrl(rawApiUrl);
+}
+export async function loginWithApiKey(opts = {}) {
+    let apiKey;
+    let apiUrl;
+    if (!process.stdin.isTTY) {
+        // Non-interactive mode. With --url only the key is read from stdin;
+        // without it, two lines: apiKey, then apiUrl.
+        if (opts.url) {
+            const lines = await readStdinLines(1);
+            apiKey = lines[0] ?? "";
+            apiUrl = normalizeApiUrl(opts.url);
+        }
+        else {
+            const defaultApiUrl = await getDefaultApiUrl();
+            const lines = await readStdinLines(2);
+            apiKey = lines[0] ?? "";
+            apiUrl = normalizeApiUrl(lines[1]?.trim() || defaultApiUrl);
+        }
+        if (!apiKey) {
+            error("API key is required");
+            process.exit(1);
+        }
+    }
+    else {
+        const prompted = await inquirer.prompt([
+            {
+                type: "password",
+                name: "apiKey",
+                message: "API Key:",
+                mask: "*",
+                validate: (v) => (v.length > 0 ? true : "API key is required"),
+            },
+        ]);
+        apiKey = prompted.apiKey;
+        apiUrl = await resolveLoginUrl(opts.url);
+    }
+    const headers = {
+        "x-api-key": apiKey,
+        "Content-Type": "application/json",
+    };
+    let data;
+    try {
+        data = await fetchWhoami(apiUrl, headers);
+    }
+    catch (err) {
+        const msg = err.message;
+        if (msg.includes("401") || msg.toLowerCase().includes("invalid")) {
+            error("API key is invalid or expired.");
+            process.exit(1);
+        }
+        if (msg.includes("fetch") ||
+            msg.includes("ECONNREFUSED") ||
+            msg.includes("ENOTFOUND")) {
+            error(`Could not reach the server at ${apiUrl}. Check the URL and try again.`);
+            process.exit(1);
+        }
+        error(`Login failed: ${msg}`);
+        process.exit(1);
+    }
+    const credential = { type: "apiKey", token: apiKey };
+    await saveCredential(apiUrl, credential);
+    printSuccess(data);
+}
+export async function loginWithBrowser(opts = {}) {
+    const apiUrl = await resolveLoginUrl(opts.url);
+    let codeRes;
+    try {
+        codeRes = await requestDeviceCode(apiUrl);
+    }
+    catch (err) {
+        const msg = err.message;
+        if (msg.includes("fetch") ||
+            msg.includes("ECONNREFUSED") ||
+            msg.includes("ENOTFOUND")) {
+            error(`Could not reach the server at ${apiUrl}. Check the URL and try again.`);
+            process.exit(1);
+        }
+        error(`Could not start device login: ${msg}`);
+        process.exit(1);
+    }
+    const verificationUrl = codeRes.verification_uri_complete ?? codeRes.verification_uri;
+    const absoluteUrl = verificationUrl.startsWith("http")
+        ? verificationUrl
+        : `${apiUrl}${verificationUrl}`;
+    info(`First copy your one-time code: ${codeRes.user_code}`);
+    if (opts.noBrowser) {
+        info(`Open this URL in your browser to continue:`);
+        info(absoluteUrl);
+    }
+    else {
+        info(`Press Enter to open ${absoluteUrl} in your browser…`);
+        await inquirer.prompt([{ type: "input", name: "_", message: "" }]);
+        if (process.env.HOBBLE_NO_OPEN !== "1") {
+            try {
+                const { default: open } = await import("open");
+                await open(absoluteUrl);
+            }
+            catch (err) {
+                debug(`open() failed: ${err.message}`);
+                // URL is already on stdout — no further action needed
+            }
+        }
+    }
+    info(`Waiting for authorization…`);
+    let token;
+    try {
+        token = await pollForToken({
+            apiUrl,
+            deviceCode: codeRes.device_code,
+            intervalSeconds: codeRes.interval ?? 5,
+        });
+    }
+    catch (err) {
+        if (err instanceof DeviceFlowDeniedError) {
+            error("Authorization denied.");
+            process.exit(1);
+        }
+        if (err instanceof DeviceFlowExpiredError) {
+            error("The login code expired. Run `hobble login` to try again.");
+            process.exit(1);
+        }
+        error(`Login failed: ${err.message}`);
+        process.exit(1);
+    }
+    // Better-Auth's device token endpoint returns `expires_in` (seconds) rather than
+    // `expires_at`. Fall back to computing the absolute expiry from `expires_in` when
+    // `expires_at` is absent.
+    const rawExpiresAt = token.expires_at !== undefined
+        ? token.expires_at
+        : token.expires_in !== undefined
+            ? Date.now() / 1000 + token.expires_in
+            : Date.now() / 1000 + 604800; // default: 7 days
+    const expiresAt = normalizeExpiresAt(rawExpiresAt);
+    const headers = {
+        Authorization: `Bearer ${token.access_token}`,
+        "Content-Type": "application/json",
+    };
+    let data;
+    try {
+        data = await fetchWhoami(apiUrl, headers);
+    }
+    catch (err) {
+        error(`Token validation failed: ${err.message}`);
+        process.exit(1);
+    }
+    await saveCredential(apiUrl, {
+        type: "session",
+        token: token.access_token,
+        expiresAt,
+    });
+    printSuccess(data);
+}
+/**
+ * Make sure the user is authenticated against the effective instance,
+ * starting the browser login flow inline when they aren't.
+ *
+ * Resolution order for the instance: explicit `url` (e.g. `init --url`) >
+ * HOBBLE_API_URL > .hobble apiUrl > global default. Returns the resolved URL.
+ *
+ * Only prompts on a TTY — non-interactive callers (CI) get the classic
+ * "Not logged in" error instead of a hung device-flow poll. HOBBLE_ASSUME_TTY=1
+ * lets the e2e harness exercise the interactive path through pipes.
+ */
+export async function ensureAuthenticated(opts = {}) {
+    const config = await loadConfig();
+    const projectConfig = await loadProjectConfig();
+    const apiUrl = opts.url
+        ? normalizeApiUrl(opts.url)
+        : getApiUrl(config, projectConfig?.apiUrl ?? null);
+    if (process.env.HOBBLE_API_KEY)
+        return apiUrl;
+    const credential = await findCredential(apiUrl);
+    if (credential && !isExpired(credential))
+        return apiUrl;
+    const interactive = process.stdin.isTTY || process.env.HOBBLE_ASSUME_TTY === "1";
+    if (!interactive) {
+        throw new Error(`Not logged in to ${apiUrl}. Run \`hobble login\` first.`);
+    }
+    info(credential
+        ? `Your session for ${apiUrl} has expired — signing in again.`
+        : `You're not logged in to ${apiUrl} yet — signing in first.`);
+    await loginWithBrowser({ url: apiUrl });
+    return apiUrl;
+}

package/dist/lib/config.d.ts

@@ -1,3 +1,4 @@
+export declare const DEFAULT_API_URL = "http://localhost:3000";
 export type AuthCredential = {
     type: "apiKey";
     token: string;
@@ -7,14 +8,40 @@ export type AuthCredential = {
     expiresAt: string;
 };
 export interface GlobalConfig {
+    /** Default instance, used when neither HOBBLE_API_URL nor .hobble names one. */
     apiUrl: string;
-    auth: AuthCredential;
+    /** Credentials keyed by instance URL, so logins to different instances coexist. */
+    credentials: Record<string, AuthCredential>;
 }
 export declare function loadConfig(): Promise<GlobalConfig | null>;
 export declare function saveConfig(config: GlobalConfig): Promise<void>;
+/**
+ * Store a credential for one instance. The instance also becomes the global
+ * default, so the most recent login is what URL-less commands talk to.
+ * Credentials for other instances are preserved.
+ */
+export declare function saveCredential(apiUrl: string, credential: AuthCredential): Promise<void>;
+/**
+ * Drop the credential for one instance. Removes the config file entirely when
+ * it was the last credential; otherwise re-points the default at a remaining
+ * instance if the removed one was the default.
+ */
+export declare function removeCredential(apiUrl: string): Promise<void>;
 export declare function deleteConfig(): Promise<void>;
-export declare function getAuthCredential(): Promise<AuthCredential>;
-export declare function getApiUrl(config: GlobalConfig | null): string;
+/** A session credential past its expiry. API-key credentials never expire here. */
+export declare function isExpired(credential: AuthCredential): boolean;
+/**
+ * Credential for one instance: HOBBLE_API_KEY always wins (CI escape hatch),
+ * otherwise the per-instance entry in the global config.
+ */
+export declare function findCredential(apiUrl: string): Promise<AuthCredential | null>;
+export declare function getAuthCredential(apiUrl: string): Promise<AuthCredential>;
+/**
+ * Effective instance URL: HOBBLE_API_URL env > .hobble override (passed in by
+ * the caller) > global default > localhost. Callers with a .hobble in scope
+ * pass its apiUrl as `projectApiUrl`.
+ */
+export declare function getApiUrl(config: GlobalConfig | null, projectApiUrl?: string | null): string;
 /**
  * Normalize a user-supplied API URL. If the input lacks a scheme (no `://`),
  * `https://` is assumed — typing `secrets.example.com` becomes
@@ -26,4 +53,3 @@ export declare function getApiUrl(config: GlobalConfig | null): string;
  * (typically by falling back to a default).
  */
 export declare function normalizeApiUrl(input: string): string;
-export declare function requireConfig(): Promise<GlobalConfig>;

package/dist/lib/config.js

@@ -3,15 +3,11 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 const CONFIG_DIR = join(homedir(), ".config", "hobble");
 const CONFIG_FILE = join(CONFIG_DIR, "config.json");
-function isGlobalConfig(value) {
+export const DEFAULT_API_URL = "http://localhost:3000";
+function isAuthCredential(value) {
     if (!value || typeof value !== "object")
         return false;
-    const v = value;
-    if (typeof v.apiUrl !== "string")
-        return false;
-    if (!v.auth || typeof v.auth !== "object")
-        return false;
-    const a = v.auth;
+    const a = value;
     if (a.type === "apiKey")
         return typeof a.token === "string";
     if (a.type === "session") {
@@ -19,14 +15,36 @@ function isGlobalConfig(value) {
     }
     return false;
 }
+function isGlobalConfig(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const v = value;
+    if (typeof v.apiUrl !== "string")
+        return false;
+    if (!v.credentials || typeof v.credentials !== "object")
+        return false;
+    return Object.values(v.credentials).every(isAuthCredential);
+}
 function migrateLegacy(parsed) {
-    if (typeof parsed.apiKey !== "string" || typeof parsed.apiUrl !== "string") {
+    if (!parsed || typeof parsed !== "object")
         return null;
+    const authShape = parsed;
+    if (typeof authShape.apiUrl === "string" && isAuthCredential(authShape.auth)) {
+        return {
+            apiUrl: authShape.apiUrl,
+            credentials: { [authShape.apiUrl]: authShape.auth },
+        };
     }
-    return {
-        apiUrl: parsed.apiUrl,
-        auth: { type: "apiKey", token: parsed.apiKey },
-    };
+    const keyShape = parsed;
+    if (typeof keyShape.apiKey === "string" && typeof keyShape.apiUrl === "string") {
+        return {
+            apiUrl: keyShape.apiUrl,
+            credentials: {
+                [keyShape.apiUrl]: { type: "apiKey", token: keyShape.apiKey },
+            },
+        };
+    }
+    return null;
 }
 export async function loadConfig() {
     let raw;
@@ -56,6 +74,39 @@ export async function saveConfig(config) {
     await mkdir(CONFIG_DIR, { recursive: true });
     await writeFile(CONFIG_FILE, JSON.stringify(config, null, 2) + "\n", "utf-8");
 }
+/**
+ * Store a credential for one instance. The instance also becomes the global
+ * default, so the most recent login is what URL-less commands talk to.
+ * Credentials for other instances are preserved.
+ */
+export async function saveCredential(apiUrl, credential) {
+    const existing = await loadConfig();
+    await saveConfig({
+        apiUrl,
+        credentials: { ...existing?.credentials, [apiUrl]: credential },
+    });
+}
+/**
+ * Drop the credential for one instance. Removes the config file entirely when
+ * it was the last credential; otherwise re-points the default at a remaining
+ * instance if the removed one was the default.
+ */
+export async function removeCredential(apiUrl) {
+    const config = await loadConfig();
+    if (!config)
+        return;
+    const credentials = { ...config.credentials };
+    delete credentials[apiUrl];
+    const remaining = Object.keys(credentials);
+    if (remaining.length === 0) {
+        await deleteConfig();
+        return;
+    }
+    await saveConfig({
+        apiUrl: config.apiUrl === apiUrl ? remaining[0] : config.apiUrl,
+        credentials,
+    });
+}
 export async function deleteConfig() {
     try {
         await rm(CONFIG_FILE);
@@ -64,17 +115,38 @@ export async function deleteConfig() {
         // already gone
     }
 }
-export async function getAuthCredential() {
+/** A session credential past its expiry. API-key credentials never expire here. */
+export function isExpired(credential) {
+    if (credential.type !== "session")
+        return false;
+    const ms = Date.parse(credential.expiresAt);
+    return Number.isFinite(ms) && ms <= Date.now();
+}
+/**
+ * Credential for one instance: HOBBLE_API_KEY always wins (CI escape hatch),
+ * otherwise the per-instance entry in the global config.
+ */
+export async function findCredential(apiUrl) {
     const envKey = process.env.HOBBLE_API_KEY;
     if (envKey)
         return { type: "apiKey", token: envKey };
     const config = await loadConfig();
-    if (!config?.auth)
-        throw new Error("Not logged in. Run `hobble login` first.");
-    return config.auth;
+    return config?.credentials[apiUrl] ?? null;
+}
+export async function getAuthCredential(apiUrl) {
+    const credential = await findCredential(apiUrl);
+    if (!credential) {
+        throw new Error(`Not logged in to ${apiUrl}. Run \`hobble login\` first.`);
+    }
+    return credential;
 }
-export function getApiUrl(config) {
-    return process.env.HOBBLE_API_URL ?? config?.apiUrl ?? "http://localhost:3000";
+/**
+ * Effective instance URL: HOBBLE_API_URL env > .hobble override (passed in by
+ * the caller) > global default > localhost. Callers with a .hobble in scope
+ * pass its apiUrl as `projectApiUrl`.
+ */
+export function getApiUrl(config, projectApiUrl) {
+    return (process.env.HOBBLE_API_URL ?? projectApiUrl ?? config?.apiUrl ?? DEFAULT_API_URL);
 }
 /**
  * Normalize a user-supplied API URL. If the input lacks a scheme (no `://`),
@@ -93,10 +165,3 @@ export function normalizeApiUrl(input) {
     const withScheme = trimmed.includes("://") ? trimmed : `https://${trimmed}`;
     return withScheme.replace(/\/+$/, "");
 }
-export async function requireConfig() {
-    const config = await loadConfig();
-    if (!config) {
-        throw new Error("Not logged in. Run `hobble login` first.");
-    }
-    return config;
-}

package/dist/lib/project-config.d.ts

@@ -1,6 +1,12 @@
 export interface ProjectConfig {
     project: string;
     environment: string;
+    /**
+     * Optional per-directory instance override. Takes precedence over the
+     * global default apiUrl (but not over HOBBLE_API_URL). Never holds
+     * credentials — those live in the user-scoped global config, keyed by URL.
+     */
+    apiUrl?: string;
 }
 export declare function loadProjectConfig(): Promise<ProjectConfig | null>;
 export declare function saveProjectConfig(config: ProjectConfig): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hobble-env/cli",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "description": "CLI for managing secrets via hobble",
   "type": "module",
   "bin": {