@hobble-env/cli 3.3.15 → 3.4.0

package/SKILL.md

@@ -7,7 +7,7 @@ description: Use when a repository contains a `.hobble` file, references the hob
 
 > **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.3.13 — keep in sync with cli/bin/hobble.ts -->
+<!-- documented-version: 3.3.15 — keep in sync with cli/bin/hobble.ts -->
 
 ## Overview
 
@@ -37,7 +37,7 @@ In this repo, the CLI runs from source: `npm run hobble -- <command>` (or `npx t
 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. Keys whose value and comment already match the server are not listed or counted, so the update list is exactly what changes.
 
-## Command Surface (v3.3.13)
+## Command Surface (v3.3.15)
 
 Global options: `-v, --verbose` (debug output on stderr), `-V, --version`.
 
@@ -46,16 +46,16 @@ Global options: `-v, --verbose` (debug output on stderr), `-V, --version`.
 | `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. With no interactive terminal (`< /dev/null`, a piped CI step) the prompt cannot be answered: exits 1 with `Prompt cancelled (no interactive terminal).` |
 | `logout` | `--all` | Removes stored credentials for the effective instance only; other instances stay logged in. `--all` removes every credential. Its confirmation prompt has the same non-TTY behaviour as `login`: exits 1 with `Prompt cancelled (no interactive terminal).` |
 | `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>`. |
+| `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"`). Exits 1 on a non-TTY, but by two different paths: with no usable credential (and no `HOBBLE_API_KEY`) the sign-in gate refuses first, with `Not logged in to <url>` plus the advice to run `hobble login`; **with** a credential it passes that gate and then dies on the first project/env prompt, reporting whatever the prompt library raised. Either way: exit 1, reason on stderr. |
 | `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. |
+| `list` | `--project`, `--env`, `--json`, `--tag <name>` (repeatable) | Names + tags + dates, never values. `--tag` is an AND filter, case-insensitive; a `--tag` naming no tag known to the project warns `Unknown tag: <name>` on stderr and still exits 0 with an empty result (the check is skipped, silently, for a token that cannot read the project's tag list). Empty results print `No secrets found.` on stderr (nothing on stdout). |
 | `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, argv passed verbatim, no shell). 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 (values are bare when safe, otherwise dotenv-quoted). Refuses to overwrite without `--force`. Use sparingly (Rule 2). |
+| `env pull` | `--project`, `--env`, `--force`, `-o <path>` (default `.env`) | Writes plaintext secrets + comments to disk (values are bare when safe, otherwise dotenv-quoted). Refuses to overwrite without `--force`. The `# Generated by hobble from <project>/<env>` header carries no timestamp, so two pulls of identical data produce byte-identical files. 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`. A key counts as an update only when its value or its comment actually differs — a push straight after an untouched `env pull` reports `0 to create, 0 to update, 0 to delete` and `No changes to apply.` **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. |
@@ -77,7 +77,7 @@ 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.
+`--json` does not *redirect* the human-facing output — it **replaces** it. `hobble list --json` writes the JSON array to stdout and prints no table at all; `hobble list --json 1>/dev/null` is therefore silent. 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.
@@ -106,7 +106,7 @@ 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.
+- `list --json`: array of `{ id, key, comment, createdAt, updatedAt, tags: [{ id, name, color }] }` — no values (`comment` is `null` when unset).
 - `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.
@@ -138,8 +138,9 @@ project root is.
 - 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 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).
 - An environment-scoped API token works with `--project`/`--env`: it can resolve its environment's parent project by name and list that project's environments, but any read or write outside the scoped environment(s) fails with a permission error. A project name the credential is not scoped to reports `not found, or your credential is not scoped to it`.
+- `HOBBLE_ASSUME_TTY=1` makes the **sign-in gate** of `init` treat piped stdin as interactive, so it starts the device flow instead of raising `Not logged in`. It does nothing else: with a valid credential already stored the gate returns early, so setting it changes nothing, and it does not make the later project/env prompts survive a pipe. Test-harness escape hatch — do not use it to bypass Rule 5.
+- `HOBBLE_NO_OPEN=1` stops the browser-login flow from actually launching a browser. It does **not** skip the `Press Enter to open <url>…` prompt that precedes it — `hobble login --no-browser` is what skips the prompt and just prints the URL. Test-harness escape hatch.
 
 ## Common Mistakes
 

package/dist/bin/hobble.js

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

package/dist/commands/env-pull.js

@@ -28,9 +28,10 @@ export const envPullCommand = new Command("pull")
         const projectId = await resolveProjectId(ctx.project);
         // Fetch all secrets
         const listResponse = (await api.get(`/api/v1/secrets?projectId=${projectId}&environment=${encodeURIComponent(ctx.environment)}`));
+        // No timestamp: two pulls of identical data must produce byte-identical
+        // files, so a re-pull diffs as "no change".
         const header = [
             `# Generated by hobble from ${ctx.project}/${ctx.environment}`,
-            `# ${new Date().toISOString()}`,
         ];
         const blocks = [];
         for (const s of listResponse.data) {

package/dist/commands/list.js

@@ -1,7 +1,7 @@
 import { Command } from "commander";
 import { api } from "../lib/api.js";
 import { resolveContext } from "../lib/project-config.js";
-import { error, table } from "../lib/output.js";
+import { error, table, warn } from "../lib/output.js";
 async function resolveProjectId(projectName) {
     const data = (await api.get("/api/v1/projects"));
     const proj = data.projects.find((p) => p.name === projectName);
@@ -24,6 +24,23 @@ export const listCommand = new Command("list")
         const response = (await api.get(`/api/v1/secrets?projectId=${projectId}&environment=${encodeURIComponent(ctx.environment)}`));
         const secrets = response.data;
         const tagFilter = opts.tag ?? [];
+        if (tagFilter.length) {
+            // A typo'd --tag otherwise looks exactly like "no matches". Warn (on
+            // stderr) but keep the exit code at 0 — an empty filter result is not
+            // an error. The lookup is best-effort: an environment-scoped token can
+            // list secrets but is forbidden the project-addressed tags route, and
+            // that must not turn a working `list` into a failure.
+            const known = await api
+                .get(`/api/v1/tags?projectId=${projectId}`)
+                .then((r) => r.data.map((t) => t.name.toLowerCase()))
+                .catch(() => null);
+            if (known) {
+                for (const t of tagFilter) {
+                    if (!known.includes(t.toLowerCase()))
+                        warn(`Unknown tag: ${t}`);
+                }
+            }
+        }
         const filtered = tagFilter.length
             ? secrets.filter((s) => {
                 const names = (s.tags ?? []).map((t) => t.name.toLowerCase());
@@ -35,7 +52,9 @@ export const listCommand = new Command("list")
             return;
         }
         if (filtered.length === 0) {
-            console.log("No secrets found.");
+            // Human-facing, so stderr — stdout carries only data (the table this
+            // stands in for goes to stderr too).
+            process.stderr.write("No secrets found.\n");
             return;
         }
         table(["Key", "Tags", "Created", "Updated"], filtered.map((s) => [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hobble-env/cli",
-  "version": "3.3.15",
+  "version": "3.4.0",
   "description": "CLI for managing secrets via hobble",
   "type": "module",
   "repository": {