@evantahler/mcpx 0.19.2 → 0.20.1

package/.claude/skills/mcpx.md

@@ -47,6 +47,7 @@ This shows parameters, types, required fields, and the full JSON Schema.
 ```bash
 mcpx exec <tool> '<json args>'                # server auto-resolved if unambiguous
 mcpx exec <server> <tool> '<json args>'       # explicit server (required if tool name exists on multiple servers)
+mcpx exec <server> <tool> -- --field value    # shell-flag args (typed via the tool's input schema)
 mcpx exec <server> <tool> -f params.json
 ```
 
@@ -78,6 +79,9 @@ mcpx exec Slack_SendMessage '{"channel":"#general","message":"hello"}'
 # Or explicitly specify the server
 mcpx exec arcade Slack_SendMessage '{"channel":"#general","message":"hello"}'
 
+# Shell-flag form (anything after `--` is parsed against the tool's input schema)
+mcpx exec arcade Slack_SendMessage -- --channel "#general" --message "hello"
+
 # Chain commands — search repos and read the first result
 mcpx exec github search_repositories '{"query":"mcp"}' \
   | jq -r '.content[0].text | fromjson | .items[0].full_name' \
@@ -143,6 +147,7 @@ mcpx deauth <server>           # remove stored auth
 | `mcpx exec <server>`                  | List tools for a server           |
 | `mcpx exec <tool> '<json>'`           | Execute tool (server auto-resolved) |
 | `mcpx exec <server> <tool> '<json>'`  | Execute tool (explicit server)    |
+| `mcpx exec <server> <tool> -- --k=v`  | Execute with shell-flag args (typed via schema) |
 | `mcpx exec <server> <tool> -f file`   | Execute with args from file       |
 | `mcpx search "<query>"`               | Search tools (keyword + semantic) |
 | `mcpx search -k "<pattern>"`          | Keyword/glob search only          |

package/.cursor/rules/mcpx.mdc

@@ -27,6 +27,7 @@ This shows parameters, types, required fields, and the full JSON Schema.
 ```bash
 mcpx exec <tool> '<json args>'                # server auto-resolved if unambiguous
 mcpx exec <server> <tool> '<json args>'       # explicit server (required if tool name exists on multiple servers)
+mcpx exec <server> <tool> -- --field value    # shell-flag args (typed via the tool's input schema)
 mcpx exec <server> <tool> -f params.json
 ```
 
@@ -58,6 +59,9 @@ mcpx exec Slack_SendMessage '{"channel":"#general","message":"hello"}'
 # Or explicitly specify the server
 mcpx exec arcade Slack_SendMessage '{"channel":"#general","message":"hello"}'
 
+# Shell-flag form (anything after `--` is parsed against the tool's input schema)
+mcpx exec arcade Slack_SendMessage -- --channel "#general" --message "hello"
+
 # Chain commands — search repos and read the first result
 mcpx exec github search_repositories '{"query":"mcp"}' \
   | jq -r '.content[0].text | fromjson | .items[0].full_name' \
@@ -139,6 +143,7 @@ mcpx deauth <server>           # remove stored auth
 | `mcpx exec <server>`                  | List tools for a server           |
 | `mcpx exec <tool> '<json>'`           | Execute tool (server auto-resolved) |
 | `mcpx exec <server> <tool> '<json>'`  | Execute tool (explicit server)    |
+| `mcpx exec <server> <tool> -- --k=v`  | Execute with shell-flag args (typed via schema) |
 | `mcpx exec <server> <tool> -f file`   | Execute with args from file       |
 | `mcpx search "<query>"`               | Search tools (keyword + semantic) |
 | `mcpx search -k "<pattern>"`          | Keyword/glob search only          |

package/README.md

@@ -45,11 +45,15 @@ mcpx info github
 # Inspect a specific tool
 mcpx info github search_repositories
 
