@iicp/client 0.7.38 → 0.7.40

package/README.md

@@ -73,6 +73,24 @@ const result = await client.submit({
 
 ---
 
+## Use as a local API proxy (OpenAI / Ollama / Anthropic compat)
+
+Run a local gateway that speaks the OpenAI, Ollama, and Anthropic HTTP APIs and routes
+every request across the IICP mesh — point any tool you already use at it, no code changes.
+
+```bash
+npm i -g @iicp/client
+iicp-node proxy                       # → http://127.0.0.1:9483
+
+export OPENAI_BASE_URL=http://127.0.0.1:9483/v1   # OpenAI SDK / LangChain / Cursor / liteLLM
+export OLLAMA_HOST=http://127.0.0.1:9483          # Open WebUI / Continue.dev / aider / Jan
+```
+
+Loopback-only consumer (never registers with the directory), built on Node's `http` (no
+extra runtime dependency). Override the port with `--port` / `IICP_PROXY_PORT`; co-host
+next to a node with `iicp-node serve --with-proxy`. Every response carries
+`Server: iicp-proxy`. Full guide: <https://iicp.network/docs/proxy>
+
 ## Configuration
 
 ```typescript
@@ -352,7 +370,7 @@ Conformance tier: `iicp:sdk:v1` (spec S.14) · [Request a badge](https://iicp.ne
 ```bash
 npm install        # install deps
 npm run typecheck  # tsc strict
-npm test           # 224 unit tests
+npm test           # run the unit suite
 npm run build      # emit to dist/
 ```
 

package/dist/cli.d.ts

@@ -21,6 +21,7 @@ export interface ServeOpts {
     relayWorkerEndpoint: string;
     node: string;
     logDir?: string;
+    withProxy?: boolean;
 }
 export declare function applySavedNode(opts: ServeOpts, saved: NodeIdentity): ServeOpts;
 /**

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAuCA,OAAO,EAcL,KAAK,YAAY,EAClB,MAAM,eAAe,CAAC;AAGvB,MAAM,WAAW,SAAS;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,qGAAqG;IACrG,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,EAAE,OAAO,CAAC;IAC1B,KAAK,EAAE,OAAO,CAAC;IACf,aAAa,EAAE,OAAO,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAsXD,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,GAAG,SAAS,CAqB9E;AA6lBD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CA+D5D;AA6RD,wBAAsB,IAAI,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,MAAM,CAAC,CAgGlF"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAwCA,OAAO,EAcL,KAAK,YAAY,EAClB,MAAM,eAAe,CAAC;AAGvB,MAAM,WAAW,SAAS;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,qGAAqG;IACrG,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,EAAE,OAAO,CAAC;IAC1B,KAAK,EAAE,OAAO,CAAC;IACf,aAAa,EAAE,OAAO,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAkaD,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,GAAG,SAAS,CAqB9E;AAuoBD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CA+D5D;AAmZD,wBAAsB,IAAI,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBlF"}

package/dist/cli.js

@@ -33,8 +33,9 @@ const node_js_1 = require("./node.js");
 const client_js_1 = require("./client.js");
 const node_log_js_1 = require("./node_log.js");
 const cip_policy_js_1 = require("./cip_policy.js");
+const index_js_1 = require("./proxy/index.js");
 const instance_lock_js_1 = require("./instance_lock.js");
-const index_js_1 = require("./backends/index.js");
+const index_js_2 = require("./backends/index.js");
 const identity_js_1 = require("./identity.js");
 const delegation_js_1 = require("./delegation.js");
 function envOr(name, fallback) {
@@ -62,6 +63,7 @@ function printHelp() {
         `  serve                      Register and serve a node\n` +
         `  query <prompt>             Discover mesh nodes and submit a chat task\n` +
         `  credits                    Show this node's earned / spent / balance credits\n` +
+        `  proxy                      Run the local OpenAI/Ollama/Anthropic-compat gateway (loopback; no registration)\n` +
         `  operator rename <name>     Change your public display_name (signed by your operator key)\n` +
         `  operator encrypt           Password-encrypt the operator secret at rest ($IICP_OPERATOR_PASSPHRASE)\n` +
         `  operator decrypt           Remove at-rest encryption of the operator secret\n\n` +
@@ -82,8 +84,13 @@ function printHelp() {
         `  --port N                   IICP_PORT (default 9484)\n` +
         `  --host HOST                IICP_HOST (default :: — dual-stack IPv4+IPv6)\n` +
         `  --skip-registration        IICP_SKIP_REGISTRATION — register-free dev mode\n` +
-        `  --auto-detect-nat          IICP_AUTO_DETECT_NAT — run NAT detection at startup\n` +
-        `  --external-ip-probe-url U  IICP_EXTERNAL_IP_PROBE_URL — fallback IPv4 probe\n\n` +
+        `  --force                    IICP_FORCE — take over the single-instance lock for this node_id\n` +
+        `  --auto-detect-nat          IICP_AUTO_DETECT_NAT — run NAT detection at startup (default on)\n` +
+        `  --no-auto-detect-nat       disable NAT detection at startup\n` +
+        `  --external-ip-probe-url U  IICP_EXTERNAL_IP_PROBE_URL — fallback IPv4 probe\n` +
+        `  --relay-worker-endpoint H  IICP_RELAY_WORKER_ENDPOINT — <host>:<port> of a relay node (R2 last-resort)\n` +
+        `  --log-dir DIR              IICP_LOG_DIR — directory for persistent log files (<node_id>.log + events.jsonl)\n` +
+        `  --with-proxy               IICP_WITH_PROXY — also run the loopback compat proxy (127.0.0.1:9483) in-process\n\n` +
         `query optional:\n` +
         `  --directory-url URL        IICP_DIRECTORY_URL (default https://iicp.network/api)\n` +
         `  --intent URN               IICP_INTENT (default urn:iicp:intent:llm:chat:v1)\n` +
@@ -91,6 +98,42 @@ function printHelp() {
         `  --max-tokens N             Limit response length\n` +
         `  --timeout-ms N             Request timeout (default 60000)\n`);
 }
+/**
+ * Thrown by safeParseArgs / port parsing to signal a clean, user-facing CLI error.
+ * main() catches it and prints a one-line `ERROR:` (exit 2) — never a raw stack trace.
+ */
+class CliError extends Error {
+}
+/**
+ * Wrap node:util parseArgs so unknown options / bad values surface as a friendly
+ * `ERROR: unknown option '--x'` (exit 2) instead of a raw ERR_PARSE_ARGS_* stack trace.
+ */
+function safeParseArgs(config) {
+    try {
+        return (0, node_util_1.parseArgs)(config);
+    }
+    catch (exc) {
+        const e = exc;
+        if (e?.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION") {
+            const m = /Unknown option '([^']*)'/.exec(e.message ?? "");
+            throw new CliError(`unknown option '${m?.[1] ?? "?"}'`);
+        }
+        if (e?.code === "ERR_PARSE_ARGS_INVALID_OPTION_VALUE" || e?.code === "ERR_PARSE_ARGS_UNEXPECTED_POSITIONAL") {
+            throw new CliError(e.message ?? "invalid argument");
+        }
+        throw new CliError(e?.message ?? String(exc));
+    }
+}
+/** Parse a port flag/env into a number, raising a friendly CliError on a non-numeric value. */
+function parsePort(raw, fallback) {
+    if (raw === undefined)
+        return fallback;
+    const n = parseInt(raw, 10);
+    if (!Number.isInteger(n) || n < 0 || n > 65535) {
+        throw new CliError("--port must be a number between 0 and 65535");
+    }
+    return n;
+}
 async function checkDependencies(backendUrl) {
     const out = [];
     // 1) Backend reachability
@@ -413,6 +456,18 @@ async function runServe(opts) {
             allowCoordinator: true,
         });
     }
