@hobble-env/cli 3.0.1

package/README.md

@@ -0,0 +1,148 @@
+# Hobble CLI
+
+A command-line tool for managing secrets stored in your secret management dashboard. Hobble lets you create, read, update, and delete secrets, and inject them into your development workflow as environment variables.
+
+## Installation
+
+Install globally from npm:
+
+```bash
+npm install -g @hobble-env/cli
+```
+
+This provides the `hobble` command.
+
+### From source
+
+From the project root:
+
+```bash
+cd cli && npm install
+```
+
+Run commands with:
+
+```bash
+npx tsx cli/bin/hobble.ts <command>
+```
+
+Or use the shortcut from the root:
+
+```bash
+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
+
+```bash
+hobble login
+```
+
+You'll be prompted for your API key and the dashboard URL (defaults to `http://localhost:3000`).
+
+### 3. Initialize a Project
+
+```bash
+hobble init
+```
+
+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:
+
+```bash
+hobble switch my-project/staging
+```
+
+## Commands
+
+### Secrets
+
+```bash
+hobble list                    # List all secrets (names only, no values)
+hobble list --json             # List as JSON
+
+hobble get DB_HOST             # Print a secret's decrypted value
+hobble get DB_HOST --json      # Output as JSON
+
+hobble set DB_HOST localhost   # Create or update a secret
+echo "s3cr3t" | hobble set DB_PASS -   # Set from stdin (avoids shell history)
+
+hobble delete DB_HOST          # Delete a secret (with confirmation)
+hobble delete DB_HOST -y       # Skip confirmation
+```
+
+### Running Commands with Secrets
+
+Fetch secrets from the dashboard and inject them as environment variables into a subprocess:
+
+```bash
+hobble run npm run dev
+hobble run -- node server.js --port 8080
+```
+
+Secrets are injected in-memory only -- nothing is written to disk.
+
+### Starting a Subshell with Secrets
+
+Start an interactive subshell with the current project/environment's secrets injected as environment variables. Exit the subshell (type `exit` or Ctrl+D) to return to your original shell with its original environment intact.
+
+```bash
+# In a directory with a .hobble file
+hobble shell
+
+# Or specify project/env explicitly
+hobble shell --project my-app --env production
+```
+
+Inside the subshell, three extra env vars are set so scripts can detect the context:
+
+- `HOBBLE_PROJECT` — project name
+- `HOBBLE_ENVIRONMENT` — environment name
+- `HOBBLE_SHELL` — `<project>/<environment>`
+
+For bash and zsh, your prompt is prefixed with `(hobble:<project>/<environment>)` as a visual reminder. Other shells keep their default prompt; use `$HOBBLE_SHELL` to build your own prompt indicator if desired.
+
+### Managing .env Files
+
+```bash
+hobble env pull                # Write secrets to .env
+hobble env pull --force        # Overwrite existing .env
+hobble env pull -o .env.local  # Write to a custom path
+
+hobble env push                # Push .env contents to the dashboard
+hobble env push -y             # Skip confirmation
+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
+```
+
+## Configuration
+
+### Global Config
+
+Stored at `~/.config/hobble/config.json` after `hobble login`. Contains your API key and dashboard URL.
+
+Override with environment variables:
+
+- `HOBBLE_API_KEY` -- override the stored API key
+- `HOBBLE_API_URL` -- override the stored dashboard 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.
+
+Override per-command with flags:
+
+```bash
+hobble list --project my-app --env production
+```

