@hobble-env/cli 3.1.0 → 3.3.1

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
@@ -76,6 +76,50 @@ hobble delete DB_HOST          # Delete a secret (with confirmation)
 hobble delete DB_HOST -y       # Skip confirmation
 ```
 
+### Credentials (org-scoped)
+
+Credentials are org-scoped shared logins and API secrets, distinct from the
+per-environment secrets above. Note the noun: `hobble get DB_HOST` reads an
+**environment secret**, while `hobble secret get stripe` (alias of
+`hobble credential get stripe`) reads an **org credential**.
+
+```bash
+hobble credential list               # List credentials (no values)
+hobble secret list --json            # Same, via the alias, as JSON (includes tags)
+
+hobble secret get stripe             # Print a credential's decrypted value
+hobble secret get stripe --field username   # Print the username instead
+hobble secret get stripe --json      # Full object (name, username, url, value, tags)
+
+hobble secret set stripe sk_live_123 --username ops@acme.com --url https://stripe.com
+echo "sk_live_123" | hobble secret set stripe -    # Value from stdin
+hobble secret set stripe sk_test_9 --tag billing --tag prod   # Attach org tags
+
+hobble secret delete stripe
+```
+
+Credential names are case-insensitive and unique **per organization** — no
+`--project`/`--env` needed, but the CLI must know which org you mean:
+
+- If your login/API key reaches exactly **one** org, it is used automatically.
+- If it reaches **several** orgs, commands fail with an "ambiguous across
+  organizations" error listing the candidates — pass `--org <slug|id>`
+  (either the org slug or its id works):
+
+  ```bash
+  hobble secret get stripe --org acme-prod
+  ```
+
+- A project/env-only scoped API token has **no** org-scoped credential
+  access and gets a clear error — create an org-scoped token instead.
+
+CI usage: when stdout is not a TTY the value is printed raw (no decoration,
+no trailing newline), so command substitution is clean:
+
+```bash
+export STRIPE_KEY=$(hobble secret get stripe --field value)
+```
+
 ### Running Commands with Secrets
 
 Fetch secrets from the dashboard and inject them as environment variables into a subprocess:
@@ -122,24 +166,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,83 @@ 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. |
+| `credential list` | `--org <slug\|id>`, `--json` | Org-scoped credentials (alias: `secret list`). Names/usernames/URLs, never values. |
+| `credential get <name>` | `--org`, `--field <value\|username\|url>`, `--json` | Decrypted credential (alias: `secret get`). Name match is case-insensitive. Non-TTY output is the raw field value only. |
+| `credential set <name> [value\|-]` | `--org`, `--username`, `--url`, `--comment <text>`, `--tag <name>` (repeatable) | Create-or-update (alias: `secret set`). `-` or omitted value reads stdin. `--tag` **replaces** all existing tags. |
+| `credential delete <name>` | `--org` | Deletes by case-insensitive name (alias: `secret delete`). |
 
 All data commands accept `--project <name> --env <name>` to override `.hobble` for a single invocation. Prefer flags over `hobble switch` for one-off reads.
 
+## Credentials vs Environment Secrets
+
+`hobble get KEY` reads a **per-environment secret** (project/env-scoped, used as ENV vars). `hobble secret get NAME` — alias of `hobble credential get NAME` — reads an **org-scoped credential** (shared logins/API details, not bound to any environment). Do not confuse the two nouns.
+
+Credential names are case-insensitive and unique per organization. Credential commands take no `--project`/`--env`; when the login/API key reaches more than one org, pass `--org <slug|id>` (an ambiguity error lists the candidate orgs). Project/env-only scoped tokens cannot access credentials — an org-scoped token is required. In CI, non-TTY output of `hobble secret get` is the raw value only: `export STRIPE_KEY=$(hobble secret get stripe)`.
+
+## 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 }`.
+- `credential list --json`: array of `{ id, name, username, url, comment, createdAt, updatedAt, tags: [{ id, name, color }] }` — no values.
+- `credential get --json`: `{ name, username, url, value, comment, tags: [name, ...] }`.
+
+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 +125,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 +137,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 +161,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

@@ -10,6 +10,7 @@ import { listCommand } from "../commands/list.js";
 import { getCommand } from "../commands/get.js";
 import { setCommand } from "../commands/set.js";
 import { tagsCommand } from "../commands/tags.js";