-# Execute a tool
+# Execute a tool (JSON args)
 mcpx exec github search_repositories '{"query": "mcp server"}'
 
+# Execute a tool with shell-style flags (anything after `--` is parsed against the tool's input schema)
+mcpx exec github search_repositories -- --query "mcp server"
+
 # Execute a tool without specifying the server (auto-resolved)
 mcpx exec search_repositories '{"query": "mcp server"}'
+mcpx exec search_repositories -- --query "mcp server"
 
 # Search tools — combines keyword and semantic matching
 mcpx search "post a ticket to linear"
@@ -80,6 +84,7 @@ mcpx search -n 5 "manage pull requests"
 | `mcpx index -i`                        | Show index status                                      |
 | `mcpx exec <server> <tool> [json]`     | Validate inputs locally, then execute tool             |
 | `mcpx exec <tool> [json]`              | Execute tool (server auto-resolved if unambiguous)     |
+| `mcpx exec <server> <tool> -- --k=v`   | Shell-flag args (typed via the tool's input schema)    |
 | `mcpx exec <server> <tool> -f file`    | Read tool args from a JSON file                        |
 | `mcpx exec <server>`                   | List available tools for a server                      |
 | `mcpx auth <server>`                   | Authenticate with an HTTP MCP server (OAuth)           |
@@ -505,6 +510,31 @@ Validation covers:
 
 If a tool's `inputSchema` is unavailable (some servers don't provide one), execution proceeds without local validation.
 
+### Shell-flag args
+
+Anything after a `--` separator is parsed as shell flags using the tool's input schema for type coercion. This is handy for interactive use — you don't need to remember JSON quoting rules.
+
+```bash
+# JSON form
+mcpx exec github create_issue '{"owner":"evantahler","repo":"mcpx","title":"bug"}'
+
+# Equivalent shell-flag form
+mcpx exec github create_issue -- --owner evantahler --repo mcpx --title bug
+
+# --field=value also works
+mcpx exec github create_issue -- --owner=evantahler --repo=mcpx --title=bug
+
+# Booleans
+mcpx exec my-server flagit -- --enabled         # true
+mcpx exec my-server flagit -- --no-enabled      # false
+
+# Arrays — repeatable flag or comma-split
+mcpx exec my-server tag -- --label bug --label todo
+mcpx exec my-server tag -- --label bug,todo
+```
+
+Type coercion follows the field's `type` in the input schema (`string`, `integer`, `number`, `boolean`, `array`). Nested objects must use the JSON form. Combining `--` shell flags with inline JSON args, `--file`, or stdin is rejected.
+
 ## Shell Output & Piping
 
 Output is human-friendly by default, JSON when piped:
@@ -635,6 +665,7 @@ To discover tools:
 To execute tools:
   mcpx exec <tool> '<json args>'              # server auto-resolved
   mcpx exec <server> <tool> '<json args>'     # explicit server
+  mcpx exec <server> <tool> -- --k=v          # shell-flag args (typed via schema)
   mcpx exec <server> <tool> -f params.json
 
 Always search before executing — don't assume tool names.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@evantahler/mcpx",