package/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: using-hobble-cli
+description: Use when a repository contains a `.hobble` file, references the hobble CLI in scripts/docs, or you need to run or test code that depends on secrets managed by a hobble dashboard
+---
+
+# Using the hobble CLI
+
+## 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`.
+
+## 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": "..." }`.
+- `.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.
+
+## 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.
+2. **Prefer `hobble run -- <cmd>` over `hobble env pull`.** `run` injects secrets into a single subprocess in memory. `pull` writes plaintext to disk and must be cleaned up. Only pull when a tool literally cannot read env vars.
+3. **Never pass secret values as CLI arguments.** They leak into shell history and `ps` output. Use stdin:
+   ```bash
+   printf '%s' "$value" | hobble set DB_PASS -
+   ```
+4. **Never print, paste, or log the output of `hobble get`.** Do not echo it into chat, a commit message, or a log file. If you must move a value, pipe it directly to the destination.
+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` |
+
+All data commands accept `--project <name> --env <name>` to override `.hobble` for a single invocation. Prefer flags over `hobble switch` for one-off reads.
+
+## Context Resolution
+
+Each data command needs a `project` and `environment`, resolved in order:
+1. `--project` / `--env` flags on the command
+2. `.hobble` in the current working directory
+3. Error: `No project configured. Run \`hobble init\` or pass \`--project\` and \`--env\`.`
+
+If you hit that error, stop and ask the user. Do not run `hobble init` on their behalf — it is interactive and binds the directory to a project.
+
+## Authentication
+
+- Stored config: `~/.config/hobble/config.json` (written by `hobble login`).
+- 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.
+
+## Common Mistakes
+
+| Mistake | Correct approach |
+|---------|------------------|
+| `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 |
+| `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 |
+
+## Running Tests That Need Secrets
+
+Prefer:
+```bash
+hobble run -- npm test
+```
+
+Avoid the pull-then-test pattern — it leaves a plaintext `.env` behind if the test fails:
+```bash
+# anti-pattern
+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`.

package/dist/bin/hobble.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/hobble.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { setVerbose } from "../lib/output.js";
+import { loginCommand } from "../commands/login.js";
+import { logoutCommand } from "../commands/logout.js";
+import { whoamiCommand } from "../commands/whoami.js";
+import { initCommand } from "../commands/init.js";
+import { switchCommand } from "../commands/switch.js";
+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 { deleteCommand } from "../commands/delete.js";
+import { runCommand } from "../commands/run.js";
+import { shellCommand } from "../commands/shell.js";
+import { envPullCommand } from "../commands/env-pull.js";
+import { envPushCommand } from "../commands/env-push.js";
+const program = new Command();
+program
+    .name("hobble")
+    .description("CLI for managing secrets via the secret-management-dash API")
+    .version("3.0.0")
+    .enablePositionalOptions()
+    .option("-v, --verbose", "Show debug output for troubleshooting");
+program.hook("preAction", (thisCommand) => {
+    const opts = thisCommand.optsWithGlobals();
+    if (opts.verbose)
+        setVerbose(true);
+});
+program.addCommand(loginCommand);
+program.addCommand(logoutCommand);
+program.addCommand(whoamiCommand);
+program.addCommand(initCommand);
+program.addCommand(switchCommand);
+program.addCommand(listCommand);
+program.addCommand(getCommand);
+program.addCommand(setCommand);
+program.addCommand(tagsCommand);
+program.addCommand(deleteCommand);
+program.addCommand(runCommand);
+program.addCommand(shellCommand);
+const envCommand = new Command("env").description("Manage .env files");
+envCommand.addCommand(envPullCommand);
+envCommand.addCommand(envPushCommand);
+program.addCommand(envCommand);
+program.parse();

package/dist/commands/delete.d.ts

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

package/dist/commands/delete.js

@@ -0,0 +1,43 @@
+import { Command } from "commander";
+import inquirer from "inquirer";
+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";
+export const deleteCommand = new Command("delete")
+    .description("Delete a secret")
+    .argument("<key>", "Secret key name")
+    .option("--project <name>", "Project name")
+    .option("--env <name>", "Environment name")
+    .option("-y, --yes", "Skip confirmation")
+    .action(async (key, opts) => {
+    try {
+        const ctx = await resolveContext(opts);
+        const projectId = await resolveProjectId(ctx.project);
+        // Find the secret by key name
+        const listResponse = (await api.get(`/api/v1/secrets?projectId=${projectId}&environment=${encodeURIComponent(ctx.environment)}`));
+        const match = listResponse.data.find((s) => s.key === key);
+        if (!match) {
+            error(`Secret "${key}" not found.`);
+            process.exit(1);
+        }
+        if (!opts.yes) {
+            const { confirm } = await inquirer.prompt([
+                {
+                    type: "confirm",
+                    name: "confirm",
+                    message: `Delete secret "${key}"?`,
+                    default: false,
+                },
+            ]);
+            if (!confirm)
+                return;
+        }
+        await api.delete(`/api/v1/secrets/${match.id}`);
+        success(`Deleted "${key}"`);
+    }
+    catch (err) {
+        error(err.message);
+        process.exit(1);
+    }
+});

