@hobble-env/cli 3.3.0 → 3.3.2

package/README.md

@@ -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:

package/SKILL.md

@@ -57,9 +57,19 @@ Global options: `-v, --verbose` (debug output on stderr), `-V, --version`.
 | `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:
@@ -99,6 +109,8 @@ 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.
 

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.2.0")
+    .version("3.3.1")
     .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/set.js

@@ -3,13 +3,7 @@ import { api } from "../lib/api.js";
 import { resolveContext } from "../lib/project-config.js";
 import { resolveProjectId } from "./list.js";
 import { success, error } from "../lib/output.js";
-async function readStdin() {
-    const chunks = [];
-    for await (const chunk of process.stdin) {
-        chunks.push(chunk);
-    }
-    return Buffer.concat(chunks).toString("utf-8").trimEnd();
-}
+import { readStdin } from "../lib/stdin.js";
 export const setCommand = new Command("set")
     .description("Create or update a secret")
     .argument("<key>", "Secret key name")

package/dist/lib/api.d.ts

@@ -1,6 +1,13 @@
 export declare class ApiError extends Error {
     status: number;
-    constructor(status: number, message: string);
+    body?: unknown | undefined;
+    /**
+     * `body` is the parsed JSON error body (when the server sent one). The
+     * thrown `message` strings are unchanged — commands that need structured
+     * fields (e.g. the credentials multi-org 400's `candidates` array, or the
+     * zero-org 403's distinct `error` string) inspect `status` + `body`.
+     */
+    constructor(status: number, message: string, body?: unknown | undefined);
 }
 /**
  * Pin the instance URL for the rest of this process. Used by `hobble init

package/dist/lib/api.js

@@ -3,9 +3,17 @@ import { loadProjectConfig } from "./project-config.js";
 import { debug } from "./output.js";
 export class ApiError extends Error {
     status;
-    constructor(status, message) {
+    body;
+    /**
+     * `body` is the parsed JSON error body (when the server sent one). The
+     * thrown `message` strings are unchanged — commands that need structured
+     * fields (e.g. the credentials multi-org 400's `candidates` array, or the
+     * zero-org 403's distinct `error` string) inspect `status` + `body`.
+     */
+    constructor(status, message, body) {
         super(message);
         this.status = status;
+        this.body = body;
         this.name = "ApiError";
     }
 }
@@ -84,18 +92,22 @@ async function request(method, path, body) {
         throw new Error(`Could not reach the server at ${baseUrl}. Check your connection or run \`hobble login\` to update the URL.`);
     }
     debug(`${res.status} ${res.statusText}`);
-    if (res.status === 401) {
-        if (credentialType === "session") {
-            throw new ApiError(401, "Your session has expired. Run `hobble login` to sign in again.");
-        }
-        throw new ApiError(401, "API key is invalid or expired. Run `hobble login` to update.");
-    }
-    if (res.status === 403) {
-        throw new ApiError(403, "You don't have permission to perform this action.");
-    }
     if (!res.ok) {
+        // Parse the error body once, up front, so structured fields survive the
+        // canned-message short-circuits below (attached as ApiError.body).
         const data = await res.json().catch(() => ({}));
-        throw new ApiError(res.status, data.error ?? `Request failed with status ${res.status}`);
+        if (res.status === 401) {
+            if (credentialType === "session") {
+                throw new ApiError(401, "Your session has expired. Run `hobble login` to sign in again.", data);
+            }
+            throw new ApiError(401, "API key is invalid or expired. Run `hobble login` to update.", data);
+        }
+        if (res.status === 403) {
+            // Keep the canned message: the server's generic 403 body is just
+            // {"error":"Forbidden"} — preferring it would regress every command.
+            throw new ApiError(403, "You don't have permission to perform this action.", data);
+        }
+        throw new ApiError(res.status, data.error ?? `Request failed with status ${res.status}`, data);
     }
     if (res.status === 204)
         return {};

package/dist/lib/stdin.d.ts

@@ -0,0 +1,2 @@
+/** Read all of stdin as UTF-8, trimming the trailing newline. */
+export declare function readStdin(): Promise<string>;

package/dist/lib/stdin.js

@@ -0,0 +1,8 @@
+/** Read all of stdin as UTF-8, trimming the trailing newline. */
+export async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString("utf-8").trimEnd();
+}

package/package.json

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