@seekrit/cli 0.29.0 → 0.31.0

package/dist/index.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 import { spawn, spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { z } from "zod";
 import { Command } from "commander";
 import { homedir, hostname, tmpdir, userInfo } from "node:os";
 import { dirname, join, parse } from "node:path";
 import { createInterface } from "node:readline";
 import { Writable } from "node:stream";
+import { createHash } from "node:crypto";
 /** All catalog keys as a runtime array (for iteration / zod enums). */
 const ENTITLEMENT_KEYS = Object.keys({
 	"feature.kms": {
@@ -210,34 +211,127 @@ function parseBranchTtl(input) {
 //#endregion
 //#region ../../packages/core/src/dotenv.ts
 /**
-* Minimal `.env` parser: `KEY=VALUE`, `#` comments, an optional `export`
-* prefix, and single/double-quoted values (double quotes honor `\n \t \r \" \\`
-* escapes; unquoted values drop trailing ` # comments`). Multiline values are
-* not supported — keep those in seekrit itself.
+* `.env` parsing and serialization — the canonical definition of what a `.env`
+* file means to seekrit. `apps/run/src/dotenv.rs` is a faithful port of the
+* parser; the two must be changed together.
+*
+* Supported: `KEY=VALUE`, `#` comments, an optional `export` prefix, and
+* single/double-quoted values. A quoted value may span lines — it runs to its
+* closing quote, wherever that lands — which is what makes a pretty-printed
+* JSON credential (a Google service-account key, say) storable in a `.env`
+* file. Single quotes are literal; double quotes honor `\n \r \t \" \\`.
+* Unquoted values are single-line and drop a trailing ` # comment`.
+*
+* {@link parseDotenv} and {@link dotenvQuote} are inverses: anything the
+* serializer emits parses back to the identical string, including values that
+* contain literal backslash escapes (`"private_key": "…\n…"` in a JSON blob).
+*/
+/** Values that can go on the line bare — no quoting needed to survive a parse. */
+function needsQuoting(value) {
+	return /[\s"'`$\\#]/.test(value) || value === "";
+}
+/**
+* Quote one value for a `.env` line so it parses back byte-for-byte.
+*
+* Single quotes are preferred whenever they are safe, because they are literal:
+* a JSON credential full of `\"` and `\n` escapes stays readable and survives
+* the round-trip untouched. Values containing a single quote (or a real
+* newline, which many other `.env` readers can't span) fall back to double
+* quotes with every escape written out.
+*/
+function dotenvQuote(value) {
+	if (!needsQuoting(value)) return value;
+	if (!value.includes("'") && !/[\n\r]/.test(value)) return `'${value}'`;
+	return `"${value.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"").replaceAll("\n", "\\n").replaceAll("\r", "\\r")}"`;
+}
+/**
+* Apply double-quote escapes in a single left-to-right pass.
+*
+* A pass per escape (`\n` → newline, then `\\` → `\`, …) is wrong: in `\\n` the
+* first pass matches the trailing `\n` and yields a real newline, corrupting
+* every literal backslash-n a JSON credential is made of. Scanning once means a
+* backslash consumes the character after it and can never be re-read.
+*/
+function unescapeDoubleQuoted(text) {
+	let out = "";
+	for (let i = 0; i < text.length; i++) {
+		if (text[i] !== "\\" || i === text.length - 1) {
+			out += text[i];
+			continue;
+		}
+		const next = text[++i];
+		if (next === "n") out += "\n";
+		else if (next === "r") out += "\r";
+		else if (next === "t") out += "	";
+		else if (next === "\"" || next === "\\") out += next;
+		else out += `\\${next}`;
+	}
+	return out;
+}
+/**
+* Find the index of the quote that closes a value opened at `start`.
+*
+* Inside double quotes a `\"` is an escaped quote, not the terminator (and a
+* `\\` immediately before the quote *is* a terminator, since the backslash is
+* itself escaped) — so the scan tracks escapes rather than searching for the
+* next bare quote. Single quotes have no escapes: the next one closes. Returns
+* -1 when the value is never closed.
+*/
+function findClosingQuote(content, start, quote) {
+	for (let i = start; i < content.length; i++) {
+		if (quote === "\"" && content[i] === "\\") {
+			i++;
+			continue;
+		}
+		if (content[i] === quote) return i;
+	}
+	return -1;
+}
+/**
+* Parse `.env` text into variables. Later assignments win, matching the
+* object-assignment semantics every `.env` reader has.
 */
 function parseDotenv(content) {
 	const out = {};
-	for (const raw of content.split(/\r?\n/)) {
-		let line = raw.trim();
-		if (!line || line.startsWith("#")) continue;
-		if (line.startsWith("export ")) line = line.slice(7).trimStart();
-		const eq = line.indexOf("=");
-		if (eq === -1) continue;
-		const key = line.slice(0, eq).trim();
+	let cursor = 0;
+	while (cursor < content.length) {
+		const newline = content.indexOf("\n", cursor);
+		const lineEnd = newline === -1 ? content.length : newline;
+		const lineStart = cursor;
+		const trimmedEnd = lineEnd > lineStart && content[lineEnd - 1] === "\r" ? lineEnd - 1 : lineEnd;
+		cursor = lineEnd + 1;
+		let i = skipSpace(content, lineStart, trimmedEnd);
+		if (i === trimmedEnd || content[i] === "#") continue;
+		if (content.startsWith("export ", i)) i = skipSpace(content, i + 7, trimmedEnd);
+		const eq = content.indexOf("=", i);
+		if (eq === -1 || eq >= trimmedEnd) continue;
+		const key = content.slice(i, eq).trim();
 		if (!key) continue;
-		let value = line.slice(eq + 1).trim();
-		const quote = value[0];
-		if (value.length >= 2 && (quote === "\"" || quote === "'") && value.at(-1) === quote) {
-			value = value.slice(1, -1);
-			if (quote === "\"") value = value.replace(/\\n/g, "\n").replace(/\\r/g, "\r").replace(/\\t/g, "	").replace(/\\"/g, "\"").replace(/\\\\/g, "\\");
-		} else {
-			const comment = value.indexOf(" #");
-			if (comment !== -1) value = value.slice(0, comment).trim();
+		const valueStart = skipSpace(content, eq + 1, trimmedEnd);
+		const quote = content[valueStart];
+		if (valueStart === trimmedEnd || quote !== "\"" && quote !== "'") {
+			const rest = content.slice(valueStart, trimmedEnd).trimEnd();
+			const comment = rest.indexOf(" #");
+			out[key] = comment === -1 ? rest : rest.slice(0, comment).trimEnd();
+			continue;
+		}
+		const close = findClosingQuote(content, valueStart + 1, quote);
+		const valueEnd = close === -1 ? content.length : close;
+		const value = content.slice(valueStart + 1, valueEnd);
+		out[key] = quote === "\"" ? unescapeDoubleQuoted(value) : value;
+		if (valueEnd >= cursor) {
+			const after = content.indexOf("\n", valueEnd);
+			cursor = after === -1 ? content.length : after + 1;
 		}
-		out[key] = value;
 	}
 	return out;
 }
+/** First index at or after `from` (and before `end`) that isn't a space or tab. */
+function skipSpace(content, from, end) {
+	let i = from;
+	while (i < end && (content[i] === " " || content[i] === "	")) i++;
+	return i;
+}
 //#endregion
 //#region ../../packages/core/src/ids.ts
 const ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
@@ -402,6 +496,104 @@ function interpolateSecrets(values) {
 		unresolved: [...unresolved].sort()
 	};
 }
+//#endregion
+//#region ../../packages/core/src/json-value.ts
+/**
+* Whether a value is worth *offering* a JSON view for: an object or array.
+*
+* Deliberately narrow. A bare `123`, `true`, or `"quoted string"` is legal JSON
+* but is far more likely to be an ordinary secret that happens to look like a
+* literal, and badging those as JSON would be noise on almost every row.
+*/
+function looksLikeJson(value) {
+	const trimmed = value.trim();
+	return trimmed.startsWith("{") && trimmed.endsWith("}") || trimmed.startsWith("[") && trimmed.endsWith("]");
+}
+/** Strip one layer of matching surrounding quotes, if the value has them. */
+function unquote(value) {
+	const trimmed = value.trim();
+	const quote = trimmed[0];
+	if (trimmed.length < 2) return null;
+	if (quote !== "'" && quote !== "\"" || trimmed.at(-1) !== quote) return null;
+	return trimmed.slice(1, -1);
+}
+function isParseable(value) {
+	try {
+		JSON.parse(value);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* The two ways a copied credential usually arrives broken.
+*
+* Both come from a shell habit rather than a typo: the quotes that made the
+* value survive `.env` or a command line get pasted along with it, or a value
+* that was escaped for a double-quoted context is pasted still escaped.
+*/
+function findRepair(value) {
+	const inner = unquote(value);
+	if (inner !== null && looksLikeJson(inner) && isParseable(inner)) return {
+		label: "remove the quotes",
+		reason: "the surrounding quotes were pasted along with the value",
+		value: inner
+	};
+	if (value.includes("\\\"")) {
+		const unescaped = value.replaceAll("\\\"", "\"").replaceAll("\\\\", "\\");
+		const candidate = unquote(unescaped) ?? unescaped;
+		if (looksLikeJson(candidate) && isParseable(candidate)) return {
+			label: "unescape the quotes",
+			reason: "the value is still escaped for a shell or a double-quoted string",
+			value: candidate
+		};
+	}
+	return null;
+}
+/**
+* Classify a decrypted value as JSON, nearly-JSON, or ordinary text.
+*
+* Only object- and array-shaped values are considered (see
+* {@link looksLikeJson}), so an ordinary secret is never reported as malformed
+* JSON just because it starts with a brace-free string.
+*/
+function inspectJsonValue(value) {
+	if (!looksLikeJson(value)) {
+		const repair = findRepair(value);
+		return repair ? {
+			kind: "malformed",
+			error: repair.reason,
+			repair
+		} : { kind: "text" };
+	}
+	let data;
+	try {
+		data = JSON.parse(value);
+	} catch (err) {
+		return {
+			kind: "malformed",
+			error: err instanceof Error ? err.message : "not valid JSON",
+			repair: findRepair(value)
+		};
+	}
+	const pretty = JSON.stringify(data, null, 2);
+	return {
+		kind: "json",
+		pretty,
+		minified: JSON.stringify(data),
+		isPretty: value.trim() === pretty,
+		size: Array.isArray(data) ? data.length : Object.keys(data).length,
+		shape: Array.isArray(data) ? "array" : "object"
+	};
+}
+/**
+* Pretty-print a value if it is JSON, otherwise hand it back unchanged — for
+* output paths that want to be helpful without ever altering a non-JSON secret.
+*/
+function prettyJsonOrRaw(value) {
+	const inspection = inspectJsonValue(value);
+	return inspection.kind === "json" ? inspection.pretty : value;
+}
 z.enum([
 	"postgres",
 	"mysql",
@@ -2528,7 +2720,7 @@ function isCliSessionToken(value) {
 }
 //#endregion
 //#region package.json
-var version = "0.29.0";
+var version = "0.31.0";
 //#endregion
 //#region ../../packages/api-client/src/index.ts
 var SeekritApiError = class extends Error {
@@ -3215,7 +3407,8 @@ function tryBuildContext(dotenvVars = {}) {
 			auth,
 			client: CLI_CLIENT
 		}),
-		auth
+		auth,
+		apiUrl
 	};
 }
 function buildContext() {
@@ -4621,15 +4814,165 @@ function registerBranchCommands(program) {
 		console.error(`deleted branch ${app.slug}#${target.slug}`);
 	});
 }
-//#endregion
-//#region src/format.ts
-function needsQuoting(value) {
-	return /[\s"'`$\\#]/.test(value) || value === "";
+/** Domain separators — must match `crates/seekrit-cache`. */
+const KEY_DOMAIN = "seekrit-lkg-cache-v1";
+const TOKEN_DOMAIN = "seekrit-token-fp-v1";
+/** 24h: long enough to ride out an outage, short enough to bound the tail. */
+const DEFAULT_MAX_AGE_MS = 1440 * 60 * 1e3;
+/**
+* Derive the key for one resolve request. Overrides are sorted, so flag order
+* never splits the cache. Byte-for-byte identical to `CacheKey::new` in
+* `crates/seekrit-cache`.
+*/
+function cacheKey(apiUrl, token, branch, overrides = {}) {
+	const pairs = Object.entries(overrides).map(([group, env]) => `${group}:${env}`).sort();
+	return {
+		key: createHash("sha256").update([
+			KEY_DOMAIN,
+			apiUrl.replace(/\/+$/, ""),
+			token,
+			branch ?? "",
+			pairs.join(",")
+		].join("\n")).digest("hex"),
+		tokenFingerprint: tokenFingerprint(token)
+	};
 }
-function dotenvQuote(value) {
-	if (!needsQuoting(value)) return value;
-	return `"${value.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"").replaceAll("\n", "\\n")}"`;
+/** The hex SHA-256 identifying a token without storing it. */
+function tokenFingerprint(token) {
+	return createHash("sha256").update(`${TOKEN_DOMAIN}\n${token}`).digest("hex");
+}
+/**
+* `$XDG_CACHE_HOME/seekrit`, else `~/.cache/seekrit` — beside the config
+* directory holding the credential, never a shared temp directory.
+*/
+function defaultCacheDir() {
+	return join(process.env.XDG_CACHE_HOME || join(homedir(), ".cache"), "seekrit");
 }
+/** Render an age for a log line, rounded to its largest whole unit. */
+function humanize(ms) {
+	const secs = Math.floor(ms / 1e3);
+	if (secs < 60) return `${secs}s`;
+	if (secs < 3600) return `${Math.floor(secs / 60)}m`;
+	if (secs < 86400) return `${Math.floor(secs / 3600)}h`;
+	return `${Math.floor(secs / 86400)}d`;
+}
+/**
+* Whether a failed resolve means the API was *unreachable* (the cache may stand
+* in) rather than *refusing us* (it must not). A refusal is an answer, and
+* revocation is supposed to take effect the moment it arrives.
+*/
+function mayFallBack(err) {
+	if (err instanceof SeekritApiError) return err.status >= 500 || err.status === 429;
+	return true;
+}
+/** An opened cache, bound to one resolve request. */
+var LkgCache = class {
+	dir;
+	maxAgeMs;
+	id;
+	constructor(id, options = {}) {
+		this.id = id;
+		this.dir = options.dir ?? defaultCacheDir();
+		this.maxAgeMs = options.maxAgeMs ?? 864e5;
+	}
+	path() {
+		return join(this.dir, `${this.id.key}.json`);
+	}
+	read() {
+		const path = this.path();
+		if (!existsSync(path)) return { kind: "missing" };
+		let envelope;
+		try {
+			envelope = JSON.parse(readFileSync(path, "utf8"));
+		} catch (err) {
+			return {
+				kind: "unusable",
+				reason: `corrupt cache entry: ${message(err)}`
+			};
+		}
+		if (envelope.version !== 1) return {
+			kind: "unusable",
+			reason: `cache entry is format v${envelope.version}, this build reads v1`
+		};
+		if (envelope.tokenFingerprint !== this.id.tokenFingerprint) return {
+			kind: "unusable",
+			reason: "cache entry belongs to a different token"
+		};
+		if (typeof envelope.body !== "string") return {
+			kind: "unusable",
+			reason: "cache entry has no body"
+		};
+		const ageMs = Math.max(0, Date.now() - envelope.fetchedAt * 1e3);
+		if (ageMs >= this.maxAgeMs) return {
+			kind: "expired",
+			ageMs
+		};
+		return {
+			kind: "hit",
+			body: envelope.body,
+			ageMs
+		};
+	}
+	/**
+	* Record a freshly-fetched response. Written to a temporary file and renamed,
+	* so a concurrent reader sees either the old entry or the new one — never a
+	* half-written file. Throws only on genuinely unexpected I/O; callers treat a
+	* failed write as a warning, never as a failed resolve.
+	*/
+	write(body) {
+		mkdirSync(this.dir, {
+			recursive: true,
+			mode: 448
+		});
+		const envelope = {
+			version: 1,
+			fetchedAt: Math.floor(Date.now() / 1e3),
+			tokenFingerprint: this.id.tokenFingerprint,
+			body
+		};
+		const tmp = join(this.dir, `${this.id.key}.${process.pid}.tmp`);
+		try {
+			writeFileSync(tmp, JSON.stringify(envelope), { mode: 384 });
+			renameSync(tmp, this.path());
+		} catch (err) {
+			rmSync(tmp, { force: true });
+			throw err;
+		}
+		this.pruneExpired();
+	}
+	/** Drop this entry — used when the API refuses the token. */
+	invalidate() {
+		rmSync(this.path(), { force: true });
+	}
+	/**
+	* Delete entries past their usefulness (a rotated token or a changed
+	* `--with` leaves one nothing will read again). Best-effort and silent, and
+	* it only ever touches files this cache named: `<64 hex>.json`.
+	*/
+	pruneExpired() {
+		let names;
+		try {
+			names = readdirSync(this.dir);
+		} catch {
+			return;
+		}
+		for (const name of names) {
+			if (!/^[0-9a-f]{64}\.json$/.test(name)) continue;
+			const path = join(this.dir, name);
+			let expired = true;
+			try {
+				const envelope = JSON.parse(readFileSync(path, "utf8"));
+				expired = Math.max(0, Date.now() - envelope.fetchedAt * 1e3) >= this.maxAgeMs;
+			} catch {}
+			if (expired) rmSync(path, { force: true });
+		}
+	}
+};
+function message(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+//#endregion
+//#region src/format.ts
 function shellQuote(value) {
 	return `'${value.replaceAll("'", `'\\''`)}'`;
 }
@@ -5886,7 +6229,7 @@ async function materializeEnv(ctx, opts) {
 		if (!opts.envId) fail("specify --app and --env, or authenticate with a service token (SEEKRIT_TOKEN)");
 		query.env = opts.envId;
 	}
-	const { scope, layers } = await ctx.client.resolve(query);
+	const { scope, layers } = await resolveWithCache(ctx, query, opts.cache);
 	const privateKey = await getPrivateKey(ctx);
 	const values = {};
 	const provenance = {};
@@ -5910,6 +6253,46 @@ async function materializeEnv(ctx, opts) {
 	};
 }
 /**
+* Resolve, going through the last-known-good cache when one is configured.
+*
+* Always live first: the cache exists for when the call cannot land, not to
+* save a round trip, so a recovered network is picked up on the very next
+* invocation. A *refused* resolve (401/403/…) drops the entry rather than
+* falling back to it — otherwise revoking a token would keep working offline
+* until the entry aged out.
+*/
+async function resolveWithCache(ctx, query, cache) {
+	if (!cache) return ctx.client.resolve(query);
+	try {
+		const response = await ctx.client.resolve(query);
+		try {
+			cache.write(JSON.stringify(response));
+		} catch (err) {
+			warn(`could not update the cache: ${errorMessage(err)}`);
+		}
+		return response;
+	} catch (err) {
+		if (!mayFallBack(err)) {
+			cache.invalidate();
+			throw err;
+		}
+		const found = cache.read();
+		if (found.kind === "hit") {
+			warn(`${errorMessage(err)} — using cached secrets fetched ${humanize(found.ageMs)} ago`);
+			return JSON.parse(found.body);
+		}
+		if (found.kind === "expired") warn(`cached secrets are ${humanize(found.ageMs)} old, past --cache-max-age`);
+		else if (found.kind === "unusable") warn(`ignoring the cached secrets: ${found.reason}`);
+		throw err;
+	}
+}
+function warn(text) {
+	process.stderr.write(`seekrit: ${text}\n`);
+}
+function errorMessage(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+/**
 * Overlay `.env` files onto an existing value/provenance set (later files win).
 * Missing files are skipped. Returns the files that were actually loaded. Used
 * both by {@link materializeEnv} and by `seekrit run`'s degraded path, where
@@ -6582,20 +6965,27 @@ withTarget(secrets.command("list").alias("ls").description("list secret names (n
 		col("updated", (s) => s.updatedAt)
 	], `no secrets in ${label}`));
 });
-withTarget(secrets.command("get <name>").description("decrypt and print one secret value").option("--raw", "print the stored value without expanding ${OTHER_SECRET} references").option("--version <n>", "print an earlier version instead of the current one")).action(async (name, options) => {
+withTarget(secrets.command("get <name>").description("decrypt and print one secret value").option("--raw", "print the stored value without expanding ${OTHER_SECRET} references").option("--version <n>", "print an earlier version instead of the current one").option("--pretty", "re-indent the value if it is JSON (left alone if it is not)")).action(async (name, options) => {
 	const ctx = buildContext();
 	const { orgId, envId } = await resolveEnvTarget(ctx, options);
 	let value;
 	if (options.version === void 0) value = (await fetchDecryptedSecrets(ctx, orgId, envId, { raw: options.raw }))[name];
 	else value = await fetchDecryptedVersion(ctx, orgId, envId, name, parseVersion(options.version));
 	if (value === void 0) fail(`no secret named ${name}`);
-	process.stdout.write(value);
+	process.stdout.write(options.pretty ? prettyJsonOrRaw(value) : value);
 	if (process.stdout.isTTY) process.stdout.write("\n");
 });
-withTarget(secrets.command("set <name> [value]").description("encrypt and store a secret (reads stdin when value is omitted or '-')")).action(async (name, value, options) => {
+withTarget(secrets.command("set <name> [value]").description("encrypt and store a secret (reads stdin when value is omitted or '-')").option("--file <path>", "read the value from a file — the way to store a JSON credential or a PEM key without fighting shell quoting")).action(async (name, value, options) => {
+	if (options.file !== void 0 && value !== void 0) fail("pass a value or --file, not both");
 	const ctx = buildContext();
 	const { orgId, envId } = await resolveEnvTarget(ctx, options);
-	await encryptAndSetSecret(ctx, orgId, envId, name, value === void 0 || value === "-" ? (await readStdin()).replace(/\n$/, "") : value);
+	let plaintext;
+	if (options.file !== void 0) {
+		if (!existsSync(options.file)) fail(`no such file: ${options.file}`);
+		plaintext = readFileSync(options.file, "utf8").replace(/\n$/, "");
+	} else if (value === void 0 || value === "-") plaintext = (await readStdin()).replace(/\n$/, "");
+	else plaintext = value;
+	await encryptAndSetSecret(ctx, orgId, envId, name, plaintext);
 	console.error(`${name} saved`);
 });
 withTarget(secrets.command("import [file]").description("bulk-import secrets from a .env file (default .env; '-' reads stdin)").option("--dry-run", "list the variable names that would be imported, without writing")).action(async (file, options) => {
@@ -6649,8 +7039,55 @@ withTarget(secrets.command("rm <name>").description("delete a secret")).action(a
 	await ctx.client.deleteSecret(orgId, envId, name);
 	console.error(`${name} deleted`);
 });
+/**
+* Open the last-known-good cache for this request, or `undefined` when it is
+* off. `dotenvVars` carries `SEEKRIT_*` values read from a `.env` file, so the
+* flags follow the same `flag > env > .env` precedence as the credentials.
+*
+* **Service tokens only.** A user session's private key is fetched from the API
+* and unlocked with a passphrase, so caching the resolve response alone would
+* not make an offline run work — and the token is what the cache key is built
+* from. `--cache` under user auth is a no-op we say out loud rather than a
+* silent one.
+*/
+function openCache(ctx, options, dotenvVars = {}) {
+	const lookup = (key) => process.env[key] ?? dotenvVars[key];
+	const truthy = (value) => [
+		"1",
+		"true",
+		"yes",
+		"on"
+	].includes((value ?? "").trim().toLowerCase());
+	if (!(options.cache ?? truthy(lookup("SEEKRIT_CACHE")))) return void 0;
+	if (!isTokenAuth(ctx)) {
+		process.stderr.write("seekrit: --cache needs a service token (SEEKRIT_TOKEN); continuing without it\n");
+		return;
+	}
+	const token = ctx.auth.type === "bearer" ? ctx.auth.token : "";
+	const maxAgeRaw = options.cacheMaxAge ?? lookup("SEEKRIT_CACHE_MAX_AGE");
+	const maxAgeMs = maxAgeRaw ? parseDurationMs(maxAgeRaw) : DEFAULT_MAX_AGE_MS;
+	const branch = options.branch ?? process.env.SEEKRIT_BRANCH ?? dotenvVars.SEEKRIT_BRANCH;
+	return new LkgCache(cacheKey(ctx.apiUrl, token, branch, options.with), {
+		dir: options.cacheDir ?? lookup("SEEKRIT_CACHE_DIR"),
+		maxAgeMs
+	});
+}
+/** `30s` / `15m` / `24h` / `7d` / bare seconds → ms. Matches the Rust parser. */
+function parseDurationMs(raw) {
+	const match = /^(\d+)\s*([smhd]?)$/.exec(raw.trim());
+	if (!match) fail(`--cache-max-age: not a duration: "${raw}" (try 15m, 24h, 7d)`);
+	const value = Number(match[1]);
+	if (value === 0) fail("--cache-max-age: must be greater than zero");
+	return value * ({
+		"": 1,
+		s: 1,
+		m: 60,
+		h: 3600,
+		d: 86400
+	}[match[2] ?? ""] ?? 1) * 1e3;
+}
 /** Resolve the layered environment for the current principal. */
-async function materialize(ctx, options) {
+async function materialize(ctx, options, dotenvVars = {}) {
 	let envId;
 	if (!isTokenAuth(ctx)) envId = (await resolveAppEnv(ctx, options)).envId;
 	return materializeEnv(ctx, {
@@ -6658,7 +7095,8 @@ async function materialize(ctx, options) {
 		branch: options.branch ?? process.env.SEEKRIT_BRANCH,
 		with: options.with,
 		envFiles: options.envFile ?? [".env"],
-		interpolate: options.interpolate
+		interpolate: options.interpolate,
+		cache: openCache(ctx, options, dotenvVars)
 	});
 }
 /**
@@ -6680,7 +7118,7 @@ async function materializeForRun(options) {
 		return await materialize(ctx, {
 			...options,
 			branch
-		});
+		}, dotenvVars);
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
 		console.error(`seekrit: continuing without seekrit-managed secrets: ${message}`);
@@ -6803,7 +7241,7 @@ async function reapStragglers(pids, signal) {
 		process.kill(pid, "SIGKILL");
 	} catch {}
 }
-program.command("run").description("run a command with decrypted secrets injected (process env > .env > app > group)").passThroughOptions().option("--org <slug>").option("--app <slug>", "application slug (token path infers this)").option("--env <slug>", "environment slug (token path infers this)").option("--branch <slug>", "read a branch of that environment (or $SEEKRIT_BRANCH)").option("--with <group=env>", "override one group’s slice for this run", collectKv).option("--env-file <path>", "a .env file to overlay (repeatable; default .env)", collectList).option("--explain", "print where each variable resolved from (to stderr)").option("--no-interpolate", "leave ${OTHER_SECRET} references as literal text").argument("<command...>", "command to run (prefix with -- to pass flags)").action(async (commandParts, options) => {
+program.command("run").description("run a command with decrypted secrets injected (process env > .env > app > group)").passThroughOptions().option("--org <slug>").option("--app <slug>", "application slug (token path infers this)").option("--env <slug>", "environment slug (token path infers this)").option("--branch <slug>", "read a branch of that environment (or $SEEKRIT_BRANCH)").option("--with <group=env>", "override one group’s slice for this run", collectKv).option("--env-file <path>", "a .env file to overlay (repeatable; default .env)", collectList).option("--explain", "print where each variable resolved from (to stderr)").option("--no-interpolate", "leave ${OTHER_SECRET} references as literal text").option("--cache", "keep a last-known-good copy of the encrypted response and fall back to it when the API is unreachable (off by default; SEEKRIT_CACHE=1)").option("--cache-dir <path>", "where to keep it (default: $XDG_CACHE_HOME/seekrit)").option("--cache-max-age <duration>", "how stale a cached copy may be and still be used, e.g. 15m, 24h, 7d (default: 24h)").argument("<command...>", "command to run (prefix with -- to pass flags)").action(async (commandParts, options) => {
 	const [cmd, ...args] = commandParts;
 	if (!cmd) fail("no command given");
 	const { values, provenance, interpolated, unresolvedRefs } = await materializeForRun(options);
@@ -6855,7 +7293,7 @@ program.command("run").description("run a command with decrypted secrets injecte
 	});
 	child.on("error", (err) => fail(`failed to start ${cmd}: ${err.message}`));
 });
-program.command("export").description("print decrypted secrets (dotenv, json, or shell)").option("--org <slug>").option("--app <slug>", "application slug (token path infers this)").option("--env <slug>", "environment slug (token path infers this)").option("--branch <slug>", "read a branch of that environment (or $SEEKRIT_BRANCH)").option("--with <group=env>", "override one group’s slice", collectKv).option("--env-file <path>", "a .env file to overlay (repeatable; default .env)", collectList).option("--explain", "print where each variable resolved from (to stderr)").option("--no-interpolate", "leave ${OTHER_SECRET} references as literal text").option("--format <format>", "dotenv | json | shell", "dotenv").action(async (options) => {
+program.command("export").description("print decrypted secrets (dotenv, json, or shell)").option("--org <slug>").option("--app <slug>", "application slug (token path infers this)").option("--env <slug>", "environment slug (token path infers this)").option("--branch <slug>", "read a branch of that environment (or $SEEKRIT_BRANCH)").option("--with <group=env>", "override one group’s slice", collectKv).option("--env-file <path>", "a .env file to overlay (repeatable; default .env)", collectList).option("--explain", "print where each variable resolved from (to stderr)").option("--no-interpolate", "leave ${OTHER_SECRET} references as literal text").option("--cache", "keep a last-known-good copy of the encrypted response and fall back to it when the API is unreachable (off by default; SEEKRIT_CACHE=1)").option("--cache-dir <path>", "where to keep it (default: $XDG_CACHE_HOME/seekrit)").option("--cache-max-age <duration>", "how stale a cached copy may be and still be used, e.g. 15m, 24h, 7d (default: 24h)").option("--format <format>", "dotenv | json | shell", "dotenv").action(async (options) => {
 	if (![
 		"dotenv",
 		"json",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seekrit/cli",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "description": "End-to-end encrypted secrets manager CLI — inject decrypted secrets into any command.",
   "type": "module",
   "publishConfig": {
@@ -26,13 +26,15 @@
   "devDependencies": {
     "@types/node": "^26.1.0",
     "tsdown": "^0.22.3",
-    "@seekrit/api-client": "0.0.1",
+    "vitest": "^4.1.9",
     "@seekrit/core": "0.0.1",
+    "@seekrit/api-client": "0.0.1",
     "@seekrit/crypto": "0.0.1"
   },
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
+    "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }
 }