-	"version": "0.19.2",
+	"version": "0.20.1",
 	"description": "A command-line interface for MCP servers. curl for MCP.",
 	"type": "module",
 	"exports": {

package/src/cli.ts

@@ -21,6 +21,7 @@ import { registerServersCommand } from "./commands/servers.ts";
 import { registerSkillCommand } from "./commands/skill.ts";
 import { registerTaskCommand } from "./commands/task.ts";
 import { registerUpgradeCommand } from "./commands/upgrade.ts";
+import { logger } from "./output/logger.ts";
 import { maybeCheckForUpdate } from "./update/background.ts";
 
 program
@@ -96,5 +97,5 @@ program.parse();
 // Print update notice after command output completes
 process.on("beforeExit", async () => {
 	const notice = await updateNotice;
-	if (notice) process.stderr.write(notice);
+	if (notice) logger.writeRaw(notice);
 });

package/src/client/browser.ts

@@ -1,4 +1,5 @@
 import { execFile } from "node:child_process";
+import { logger } from "../output/logger.ts";
 
 /**
  * Open a URL in the default browser (macOS/Windows/Linux).
@@ -12,11 +13,11 @@ export function openBrowser(url: string): Promise<void> {
 	try {
 		const parsed = new URL(url);
 		if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-			process.stderr.write(`Refusing to open non-HTTP URL: ${url}\n`);
+			logger.error(`Refusing to open non-HTTP URL: ${url}`);
 			return Promise.resolve();
 		}
 	} catch {
-		process.stderr.write(`Invalid URL: ${url}\n`);
+		logger.error(`Invalid URL: ${url}`);
 		return Promise.resolve();
 	}
 
@@ -37,7 +38,7 @@ export function openBrowser(url: string): Promise<void> {
 	return new Promise((resolve) => {
 		execFile(cmd, args, (err) => {
 			if (err) {
-				process.stderr.write(`Could not open browser. Please visit:\n  ${url}\n`);
+				logger.warn(`Could not open browser. Please visit:\n  ${url}`);
 			}
 			resolve();
 		});

package/src/client/elicitation.ts

@@ -7,6 +7,7 @@ import type {
 	PrimitiveSchemaDefinition,
 } from "@modelcontextprotocol/sdk/types.js";
 import ansis from "ansis";
+import { logger } from "../output/logger.ts";
 import { validateElicitationResponse } from "../validation/schema.ts";
 import { openBrowser } from "./browser.ts";
 
@@ -74,7 +75,7 @@ async function handleFormInteractive(params: ElicitRequestFormParams): Promise<E
 	const question = (prompt: string): Promise<string> => new Promise((resolve) => rl.question(prompt, resolve));
 
 	try {
-		process.stderr.write(`\n${ansis.bold("Server requests input:")} ${params.message}\n`);
+		logger.writeRaw(`\n${ansis.bold("Server requests input:")} ${params.message}\n`);
 
 		const schema = params.requestedSchema;
 		const properties = schema.properties ?? {};
@@ -86,7 +87,7 @@ async function handleFormInteractive(params: ElicitRequestFormParams): Promise<E
 			const value = await promptField(key, fieldSchema, isRequired, question);
 			if (value === undefined) {
 				if (isRequired) {
-					process.stderr.write(ansis.yellow("Cancelled.\n"));
+					logger.writeRaw(ansis.yellow("Cancelled.\n"));
 					return { action: "cancel" };
 				}
 				continue;
@@ -98,7 +99,7 @@ async function handleFormInteractive(params: ElicitRequestFormParams): Promise<E
 		const validation = validateElicitationResponse(schema as unknown as Record<string, unknown>, content);
 		if (!validation.valid) {
 			const msgs = validation.errors.map((e) => `  ${e.path}: ${e.message}`).join("\n");
-			process.stderr.write(ansis.red(`Validation failed:\n${msgs}\n`));
+			logger.writeRaw(ansis.red(`Validation failed:\n${msgs}\n`));
 			return { action: "cancel" };
 		}
 
@@ -121,7 +122,7 @@ async function promptField(
 
 	// Show description if present
 	if (desc) {
-		process.stderr.write(ansis.dim(`  ${desc}\n`));
+		logger.writeRaw(ansis.dim(`  ${desc}\n`));
 	}
 
 	// Enum (single-select)
@@ -178,7 +179,7 @@ async function promptNumber(
 	if (!answer) return undefined;
 	const num = Number(answer);
 	if (Number.isNaN(num)) {
-		process.stderr.write(ansis.red(`  Invalid number: ${answer}\n`));
+		logger.writeRaw(ansis.red(`  Invalid number: ${answer}\n`));
 		return undefined;
 	}
 	return num;
@@ -206,10 +207,10 @@ async function promptEnum(
 ): Promise<string | undefined> {
 	const values = (schema as { enum: string[] }).enum;
 	const def = (schema as { default?: string }).default;
-	process.stderr.write(`  ${marker}${label}:\n`);
+	logger.writeRaw(`  ${marker}${label}:\n`);
 	values.forEach((v, i) => {
 		const defMark = v === def ? ansis.dim(" (default)") : "";
-		process.stderr.write(`    [${i + 1}] ${v}${defMark}\n`);
+		logger.writeRaw(`    [${i + 1}] ${v}${defMark}\n`);
 	});
 	const answer = await question("  > ");
 	if (!answer && def !== undefined) return def;
@@ -228,10 +229,10 @@ async function promptOneOfEnum(
 ): Promise<string | undefined> {
 	const options = (schema as { oneOf: { const: string; title: string }[] }).oneOf;
 	const def = (schema as { default?: string }).default;
-	process.stderr.write(`  ${marker}${label}:\n`);
+	logger.writeRaw(`  ${marker}${label}:\n`);
 	options.forEach((opt, i) => {
 		const defMark = opt.const === def ? ansis.dim(" (default)") : "";
-		process.stderr.write(`    [${i + 1}] ${opt.title} (${opt.const})${defMark}\n`);
+		logger.writeRaw(`    [${i + 1}] ${opt.title} (${opt.const})${defMark}\n`);
 	});
 	const answer = await question("  > ");
 	if (!answer && def !== undefined) return def;
@@ -264,10 +265,10 @@ async function promptMultiSelect(
 		return undefined;
 	}
 
-	process.stderr.write(`  ${marker}${label} (select multiple, comma-separated):\n`);
+	logger.writeRaw(`  ${marker}${label} (select multiple, comma-separated):\n`);
 	values.forEach((v, i) => {
 		const display = titles ? `${titles[i]} (${v})` : v;
-		process.stderr.write(`    [${i + 1}] ${display}\n`);
+		logger.writeRaw(`    [${i + 1}] ${display}\n`);
 	});
 	const answer = await question("  > ");
 	if (!answer && def !== undefined) return def;
@@ -324,10 +325,10 @@ async function handleUrlInteractive(params: ElicitRequestURLParams): Promise<Eli
 			}
 		})();
 
-		process.stderr.write(`\n${ansis.bold("Server requests URL interaction:")}\n`);
-		process.stderr.write(`  ${params.message}\n`);
-		process.stderr.write(`  ${ansis.yellow("Domain:")} ${domain}\n`);
-		process.stderr.write(`  ${ansis.yellow("URL:")} ${params.url}\n`);
+		logger.writeRaw(`\n${ansis.bold("Server requests URL interaction:")}\n`);
+		logger.writeRaw(`  ${params.message}\n`);
+		logger.writeRaw(`  ${ansis.yellow("Domain:")} ${domain}\n`);
+		logger.writeRaw(`  ${ansis.yellow("URL:")} ${params.url}\n`);
 
 		const answer = await question(`  Open in browser? [y/n]: `);
 		if (["y", "yes"].includes(answer.toLowerCase())) {

package/src/commands/exec.ts

@@ -2,7 +2,7 @@ import type { Command } from "commander";
 import type { ServerManager } from "../client/manager.ts";
 import { DEFAULTS } from "../constants.ts";
 import { getContext } from "../context.ts";
-import { parseJsonArgs, readStdin } from "../lib/input.ts";
+import { parseJsonArgs, parseShellArgs, readStdin } from "../lib/input.ts";
 import {
 	formatCallResult,
 	formatError,
@@ -15,17 +15,25 @@ import { validateToolInput } from "../validation/schema.ts";
 
 type ResolvedArgs =
 	| { mode: "list-tools"; server: string }
-	| { mode: "call-tool"; server: string; tool: string; argsStr: string | undefined };
+	| {
+			mode: "call-tool";
+			server: string;
+			tool: string;
+			rest: string[];
+	  };
 
 /**
  * Resolve the positional args into either list-tools or call-tool mode.
  * Supports both `exec <server> <tool> [args]` and `exec <tool> [args]`.
+ *
+ * `rest` is whatever positional tokens remain after `<server> <tool>`. It may contain
+ * a single inline JSON string, or shell-flag tokens (after `--`), or be empty.
  */
 async function resolveExecArgs(
 	manager: ServerManager,
 	first: string,
 	second: string | undefined,
-	third: string | undefined,
+	rest: string[],
 ): Promise<ResolvedArgs> {
 	const serverNames = manager.getServerNames();
 	const isServer = serverNames.includes(first);
@@ -60,10 +68,10 @@ async function resolveExecArgs(
 			}
 		}
 
-		return { mode: "call-tool", server: first, tool: second, argsStr: third };
+		return { mode: "call-tool", server: first, tool: second, rest };
 	}
 