package/dist/commands/env-pull.d.ts

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

package/dist/commands/env-pull.js

@@ -0,0 +1,56 @@
+import { Command } from "commander";
+import { writeFile, access } from "node:fs/promises";
+import { api } from "../lib/api.js";
+import { resolveContext } from "../lib/project-config.js";
+import { resolveProjectId } from "./list.js";
+import { success, warn, error } from "../lib/output.js";
+import { formatEnvComment } from "../lib/env-format.js";
+export const envPullCommand = new Command("pull")
+    .description("Write secrets to a .env file")
+    .option("--project <name>", "Project name")
+    .option("--env <name>", "Environment name")
+    .option("--force", "Overwrite existing .env file")
+    .option("-o, --output <path>", "Output file path", ".env")
+    .action(async (opts) => {
+    try {
+        // Check if .env already exists
+        if (!opts.force) {
+            try {
+                await access(opts.output);
+                error(`${opts.output} already exists. Use --force to overwrite.`);
+                process.exit(1);
+            }
+            catch {
+                // File doesn't exist, good
+            }
+        }
+        const ctx = await resolveContext(opts);
+        const projectId = await resolveProjectId(ctx.project);
+        // Fetch all secrets
+        const listResponse = (await api.get(`/api/v1/secrets?projectId=${projectId}&environment=${encodeURIComponent(ctx.environment)}`));
+        const header = [
+            `# Generated by hobble from ${ctx.project}/${ctx.environment}`,
+            `# ${new Date().toISOString()}`,
+        ];
+        const blocks = [];
+        for (const s of listResponse.data) {
+            const detailResponse = (await api.get(`/api/v1/secrets/${s.id}`));
+            const detail = detailResponse.data;
+            // Quote values that contain spaces or special characters
+            const needsQuotes = /[\s#=]/.test(detail.value);
+            const assignment = needsQuotes
+                ? `${detail.key}="${detail.value}"`
+                : `${detail.key}=${detail.value}`;
+            const block = [...formatEnvComment(detail.comment), assignment];
+            blocks.push(block.join("\n"));
+        }
+        const body = [header.join("\n"), ...blocks].join("\n\n");
+        await writeFile(opts.output, body + "\n", "utf-8");
+        success(`Wrote ${listResponse.data.length} secrets to ${opts.output}`);
+        warn("Make sure this file is in your .gitignore!");
+    }
+    catch (err) {
+        error(err.message);
+        process.exit(1);
+    }
+});

package/dist/commands/env-push.d.ts

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

package/dist/commands/env-push.js

@@ -0,0 +1,135 @@
+import { Command } from "commander";
+import { readFile } from "node:fs/promises";
+import { parse } from "dotenv";
+import inquirer from "inquirer";
+import { api } from "../lib/api.js";
+import { resolveContext } from "../lib/project-config.js";
+import { resolveProjectId } from "./list.js";
+import { success, info, error } from "../lib/output.js";
+const HOBBLE_BANNER = /^# Generated by hobble\b/;
+/**
+ * Walk the raw .env source and associate each contiguous run of `# ...` lines
+ * (separated by no blank lines) with the next KEY=VALUE assignment. The banner
+ * comments emitted by `hobble pull` are stripped so they don't get re-pushed.
+ */
+function extractComments(raw) {
+    const lines = raw.split(/\r?\n/);
+    const buffer = [];
+    const result = {};
+    for (const rawLine of lines) {
+        const line = rawLine.trim();
+        if (line.startsWith("#")) {
+            if (HOBBLE_BANNER.test(line)) {
+                buffer.length = 0;
+                continue;
+            }
+            // strip leading "#" and a single optional space
+            buffer.push(line.replace(/^#\s?/, ""));
+            continue;
+        }
+        if (line === "") {
+            buffer.length = 0;
+            continue;
+        }
+        const match = line.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+        if (match && buffer.length > 0) {
+            result[match[1]] = buffer.join("\n");
+        }
+        buffer.length = 0;
+    }
+    return result;
+}
+export const envPushCommand = new Command("push")
+    .description("Push a .env file to the API")
+    .option("--project <name>", "Project name")
+    .option("--env <name>", "Environment name")
+    .option("-y, --yes", "Skip confirmation")
+    .option("-i, --input <path>", "Input file path", ".env")
+    .action(async (opts) => {
+    try {
+        const raw = await readFile(opts.input, "utf-8").catch(() => {
+            error(`File not found: ${opts.input}`);
+            process.exit(1);
+        });
+        const rawText = raw;
+        const parsed = parse(rawText);
+        const comments = extractComments(rawText);
+        const allKeys = Object.keys(parsed);
+        if (allKeys.length === 0) {
+            info("No secrets found in .env file.");
+            return;
+        }
+        const keysWithValues = allKeys.filter((k) => parsed[k] !== "");
+        const emptyKeys = allKeys.filter((k) => parsed[k] === "");
+        const ctx = await resolveContext(opts);
+        const projectId = await resolveProjectId(ctx.project);
+        // Fetch existing secrets to diff
+        const listResponse = (await api.get(`/api/v1/secrets?projectId=${projectId}&environment=${encodeURIComponent(ctx.environment)}`));
+        const existingByKey = new Map(listResponse.data.map((s) => [s.key, s]));
+        const toCreate = keysWithValues.filter((k) => !existingByKey.has(k));
+        const toUpdate = keysWithValues.filter((k) => existingByKey.has(k));
+        const toDelete = emptyKeys.filter((k) => existingByKey.has(k));
+        info(`${toCreate.length} to create, ${toUpdate.length} to update, ${toDelete.length} to delete`);
+        if (toCreate.length > 0) {
+            info(`Create: ${toCreate.join(", ")}`);
+        }
+        if (toUpdate.length > 0) {
+            info(`Update: ${toUpdate.join(", ")}`);
+        }
+        if (toDelete.length > 0) {
+            info(`Delete: ${toDelete.join(", ")}`);
+        }
+        if (toCreate.length === 0 && toUpdate.length === 0 && toDelete.length === 0) {
+            info("No changes to apply.");
+            return;
+        }
+        if (!opts.yes) {
+            const { confirm } = await inquirer.prompt([
+                {
+                    type: "confirm",
+                    name: "confirm",
+                    message: "Apply these changes?",
+                    default: false,
+                },
+            ]);
+            if (!confirm)
+                return;
+        }
+        // Apply changes
+        for (const key of toCreate) {
+            const body = {
+                projectId,
+                environment: ctx.environment,
+                key,
+                value: parsed[key],
+            };
+            if (comments[key] !== undefined)
+                body.comment = comments[key];
+            await api.post("/api/v1/secrets", body);
+        }
+        for (const key of toUpdate) {
+            const existing = existingByKey.get(key);
+            const incoming = comments[key];
+            const body = {
+                value: parsed[key],
+            };
+            // Only send comment when the file changes it. This prevents push from
+            // wiping a server-side comment when the user authored a .env without
+            // including comment lines.
+            if (incoming !== undefined && incoming !== (existing.comment ?? "")) {
+                body.comment = incoming;
+            }
+            await api.put(`/api/v1/secrets/${existing.id}`, body);
+        }
+        for (const key of toDelete) {
+            const existing = existingByKey.get(key);
+            await api.delete(`/api/v1/secrets/${existing.id}`);
+        }
+        const total = toCreate.length + toUpdate.length + toDelete.length;
+        success(`Pushed ${total} changes to ${ctx.project}/${ctx.environment}`);
+    }
+    catch (err) {
+        error(err.message);
+        process.exit(1);
+    }
+});

package/dist/commands/get.d.ts

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

package/dist/commands/get.js

@@ -0,0 +1,43 @@
+import { Command } from "commander";
+import { api } from "../lib/api.js";
+import { resolveContext } from "../lib/project-config.js";
+import { resolveProjectId } from "./list.js";
+import { error, isTTY } from "../lib/output.js";
+export const getCommand = new Command("get")
+    .description("Get a decrypted secret value")
+    .argument("<key>", "Secret key name")
+    .option("--project <name>", "Project name")
+    .option("--env <name>", "Environment name")
+    .option("--json", "Output as JSON")
+    .action(async (key, opts) => {
+    try {
+        const ctx = await resolveContext(opts);
+        const projectId = await resolveProjectId(ctx.project);
+        // Find the secret by key name
+        const listResponse = (await api.get(`/api/v1/secrets?projectId=${projectId}&environment=${encodeURIComponent(ctx.environment)}`));
+        const match = listResponse.data.find((s) => s.key === key);
+        if (!match) {
+            error(`Secret "${key}" not found.`);
+            process.exit(1);
+        }
+        // Fetch decrypted value
+        const secretResponse = (await api.get(`/api/v1/secrets/${match.id}`));
+        const secret = secretResponse.data;
+        if (opts.json) {
+            process.stdout.write(JSON.stringify({ key: secret.key, value: secret.value, tags: (secret.tags ?? []).map((t) => t.name) }, null, 2) + "\n");
+            return;
+        }
+        if (isTTY()) {
+            console.log(`${secret.key}=${secret.value}`);
+            if (secret.tags && secret.tags.length)
+                console.log(`# tags: ${secret.tags.map((t) => t.name).join(", ")}`);
+        }
+        else {
+            process.stdout.write(secret.value);
+        }
+    }
+    catch (err) {
+        error(err.message);
+        process.exit(1);
+    }
+});

package/dist/commands/init.d.ts

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

package/dist/commands/init.js

@@ -0,0 +1,70 @@
+import { Command } from "commander";
+import inquirer from "inquirer";
+import { api } from "../lib/api.js";
+import { 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 () => {
+    try {
+        // Fetch projects
+        const projectData = (await api.get("/api/v1/projects"));
+        if (projectData.projects.length === 0) {
+            error("No projects found. Create one in the dashboard first.");
+            process.exit(1);
+        }
+        const { projectId } = await inquirer.prompt([
+            {
+                type: "list",
+                name: "projectId",
+                message: "Select a project:",
+                choices: projectData.projects.map((p) => ({
+                    name: p.name,
+                    value: p.id,
+                })),
+            },
+        ]);
+        const selectedProject = projectData.projects.find((p) => p.id === projectId);
+        // Fetch environments
+        const envData = (await api.get(`/api/v1/projects/${projectId}/environments`));
+        if (envData.environments.length === 0) {
+            error("No environments found. Create one in the dashboard first.");
+            process.exit(1);
+        }
+        const { envName } = await inquirer.prompt([
+            {
+                type: "list",
+                name: "envName",
+                message: "Select an environment:",
+                choices: envData.environments.map((e) => ({
+                    name: e.name,
+                    value: e.name,
+                })),
+            },
+        ]);
+        await saveProjectConfig({
+            project: selectedProject.name,
+            environment: envName,
+        });
+        // Offer to add .hobble to .gitignore — but only if it's not already there
+        const alreadyIgnored = await isHobbleInGitignore();
+        if (!alreadyIgnored) {
+            const { addGitignore } = await inquirer.prompt([
+                {
+                    type: "confirm",
+                    name: "addGitignore",
+                    message: "Add .hobble to .gitignore?",
+                    default: true,
+                },
+            ]);
+            if (addGitignore) {
+                await addToGitignore();
+            }
+        }
+        success(`Configured: ${selectedProject.name}/${envName}`);
+    }
+    catch (err) {
+        error(err.message);
+        process.exit(1);
+    }
+});

package/dist/commands/list.d.ts

@@ -0,0 +1,4 @@
+import { Command } from "commander";
+declare function resolveProjectId(projectName: string): Promise<string>;
+export { resolveProjectId };
+export declare const listCommand: Command;