@seekrit/cli 0.21.0 → 0.23.0

package/dist/index.js

@@ -1976,7 +1976,7 @@ function isServiceToken(value) {
 }
 //#endregion
 //#region package.json
-var version = "0.21.0";
+var version = "0.23.0";
 //#endregion
 //#region ../../packages/api-client/src/index.ts
 var SeekritApiError = class extends Error {
@@ -1993,13 +1993,16 @@ var SeekritClient = class {
 	baseUrl;
 	auth;
 	fetchImpl;
+	client;
 	constructor(options) {
 		this.baseUrl = options.baseUrl.replace(/\/$/, "");
 		this.auth = options.auth;
 		this.fetchImpl = options.fetch ?? ((...args) => fetch(...args));
+		this.client = options.client;
 	}
 	async request(method, path, body) {
 		const headers = { accept: "application/json" };
+		if (this.client) headers["x-seekrit-client"] = this.client;
 		if (this.auth.type === "bearer") headers.authorization = `Bearer ${this.auth.token}`;
 		else if (this.auth.type === "dynamic") {
 			const token = await this.auth.getToken();
@@ -2430,6 +2433,8 @@ async function readStdin() {
 }
 //#endregion
 //#region src/context.ts
+/** Sent as `x-seekrit-client` so the API attributes usage to the CLI (analytics). */
+const CLI_CLIENT = `cli/${version}`;
 /**
 * Build the client context from configured credentials, or return null when
 * none are set. `seekrit run` uses this to degrade to a plain launcher instead
@@ -2460,7 +2465,8 @@ function tryBuildContext(dotenvVars = {}) {
 	return {
 		client: new SeekritClient({
 			baseUrl: apiUrl,
-			auth
+			auth,
+			client: CLI_CLIENT
 		}),
 		auth
 	};
@@ -3232,7 +3238,8 @@ async function mintAdminToken(apiUrl, creds) {
 			type: "m2m",
 			clientId: creds.clientId,
 			clientSecret: creds.clientSecret
-		}
+		},
+		client: `cli/${version}`
 	});
 	const { orgs } = await client.listOrgs();
 	const org = orgs[0];
@@ -4716,7 +4723,7 @@ registerMongoCommands(program);
 registerKmsCommands(program);
 registerRecoveryCommands(program);
 program.command("mcp").description("run an MCP server over stdio so AI agents can drive seekrit").action(async () => {
-	const { runMcpServer } = await import("./mcp-DScHFOMG.js");
+	const { runMcpServer } = await import("./mcp-CbNXG37n.js");
 	await runMcpServer();
 });
 program.command("audit").description("show the org audit trail").option("--org <slug>").option("--limit <n>", "entries to fetch", "50").action(async (options) => {

package/dist/{mcp-DScHFOMG.js → mcp-CbNXG37n.js}

@@ -26,6 +26,74 @@ function errText(err) {
 		isError: true
 	};
 }
+/**
+* Short primer surfaced as the MCP server `instructions`. Most clients show
+* this to the model on connect, so it has to orient an agent that lands here
+* with zero context in a few lines.
+*/
+function serverInstructions() {
+	return [
+		"seekrit is a zero-knowledge secrets manager. This is the LOCAL CRYPTO plane —",
+		"it runs on this machine, next to your key, so it's the one server that can",
+		"actually read or write a secret VALUE (everything else can only see structure).",
+		"",
+		"Auth comes from SEEKRIT_TOKEN (a skt_… token), SEEKRIT_CLIENT_ID +",
+		"SEEKRIT_CLIENT_SECRET (machine credentials — an admin token is minted and",
+		"cached automatically on first use), or the config saved by `seekrit login`.",
+		"Decrypting under a user session (not a token) additionally needs",
+		"SEEKRIT_PASSPHRASE set in this server's env — there's no TTY to prompt on.",
+		"",
+		"Model: org → apps/groups → environments → secrets. Call `whoami` first, then",
+		"`get_started` for the recommended end-to-end recipe. Prefer `run_command` over",
+		"`get_secret reveal:true` — it injects secrets into a subprocess so plaintext",
+		"never enters your context or the transcript."
+	].join("\n");
+}
+/** The `get_started` tool body: the recommended first-project flow end to end. */
+function getStartedText() {
+	return [
+		"# Standing up a project with seekrit (agent, end to end)",
+		"",
+		"This server is the crypto plane — every step below runs locally, next to your",
+		"key, so secret values never leave this machine.",
+		"",
+		"## 1. Confirm identity",
+		"`whoami` — see who you're authenticated as and which orgs you can reach. If it",
+		"fails, check SEEKRIT_TOKEN / SEEKRIT_CLIENT_ID+SEEKRIT_CLIENT_SECRET / saved",
+		"login in this server's env.",
+		"",
+		"## 2. Provision structure",
+		"- `create_org` (user session only — a service token can't own one) if you",
+		"  don't have one yet, otherwise skip to the next step.",
+		"- `create_app` — an application to hold environments.",
+		"- `create_env` — generates the data key on this machine and grants it to you.",
+		"- `create_group` + `compose_group` (optional) — a reusable secret bag layered",
+		"  under one or more app environments.",
+		"",
+		"## 3. Store secrets",
+		"- `set_secret` — encrypts a value locally and stores the ciphertext.",
+		"- `list_secrets` — confirm names + versions (never returns values).",
+		"",
+		"## 4. Use secrets without exposing them",
+		"- `run_command -- <cmd>` — inject secrets into a subprocess; prefer this.",
+		"- `export_env` — materialize a `.env` file when a tool needs one on disk.",
+		"- `get_secret reveal:true` — only when the value itself is what's needed.",
+		"",
+		"## 5. Propagate access",
+		"- `create_token` bound to an app+env — a runtime credential for CI/another",
+		"  agent to decrypt with (pass `admin:true` instead for a provisioning token).",
+		"- `grant_env` — give another member or token access to an env's data key.",
+		"- `configure_project` — link a directory to an org/app (writes seekrit.json)",
+		"  so a bound token can infer its target without flags.",
+		"",
+		"## 6. Verify",
+		"`audit` — every write, grant, and revocation is recorded; read it back.",
+		"",
+		"Also available: `kms_*` (client-side managed encrypt/sign keys) and",
+		"`create_pg_lease`/`create_mysql_lease` (short-lived database credentials whose",
+		"password is generated here and never stored anywhere in plaintext)."
+	].join("\n");
+}
 /** Build the client context or throw a friendly, agent-readable error. */
 function getCtx() {
 	const ctx = tryBuildContext();
@@ -121,7 +189,7 @@ async function runMcpServer(options = {}) {
 	const server = new McpServer({
 		name: "seekrit",
 		version: options.version ?? version
-	});
+	}, { instructions: serverInstructions() });
 	/** Register a tool whose handler returns data (serialized) or throws (→ isError). */
 	const tool = (name, description, shape, handler) => {
 		server.registerTool(name, {
@@ -135,6 +203,15 @@ async function runMcpServer(options = {}) {
 			}
 		}));
 	};
+	server.registerTool("get_started", {
+		description: "The recommended first-project recipe: provision structure, store secrets, and use them without exposing values. Call this before doing anything else.",
+		inputSchema: {},
+		annotations: {
+			title: "get_started",
+			readOnlyHint: true,
+			openWorldHint: false
+		}
+	}, async () => jsonText(getStartedText()));
 	tool("whoami", "Show the authenticated identity, its role, and accessible orgs.", {}, async () => {
 		const ctx = getCtx();
 		if (isTokenAuth(ctx) && ctx.auth.type === "bearer") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seekrit/cli",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "End-to-end encrypted secrets manager CLI — inject decrypted secrets into any command.",
   "type": "module",
   "publishConfig": {