-	// Not a server name — treat first as a tool name
+	// Not a server name — treat first as a tool name; `second` is the start of `rest`.
 	const toolName = first;
 	const { tools } = await manager.getAllTools();
 	const matches = tools.filter((t) => t.tool.name === toolName);
@@ -79,28 +87,32 @@ async function resolveExecArgs(
 		);
 	}
 
-	return { mode: "call-tool", server: matches[0]!.server, tool: toolName, argsStr: second };
+	const fullRest = second === undefined ? rest : [second, ...rest];
+	return { mode: "call-tool", server: matches[0]!.server, tool: toolName, rest: fullRest };
 }
 
 export function registerExecCommand(program: Command) {
 	program
-		.command("exec <first> [second] [third]")
-		.description("execute a tool (server is optional if tool name is unambiguous)")
+		.command("exec <server> [tool] [args...]")
+		.description(
+			"execute a tool. server may be omitted if the tool name is unambiguous: `mcpx exec <tool> [args...]`. " +
+				"args may be a single JSON object string, or shell flags after `--` (e.g. `-- --field value`).",
+		)
 		.option("-f, --file <path>", "read JSON args from a file")
 		.option("--no-wait", "return task handle immediately without waiting for completion")
 		.option("--ttl <ms>", "task TTL in milliseconds", String(DEFAULTS.TASK_TTL_MS))
 		.action(
 			async (
-				first: string,
-				second: string | undefined,
-				third: string | undefined,
+				serverOrTool: string,
+				toolOrFirstArg: string | undefined,
+				trailing: string[],
 				options: { file?: string; wait: boolean; ttl: string },
 			) => {
 				const { manager, formatOptions } = await getContext(program);
 
 				let resolved: ResolvedArgs;
 				try {
-					resolved = await resolveExecArgs(manager, first, second, third);
+					resolved = await resolveExecArgs(manager, serverOrTool, toolOrFirstArg, trailing);
 				} catch (err) {
 					console.error(formatError(String(err), formatOptions));
 					await manager.close();
@@ -120,15 +132,32 @@ export function registerExecCommand(program: Command) {
 					return;
 				}
 
-				const { server, tool, argsStr } = resolved;
+				const { server, tool, rest } = resolved;
 
 				try {
-					// Error if both --file and positional arg provided
+					// Classify the trailing positional tokens. If the first one starts with `--`
+					// it's the shell-flag form; otherwise, treat a single token as inline JSON.
+					const isShellFlagForm = rest.length > 0 && rest[0]!.startsWith("--");
+					const argsStr = !isShellFlagForm && rest.length === 1 ? rest[0] : undefined;
+					const shellTokens = isShellFlagForm ? rest : [];
+
+					// More than one positional token without `--` flag prefix is ambiguous.
+					if (!isShellFlagForm && rest.length > 1) {
+						throw new Error("Cannot mix inline JSON args with shell flags — use one form");
+					}
+
+					// Conflict checks
 					if (options.file && argsStr) {
 						throw new Error("Cannot specify both --file and inline JSON args");
 					}
+					if (shellTokens.length > 0 && options.file) {
+						throw new Error("Cannot mix `--` shell flags with --file");
+					}
 
-					// Parse args from: --file > positional arg > stdin > empty
+					// Fetch the tool schema once, up front, so shell-flag parsing can use it for type coercion.
+					const toolSchema = await manager.getToolSchema(server, tool);
+
+					// Parse args from: --file > inline JSON positional > shell flags after `--` > stdin > empty
 					let args: Record<string, unknown> = {};
 
 					if (options.file) {
@@ -140,6 +169,8 @@ export function registerExecCommand(program: Command) {
 						args = parseJsonArgs(content);
 					} else if (argsStr) {
 						args = parseJsonArgs(argsStr);
+					} else if (shellTokens.length > 0) {
+						args = parseShellArgs(shellTokens, toolSchema?.inputSchema);
 					} else if (!process.stdin.isTTY) {
 						// Read from stdin
 						const stdin = await readStdin();
@@ -149,7 +180,6 @@ export function registerExecCommand(program: Command) {
 					}
 
 					// Validate args against tool inputSchema before calling
-					const toolSchema = await manager.getToolSchema(server, tool);
 					if (toolSchema) {
 						const validation = validateToolInput(server, toolSchema, args);
 						if (!validation.valid) {

package/src/config/loader.ts

@@ -1,6 +1,7 @@
 import { chmod } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { DEFAULT_CONFIG_DIR, ENV } from "../constants.ts";
+import { logger } from "../output/logger.ts";
 import { interpolateEnv } from "./env.ts";
 import {
 	type AuthFile,
@@ -64,7 +65,7 @@ export async function loadConfig(options: LoadConfigOptions = {}): Promise<Confi
 		const cwd = process.cwd();
 		if (await hasServersFile(cwd)) {
 			configDir = cwd;
-			process.stderr.write(`Note: using servers.json from current directory (${cwd})\n`);
+			logger.info(`Note: using servers.json from current directory (${cwd})`);
 		}
 	}
 

package/src/lib/input.ts

@@ -31,3 +31,173 @@ export async function readStdin(): Promise<string> {
 	}
 	return chunks.join("");
 }
+
+type SchemaProperty = {
+	type?: string | string[];
+	items?: { type?: string | string[] };
+};
+
+/**
+ * Parse shell-style flag tokens into an arguments object, using a JSON Schema for type
+ * coercion. Supports:
+ *   --key value, --key=value
+ *   --key            (boolean true; only when schema says boolean or schema is unknown)
+ *   --no-key         (boolean false; only when `key` is a known boolean field)
+ *   repeated flags or comma-separated values for arrays
+ *
+ * Coerces values to integer/number/boolean according to the field's `type` in the
+ * schema. For unknown fields (or empty schema), values are left as strings — Ajv
+ * will surface the unknown-field error during validation.
+ */
+export function parseShellArgs(
+	tokens: string[],
+	inputSchema: Record<string, unknown> | undefined,
+): Record<string, unknown> {
+	const properties = (inputSchema?.properties ?? {}) as Record<string, SchemaProperty>;
+	const result: Record<string, unknown> = {};
+	const seen = new Set<string>();
+
+	function getType(key: string): string | undefined {
+		const prop = properties[key];
+		if (!prop) return undefined;
+		const t = prop.type;
+		return Array.isArray(t) ? t[0] : t;
+	}
+
+	function getItemType(key: string): string | undefined {
+		const t = properties[key]?.items?.type;
+		return Array.isArray(t) ? t[0] : t;
+	}
+
+	function coerceScalar(key: string, raw: string, type: string | undefined): unknown {
+		switch (type) {
+			case "string":
+				return raw;
+			case "integer": {
+				const n = Number.parseInt(raw, 10);
+				if (Number.isNaN(n) || !/^-?\d+$/.test(raw.trim())) {
+					throw new Error(`--${key}: expected integer, got "${raw}"`);
+				}
+				return n;
+			}
+			case "number": {
+				const n = Number.parseFloat(raw);
+				if (Number.isNaN(n)) {
+					throw new Error(`--${key}: expected number, got "${raw}"`);
+				}
+				return n;
+			}
+			case "boolean": {
+				const lower = raw.toLowerCase();
+				if (lower === "true" || lower === "1" || lower === "") return true;
+				if (lower === "false" || lower === "0") return false;
+				throw new Error(`--${key}: expected boolean, got "${raw}"`);
+			}
+			case "object":
+				throw new Error(`--${key}: nested objects are not supported as shell flags — use JSON form`);
+			default:
+				return raw;
+		}
+	}
+
+	function assign(key: string, rawValue: string | undefined, isBooleanFlag: boolean): void {
+		const type = getType(key);
+
+		if (type === "array") {
+			const itemType = getItemType(key);
+			const pieces =
+				rawValue === undefined
+					? [""]
+					: rawValue
+							.split(",")
+							.map((s) => s.trim())
+							.filter((s) => s.length > 0);
+			const coerced = pieces.map((p) => coerceScalar(key, p, itemType));
+			const existing = result[key];
+			if (Array.isArray(existing)) {
+				existing.push(...coerced);
+			} else {
+				result[key] = coerced;
+			}
+			return;
+		}
+
+		if (seen.has(key)) {
+			throw new Error(`--${key}: specified more than once (use comma-separated values for array fields)`);
+		}
+		seen.add(key);
+
+		if (isBooleanFlag) {
+			result[key] = true;
+			return;
+		}
+
+		if (rawValue === undefined) {
+			throw new Error(`--${key}: expected value`);
+		}
+
+		result[key] = coerceScalar(key, rawValue, type);
+	}
+
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i] ?? "";
+
+		if (!token.startsWith("--")) {
+			throw new Error(`unexpected positional argument "${token}" — use --field=value form`);
+		}
+
+		const body = token.slice(2);
+		if (body.length === 0) {
+			throw new Error('unexpected bare "--" separator');
+		}
+
+		const eqIdx = body.indexOf("=");
+		let key: string;
+		let inlineValue: string | undefined;
+		if (eqIdx === -1) {
+			key = body;
+			inlineValue = undefined;
+		} else {
+			key = body.slice(0, eqIdx);
+			inlineValue = body.slice(eqIdx + 1);
+		}
+
+		// --no-key form: only treat as negation when `key` (without "no-") is a known boolean
+		if (key.startsWith("no-") && inlineValue === undefined) {
+			const bareKey = key.slice(3);
+			if (getType(bareKey) === "boolean") {
+				if (seen.has(bareKey)) {
+					throw new Error(`--${bareKey}: specified more than once`);
+				}
+				seen.add(bareKey);
+				result[bareKey] = false;
+				continue;
+			}
+		}
+
+		const type = getType(key);
+		const isBooleanField = type === "boolean";
+
+		if (inlineValue !== undefined) {
+			assign(key, inlineValue, false);
+			continue;
+		}
+
+		// No inline value — peek at next token. Booleans without a value mean "true".
+		const next = tokens[i + 1];
+		const nextLooksLikeFlag = next?.startsWith("--") === true;
+		if (isBooleanField && (next === undefined || nextLooksLikeFlag)) {
+			assign(key, undefined, true);
+			continue;
+		}
+
+		if (next === undefined || nextLooksLikeFlag) {
+			throw new Error(`--${key}: expected value`);
+		}
+
+		i++;
+		assign(key, next, false);
+	}
+
+	return result;
+}