+import { credentialCommand } from "../commands/credential.js";
 import { deleteCommand } from "../commands/delete.js";
 import { runCommand } from "../commands/run.js";
 import { shellCommand } from "../commands/shell.js";
@@ -19,7 +20,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.3.0")
     .enablePositionalOptions()
     .option("-v, --verbose", "Show debug output for troubleshooting");
 program.hook("preAction", (thisCommand) => {
@@ -36,6 +37,7 @@ program.addCommand(listCommand);
 program.addCommand(getCommand);
 program.addCommand(setCommand);
 program.addCommand(tagsCommand);
+program.addCommand(credentialCommand);
 program.addCommand(deleteCommand);
 program.addCommand(runCommand);
 program.addCommand(shellCommand);

package/dist/commands/credential.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const credentialCommand: Command;

package/dist/commands/credential.js

@@ -0,0 +1,199 @@
+import { Command } from "commander";
+import { api, ApiError } from "../lib/api.js";
+import { success, error, isTTY, table } from "../lib/output.js";
+import { readStdin } from "../lib/stdin.js";
+/**
+ * Render credential-specific API errors:
+ *  - multi-org 400 → list the candidate orgs (`name (slug)`, id fallback when
+ *    slug is null) and point at --org;
+ *  - zero-org 403 → surface the server's distinct "no org-scoped credential
+ *    access" message (NOT an ambiguity prompt); falls back to the canned 403
+ *    message when the body is absent (older server).
+ */
+function renderCredentialError(err) {
+    if (err instanceof ApiError) {
+        const body = (err.body ?? {});
+        if (err.status === 400 && Array.isArray(body.candidates) && body.candidates.length > 0) {
+            const list = body.candidates
+                .map((c) => `${c.name} (${c.slug ?? c.id})`)
+                .join(", ");
+            return `Credential names are ambiguous across organizations — pass --org <slug|id>. Candidates: ${list}`;
+        }
+        if (err.status === 403 &&
+            typeof body.error === "string" &&
+            body.error.includes("no org-scoped credential access")) {
+            return body.error;
+        }
+    }
+    return err.message;
+}
+function orgQuery(org) {
+    return org ? `?org=${encodeURIComponent(org)}` : "";
+}
+async function listCredentials(org) {
+    const res = (await api.get(`/api/v1/credentials${orgQuery(org)}`));
+    return res.data;
+}
+/**
+ * Case-INSENSITIVE name match — `credential_org_name_unique` is a per-org
+ * lower(name) index, so at most one credential matches per org and `STRIPE`
+ * must find `stripe`. (Deliberately not the exact `===` match the env-secret
+ * `get` uses; env keys are exact-case ENV names, credential names are not.)
+ */
+function findByName(items, name) {
+    const lower = name.toLowerCase();
+    return items.find((c) => c.name.toLowerCase() === lower);
+}
+const listSubcommand = new Command("list")
+    .description("List credentials in the organization")
+    .option("--org <slugOrId>", "Organization (slug or id) when more than one is reachable")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+    try {
+        const credentials = await listCredentials(opts.org);
+        if (opts.json) {
+            process.stdout.write(JSON.stringify(credentials, null, 2) + "\n");
+            return;
+        }
+        if (credentials.length === 0) {
+            console.log("No credentials found.");
+            return;
+        }
+        table(["Name", "Username", "URL", "Updated"], credentials.map((c) => [
+            c.name,
+            c.username ?? "",
+            c.url ?? "",
+            new Date(c.updatedAt).toLocaleDateString(),
+        ]));
+    }
+    catch (err) {
+        error(renderCredentialError(err));
+        process.exit(1);
+    }
+});
+const getSubcommand = new Command("get")
+    .description("Get a decrypted credential value")
+    .argument("<name>", "Credential name (case-insensitive)")
+    .option("--org <slugOrId>", "Organization (slug or id) when more than one is reachable")
+    .option("--field <field>", "Field to output: value, username, or url", "value")
+    .option("--json", "Output the full credential as JSON")
+    .action(async (name, opts) => {
+    try {
+        const field = opts.field;
+        if (!["value", "username", "url"].includes(field)) {
+            error(`Invalid --field "${field}". Must be value, username, or url.`);
+            process.exit(1);
+        }
+        const match = findByName(await listCredentials(opts.org), name);
+        if (!match) {
+            error(`Credential "${name}" not found.`);
+            process.exit(1);
+        }
+        const res = (await api.get(`/api/v1/credentials/${match.id}`));
+        const cred = res.data;
+        if (opts.json) {
+            process.stdout.write(JSON.stringify({
+                name: cred.name,
+                username: cred.username,
+                url: cred.url,
+                value: cred.value,
+                comment: cred.comment,
+                tags: (cred.tags ?? []).map((t) => t.name),
+            }, null, 2) + "\n");
+            return;
+        }
+        const selected = field === "value" ? cred.value : field === "username" ? cred.username : cred.url;
+        if (selected == null) {
+            error(`Credential "${cred.name}" has no ${field}.`);
+            process.exit(1);
+        }
+        if (isTTY()) {
+            const label = field === "value" ? cred.name : `${cred.name}.${field}`;
+            console.log(`${label}=${selected}`);
+        }
+        else {
+            // CI-safe: raw value only, no decoration, no trailing newline — so
+            // `$(hobble secret get NAME)` substitutes cleanly.
+            process.stdout.write(selected);
+        }
+    }
+    catch (err) {
+        error(renderCredentialError(err));
+        process.exit(1);
+    }
+});
+const setSubcommand = new Command("set")
+    .description("Create or update a credential")
+    .argument("<name>", "Credential name (case-insensitive)")
+    .argument("[value]", "Credential value (use - to read from stdin)")
+    .option("--org <slugOrId>", "Organization (slug or id) when more than one is reachable")
+    .option("--username <username>", "Login/identifier for this credential")
+    .option("--url <url>", "Related URL")
+    .option("--comment <text>", "Comment (use empty string to clear)")
+    .option("--tag <name>", "Tag to attach (repeatable; replaces existing tags)", (val, prev) => prev.concat(val), [])
+    .action(async (name, rawValue, opts) => {
+    try {
+        let value;
+        if (rawValue === "-" || rawValue === undefined) {
+            value = await readStdin();
+        }
+        else {
+            value = rawValue;
+        }
+        // The same single-org resolution gates create-vs-update: the list call
+        // below 400s on multi-org callers without --org, so a write can never
+        // target an arbitrarily-chosen org.
+        const existing = findByName(await listCredentials(opts.org), name);
+        const tags = opts.tag && opts.tag.length ? opts.tag : undefined;
+        const fields = { value };
+        if (opts.username !== undefined)
+            fields.username = opts.username;
+        if (opts.url !== undefined)
+            fields.url = opts.url;
+        if (opts.comment !== undefined)
+            fields.comment = opts.comment;
+        if (tags)
+            fields.tags = tags;
+        if (existing) {
+            await api.put(`/api/v1/credentials/${existing.id}`, fields);
+            success(`Updated "${existing.name}"`);
+        }
+        else {
+            await api.post(`/api/v1/credentials${orgQuery(opts.org)}`, {
+                name,
+                ...fields,
+            });
+            success(`Created "${name}"`);
+        }
+    }
+    catch (err) {
+        error(renderCredentialError(err));
+        process.exit(1);
+    }
+});
+const deleteSubcommand = new Command("delete")
+    .description("Delete a credential")
+    .argument("<name>", "Credential name (case-insensitive)")
+    .option("--org <slugOrId>", "Organization (slug or id) when more than one is reachable")
+    .action(async (name, opts) => {
+    try {
+        const match = findByName(await listCredentials(opts.org), name);
+        if (!match) {
+            error(`Credential "${name}" not found.`);
+            process.exit(1);
+        }
+        await api.delete(`/api/v1/credentials/${match.id}`);
+        success(`Deleted "${match.name}"`);
+    }
+    catch (err) {
+        error(renderCredentialError(err));
+        process.exit(1);
+    }
+});
+export const credentialCommand = new Command("credential")
+    .alias("secret")
+    .description("Manage org-scoped credentials (shared logins/API secrets — distinct from per-environment secrets)")
+    .addCommand(listSubcommand)
+    .addCommand(getSubcommand)
+    .addCommand(setSubcommand)
+    .addCommand(deleteSubcommand);

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);