+    // 2-C: co-host the compat proxy on loopback alongside the node, supervised so a
+    // proxy failure logs but never drops the network-facing node. Forced to 127.0.0.1.
+    if (opts.withProxy) {
+        const pport = envInt("IICP_PROXY_PORT", 9483);
+        const pclient = new client_js_1.IicpClient({
+            directory_url: opts.directoryUrl,
+            region: opts.region,
+        });
+        const pserver = (0, index_js_1.createProxyServer)(pclient);
+        pserver.on("error", (e) => process.stderr.write(`co-hosted proxy error (node continues): ${String(e)}\n`));
+        pserver.listen(pport, "127.0.0.1", () => process.stdout.write(`co-hosted proxy → http://127.0.0.1:${pport} (OpenAI/Ollama/Anthropic compat)\n`));
+    }
     if (opts.node) {
         const saved = (0, identity_js_1.loadNode)(opts.node);
         if (!saved) {
@@ -421,6 +476,13 @@ async function runServe(opts) {
         }
         opts = applySavedNode(opts, saved);
     }
+    // #410/#414 — built-in backend-url fallback applied LAST (after flag/env/saved-config),
+    // so a bare `serve --model x` works without --backend-url. An `anthropic` backend
+    // defaults to the Anthropic API, not localhost Ollama. Mirrors Python cli.py ~704.
+    if (!opts.backendUrl) {
+        opts.backendUrl =
+            opts.backendType === "anthropic" ? "https://api.anthropic.com" : "http://localhost:11434";
+    }
     // Onboarding: if no --model given, auto-select the first model the backend advertises
     // (Ollama /api/tags) so a bare `iicp-node serve` just works (parity with Rust/Python).
     if (!opts.model && opts.backendUrl) {
@@ -444,8 +506,8 @@ async function runServe(opts) {
         process.stderr.write("ERROR: --model is required (--backend-url defaults to http://localhost:11434). Set IICP_BACKEND_MODEL, or use --node NAME.\n");
         return 2;
     }
-    if (!index_js_1.BACKEND_TYPES.includes(opts.backendType)) {
-        process.stderr.write(`ERROR: --backend-type must be one of ${JSON.stringify(index_js_1.BACKEND_TYPES)}.\n`);
+    if (!index_js_2.BACKEND_TYPES.includes(opts.backendType)) {
+        process.stderr.write(`ERROR: --backend-type must be one of ${JSON.stringify(index_js_2.BACKEND_TYPES)}.\n`);
         return 2;
     }
     const nodeId = (opts.nodeId || (0, node_crypto_1.randomUUID)()).slice(0, 36);
@@ -610,7 +672,7 @@ async function runServe(opts) {
         const t = opts.backendUrl.replace(/\/$/, "");
         return t.endsWith("/v1") ? t : `${t}/v1`;
     })();
-    const handler = (0, index_js_1.getBackendHandler)(opts.backendType, {
+    const handler = (0, index_js_2.getBackendHandler)(opts.backendType, {
         baseUrl: _baseUrl,
         model: opts.model,
         // #5 — Bearer key for auth'd backends (LM Studio, hosted). Empty/undefined = no header.
@@ -775,8 +837,19 @@ async function runServe(opts) {
     void node_crypto_1.randomUUID;
     return 0;
 }
+function printQueryHelp() {
+    process.stdout.write(`usage: iicp-node query <prompt> [options]\n\n` +
+        `Discover mesh nodes and submit a chat task.\n\n` +
+        `options:\n` +
+        `  --directory-url URL        IICP_DIRECTORY_URL (default https://iicp.network/api)\n` +
+        `  --intent URN               IICP_INTENT (default urn:iicp:intent:llm:chat:v1)\n` +
+        `  --model NAME               Pin to a specific model on the remote node\n` +
+        `  --max-tokens N             Limit response length\n` +
+        `  --timeout-ms N             Request timeout in milliseconds (default 60000)\n` +
+        `  -h, --help                 Show this help and exit\n`);
+}
 async function runQuery(argv) {
-    const { values, positionals } = (0, node_util_1.parseArgs)({
+    const { values, positionals } = safeParseArgs({
         args: argv,
         options: {
             "directory-url": { type: "string" },
@@ -784,13 +857,17 @@ async function runQuery(argv) {
             model: { type: "string" },
             "max-tokens": { type: "string" },
             "timeout-ms": { type: "string" },
+            help: { type: "boolean", short: "h" },
         },
         allowPositionals: true,
-        strict: false,
     });
+    if (values.help) {
+        printQueryHelp();
+        return 0;
+    }
     const prompt = positionals.join(" ").trim();
     if (!prompt) {
-        process.stderr.write("Usage: iicp-node query <prompt> [flags]\n");
+        printQueryHelp();
         return 1;
     }
     const directoryUrl = values["directory-url"] ??
@@ -1043,8 +1120,22 @@ async function verifyCreditAwards(directoryUrl, nodeId) {
  * directory (not the local config), so editing the saved file cannot inflate them;
  * `reconciles` flags a ledger that does not add up.
  */
+function printCreditsHelp() {
+    process.stdout.write(`usage: iicp-node credits [options]\n\n` +
+        `Show this node's earned / spent / balance credits (authenticated from the directory).\n\n` +
+        `options:\n` +
+        `  --node NAME                Load token + node_id from ~/.iicp/nodes/<NAME>.json\n` +
+        `  --node-id ID               Node id (if not using --node)\n` +
+        `  --token TOKEN              Node token (env IICP_NODE_TOKEN)\n` +
+        `  --directory-url URL        IICP directory base URL (defaults to saved node / env / iicp.network)\n` +
+        `  --json                     Print the raw summary JSON\n` +
+        `  --verify                   Cryptographically audit each award against the signed CREDIT_AWARD log\n` +
+        `  -h, --help                 Show this help and exit\n\n` +
+        `With no --node / --node-id and exactly one saved node (or a node named 'default'),\n` +
+        `that node is used automatically.\n`);
+}
 async function runCredits(argv) {
-    const { values } = (0, node_util_1.parseArgs)({
+    const { values } = safeParseArgs({
         args: argv,
         options: {
             node: { type: "string" },
@@ -1053,13 +1144,37 @@ async function runCredits(argv) {
             "directory-url": { type: "string" },
             json: { type: "boolean" },
             verify: { type: "boolean" },
+            help: { type: "boolean", short: "h" },
         },
         allowPositionals: false,
     });
-    const nodeName = values["node"];
+    if (values.help) {
+        printCreditsHelp();
+        return 0;
+    }
+    let nodeName = values["node"];
     let directoryUrl = values["directory-url"];
     let nodeId = values["node-id"];
     let token = values["token"] ?? process.env["IICP_NODE_TOKEN"];
+    // #8 — no --node / --node-id: if exactly one saved node (or a 'default' node) exists,
+    // use it automatically; otherwise emit a clear error listing the saved node names.
+    if (!nodeName && !nodeId) {
+        const saved = (0, identity_js_1.listNodes)();
+        if (saved.length === 1) {
+            nodeName = saved[0].name;
+        }
+        else if (saved.some((n) => n.name === "default")) {
+            nodeName = "default";
+        }
+        else if (saved.length === 0) {
+            process.stderr.write("ERROR: no saved nodes — run `iicp-node init` / `serve` first, or pass --node-id ID.\n");
+            return 1;
+        }
+        else {
+            process.stderr.write(`ERROR: multiple saved nodes — pass --node NAME (one of: ${saved.map((n) => n.name).join(", ")}) or --node-id ID.\n`);
+            return 1;
+        }
+    }
     if (nodeName) {
         const saved = (0, identity_js_1.loadNode)(nodeName);
         if (!saved) {
@@ -1231,21 +1346,44 @@ async function runOperatorDecrypt() {
  * signed call updates the single operator record, reflected on every node + the leaderboard.
  * Updates the local operator.json on success. Never sends the secret/contact.
  */
+function printOperatorHelp() {
+    process.stdout.write(`usage: iicp-node operator <subcommand> [options]\n\n` +
+        `Manage your operator identity.\n\n` +
+        `subcommands:\n` +
+        `  rename <name>              Change your public display_name (signed by your operator key)\n` +
+        `  encrypt                    Password-encrypt the operator secret at rest ($IICP_OPERATOR_PASSPHRASE)\n` +
+        `  decrypt                    Remove at-rest encryption of the operator secret\n\n` +
+        `operator rename options:\n` +
+        `  --directory-url URL        IICP directory base URL (defaults to env / iicp.network)\n` +
+        `  -h, --help                 Show this help and exit\n`);
+}
 async function runOperator(argv) {
     const sub = argv[0];
+    if (sub === undefined || sub === "--help" || sub === "-h") {
+        printOperatorHelp();
+        return sub === undefined ? 2 : 0;
+    }
     if (sub === "encrypt")
         return runOperatorEncrypt();
     if (sub === "decrypt")
         return runOperatorDecrypt();
     if (sub !== "rename") {
-        process.stderr.write(`unknown operator subcommand: ${sub ?? "(none)"}\n`);
+        process.stderr.write(`unknown operator subcommand: ${sub}\n`);
+        printOperatorHelp();
         return 2;
     }
-    const { values, positionals } = (0, node_util_1.parseArgs)({
+    const { values, positionals } = safeParseArgs({
         args: argv.slice(1),
-        options: { "directory-url": { type: "string" } },
+        options: {
+            "directory-url": { type: "string" },
+            help: { type: "boolean", short: "h" },
+        },
         allowPositionals: true,
     });
+    if (values.help) {
+        printOperatorHelp();
+        return 0;
+    }
     const name = positionals[0];
     // eslint-disable-next-line no-control-regex
     if (!name || name.length > 64 || /[\u0000-\u001f\u007f]/.test(name)) {
@@ -1299,8 +1437,50 @@ async function runOperator(argv) {
     process.stdout.write(`Renamed operator display_name to ${JSON.stringify(op.display_name)}.\n`);
     return 0;
 }
+// ── proxy (ADR-050) — local compat gateway; consumer, loopback, no registration ──
+function printProxyHelp() {
+    process.stdout.write(`usage: iicp-node proxy [options]\n\n` +
+        `Run the local OpenAI/Ollama/Anthropic-compat gateway (consumer; loopback;\n` +
+        `does NOT register with the directory).\n\n` +
+        `options:\n` +
+        `  --port N                   Listen port (env IICP_PROXY_PORT, default 9483)\n` +
+        `  --host HOST                Bind host (env IICP_PROXY_HOST, default 127.0.0.1 — loopback)\n` +
+        `  --directory-url URL        IICP_DIRECTORY_URL (default https://iicp.network/api)\n` +
+        `  --region REGION            Preferred region (env IICP_PROXY_PREFERRED_REGION)\n` +
+        `  --token TOKEN              Node token (env IICP_NODE_TOKEN)\n` +
+        `  -h, --help                 Show this help and exit\n`);
+}
+async function runProxyCmd(argv) {
+    const { values } = safeParseArgs({
+        args: argv,
+        allowPositionals: false,
+        options: {
+            port: { type: "string" },
+            host: { type: "string" },
+            "directory-url": { type: "string" },
+            region: { type: "string" },
+            token: { type: "string" },
+            help: { type: "boolean", short: "h" },
+        },
+    });
+    if (values.help) {
+        printProxyHelp();
+        return 0;
+    }
+    const port = values.port !== undefined
+        ? parsePort(values.port, 9483)
+        : parsePort(process.env["IICP_PROXY_PORT"], 9483);
+    const host = values.host ?? envOr("IICP_PROXY_HOST", "127.0.0.1");
+    return (0, index_js_1.runProxy)({
+        host,
+        port,
+        directoryUrl: values["directory-url"] ?? envOr("IICP_DIRECTORY_URL", "https://iicp.network/api"),
+        region: values.region ?? envOr("IICP_PROXY_PREFERRED_REGION"),
+        token: values.token ?? envOr("IICP_NODE_TOKEN"),
+    });
+}
 async function main(argv = process.argv.slice(2)) {
-    if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
+    if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h" || argv[0] === "help") {
         printHelp();
         return argv.length === 0 ? 2 : 0;
     }
@@ -1308,6 +1488,19 @@ async function main(argv = process.argv.slice(2)) {
         process.stdout.write(`iicp-node ${SDK_VERSION}\n`);
         return 0;
     }
+    try {
+        return await dispatch(argv);
+    }
+    catch (exc) {
+        if (exc instanceof CliError) {
+            process.stderr.write(`ERROR: ${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
+}
+/** Command dispatch — separated so main() can wrap parse failures as clean CliError output. */
+async function dispatch(argv) {
     const cmd = argv[0];
     if (cmd === "init")
         return runInit();
@@ -1319,12 +1512,14 @@ async function main(argv = process.argv.slice(2)) {
         return runCredits(argv.slice(1));
     if (cmd === "operator")
         return runOperator(argv.slice(1));
+    if (cmd === "proxy")
+        return runProxyCmd(argv.slice(1));
     if (cmd !== "serve") {
         process.stderr.write(`unknown command: ${cmd}\n`);
         printHelp();
         return 2;
     }
-    const { values } = (0, node_util_1.parseArgs)({
+    const { values } = safeParseArgs({
         args: argv.slice(1),
         options: {
             node: { type: "string" },
@@ -1343,9 +1538,13 @@ async function main(argv = process.argv.slice(2)) {
             "skip-registration": { type: "boolean" },
             force: { type: "boolean" },
             "auto-detect-nat": { type: "boolean" },
+            // Parity with Python's BooleanOptionalAction: an explicit off-switch for NAT
+            // detection (`--auto-detect-nat=false` can't work — it's a no-arg boolean).
+            "no-auto-detect-nat": { type: "boolean" },
             "external-ip-probe-url": { type: "string" },
             "relay-worker-endpoint": { type: "string" },
             "log-dir": { type: "string" },
+            "with-proxy": { type: "boolean" },
             help: { type: "boolean", short: "h" },
         },
         allowPositionals: false,
@@ -1371,21 +1570,27 @@ async function main(argv = process.argv.slice(2)) {
             : envInt("IICP_MAX_CONCURRENT", 4),
         nodeId: values["node-id"] ?? envOr("IICP_NODE_ID") ?? "",
         port: values.port !== undefined
-            ? parseInt(values.port, 10)
-            : envInt("IICP_PORT", 9484),
+            ? parsePort(values.port, 9484)
+            : parsePort(process.env["IICP_PORT"], 9484),
         host: values.host ?? envOr("IICP_HOST", "::"),
         skipRegistration: Boolean(values["skip-registration"]) || envBool("IICP_SKIP_REGISTRATION"),
         force: Boolean(values["force"]) || envBool("IICP_FORCE"),
-        // Default ON — matches Python CLI behaviour; operator must set IICP_AUTO_DETECT_NAT=false to opt out.
-        autoDetectNat: values["auto-detect-nat"] !== undefined
-            ? Boolean(values["auto-detect-nat"])
-            : (process.env.IICP_AUTO_DETECT_NAT !== undefined ? envBool("IICP_AUTO_DETECT_NAT") : true),
+        // Default ON — matches Python CLI behaviour. Off-switch precedence: explicit
+        // --no-auto-detect-nat > --auto-detect-nat > IICP_AUTO_DETECT_NAT env > default on.
+        autoDetectNat: values["no-auto-detect-nat"]
+            ? false
+            : values["auto-detect-nat"] !== undefined
+                ? Boolean(values["auto-detect-nat"])
+                : process.env.IICP_AUTO_DETECT_NAT !== undefined
+                    ? envBool("IICP_AUTO_DETECT_NAT")
+                    : true,
         // Default to api.ipify.org so FRITZ!Box/CGNAT detection works out of the box.
         externalIpProbeUrl: values["external-ip-probe-url"]
             ?? envOr("IICP_EXTERNAL_IP_PROBE_URL")
             ?? "https://api.ipify.org",
         relayWorkerEndpoint: values["relay-worker-endpoint"] ?? envOr("IICP_RELAY_WORKER_ENDPOINT") ?? "",
         logDir: values["log-dir"] ?? envOr("IICP_LOG_DIR"),
+        withProxy: Boolean(values["with-proxy"]) || envBool("IICP_WITH_PROXY"),
     };
     return runServe(opts);
 }
@@ -1394,8 +1599,9 @@ if (require.main === module) {
     main()
         .then((code) => process.exit(code))
         .catch((err) => {
-        // eslint-disable-next-line no-console
-        console.error(err);
+        // Clean one-line error — never dump a raw Node stack trace at the user.
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`ERROR: ${msg}\n`);
         process.exit(1);
     });
 }