From bb4815f069c374a57fac3428e22f86f552096eef Mon Sep 17 00:00:00 2001 From: lodekeeper Date: Thu, 2 Jul 2026 09:35:20 +0000 Subject: [PATCH 01/19] feat(cli): support nested maps in rc config file MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The --rcConfig file required nested options to be written as dotted keys (e.g. rest.address). Flatten nested maps to dotted keys before handing the parsed file to yargs, so both nested maps and dotted keys are accepted. Arrays are preserved (not flattened by index) and already-dotted keys pass through unchanged, keeping existing configs fully backward compatible. 🤖 Generated with AI assistance --- packages/cli/src/options/globalOptions.ts | 4 +- packages/cli/src/util/object.ts | 25 ++++++++ packages/cli/test/unit/util/object.test.ts | 69 ++++++++++++++++++++++ 3 files changed, 96 insertions(+), 2 deletions(-) create mode 100644 packages/cli/test/unit/util/object.test.ts diff --git a/packages/cli/src/options/globalOptions.ts b/packages/cli/src/options/globalOptions.ts index 795b4417e235..8450106a4d52 100644 --- a/packages/cli/src/options/globalOptions.ts +++ b/packages/cli/src/options/globalOptions.ts @@ -1,7 +1,7 @@ import {ACTIVE_PRESET} from "@lodestar/params"; import {CliCommandOptions} from "@lodestar/utils"; import {NetworkName, networkNames} from "../networks/index.js"; -import {readFile} from "../util/index.js"; +import {flattenObject, readFile} from "../util/index.js"; import {IParamsArgs, paramsOptions} from "./paramsOptions.js"; type GlobalSingleArgs = { @@ -70,7 +70,7 @@ const globalSingleOptions: CliCommandOptions = { export const rcConfigOption: [string, string, (configPath: string) => Record] = [ "rcConfig", globalSingleOptions.rcConfig.description as string, - (configPath: string): Record => readFile(configPath, ["json", "yml", "yaml"]), + (configPath: string): Record => flattenObject(readFile(configPath, ["json", "yml", "yaml"])), ]; export type GlobalArgs = GlobalSingleArgs & IParamsArgs; diff --git a/packages/cli/src/util/object.ts b/packages/cli/src/util/object.ts index efd9bcfd4977..70f0938ce0bb 100644 --- a/packages/cli/src/util/object.ts +++ b/packages/cli/src/util/object.ts @@ -13,3 +13,28 @@ export function removeUndefinedRecursive(obj: T) } return obj as RecursivePartial; } + +/** + * Flattens a nested object into a single-level object with dot-notation keys. + * + * Allows the rc config file to be written with either nested maps or dotted keys, e.g. + * `{rest: {address: "0.0.0.0"}}` and `{"rest.address": "0.0.0.0"}` both flatten to + * `{"rest.address": "0.0.0.0"}`, matching how CLI options are registered (`dot-notation` + * is disabled in yargs). Arrays are preserved as values (not flattened by index) so + * array options like `rest.namespace` or `bootnodes` keep working. + * + * If the same option is provided in both nested and dotted form, the value that appears + * last in the file wins. + */ +export function flattenObject(obj: Record, parentKey?: string): Record { + const flattened: Record = {}; + for (const [key, value] of Object.entries(obj)) { + const prefixedKey = parentKey ? `${parentKey}.${key}` : key; + if (value != null && typeof value === "object" && !Array.isArray(value)) { + Object.assign(flattened, flattenObject(value as Record, prefixedKey)); + } else { + flattened[prefixedKey] = value; + } + } + return flattened; +} diff --git a/packages/cli/test/unit/util/object.test.ts b/packages/cli/test/unit/util/object.test.ts new file mode 100644 index 000000000000..1a192d46092d --- /dev/null +++ b/packages/cli/test/unit/util/object.test.ts @@ -0,0 +1,69 @@ +import {describe, expect, it} from "vitest"; +import {flattenObject} from "../../../src/util/object.js"; + +describe("util / flattenObject", () => { + it("flattens nested maps into dot-notation keys", () => { + expect(flattenObject({rest: {address: "0.0.0.0", port: 9596}})).toEqual({ + "rest.address": "0.0.0.0", + "rest.port": 9596, + }); + }); + + it("leaves already-dotted keys unchanged (backwards compatible)", () => { + expect(flattenObject({"rest.address": "0.0.0.0", "rest.port": 9596})).toEqual({ + "rest.address": "0.0.0.0", + "rest.port": 9596, + }); + }); + + it("preserves arrays as values instead of flattening them by index", () => { + expect(flattenObject({rest: {namespace: ["beacon", "config"]}, bootnodes: ["enr:-a", "enr:-b"]})).toEqual({ + "rest.namespace": ["beacon", "config"], + bootnodes: ["enr:-a", "enr:-b"], + }); + }); + + it("preserves primitive value types (boolean, number, null)", () => { + expect(flattenObject({metrics: {enabled: true, port: 8008, host: null}})).toEqual({ + "metrics.enabled": true, + "metrics.port": 8008, + "metrics.host": null, + }); + }); + + it("supports nested and dotted keys mixed in the same object", () => { + expect(flattenObject({rest: {address: "0.0.0.0"}, "rest.port": 9596, network: "hoodi"})).toEqual({ + "rest.address": "0.0.0.0", + "rest.port": 9596, + network: "hoodi", + }); + }); + + it("flattens arbitrarily deep nesting", () => { + expect(flattenObject({a: {b: {c: 1}}})).toEqual({"a.b.c": 1}); + }); + + it("returns top-level scalars untouched", () => { + expect(flattenObject({network: "hoodi", port: 9000, rest: true})).toEqual({ + network: "hoodi", + port: 9000, + rest: true, + }); + }); + + it("last definition wins when a key is given in both nested and dotted form", () => { + expect(flattenObject({"rest.address": "first", rest: {address: "second"}})).toEqual({ + "rest.address": "second", + }); + }); + + it("keeps arrays of objects intact as a single value", () => { + expect(flattenObject({chain: {trustedSetup: [{index: 0}, {index: 1}]}})).toEqual({ + "chain.trustedSetup": [{index: 0}, {index: 1}], + }); + }); + + it("drops empty nested maps and keeps sibling keys", () => { + expect(flattenObject({rest: {}, network: "hoodi"})).toEqual({network: "hoodi"}); + }); +}); From 5684d869fb268f5a583d2579a39c398a736d5f67 Mon Sep 17 00:00:00 2001 From: lodekeeper Date: Thu, 2 Jul 2026 09:41:20 +0000 Subject: [PATCH 02/19] docs(cli): add rcConfig example to CLI reference MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a small nested-map example to the --rcConfig option so it renders in the generated CLI reference (beacon-cli#--rcconfig), rather than a dedicated docs page. The example field is docs-only and does not affect --help output. 🤖 Generated with AI assistance --- packages/cli/src/options/globalOptions.ts | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/packages/cli/src/options/globalOptions.ts b/packages/cli/src/options/globalOptions.ts index 8450106a4d52..47a28c524a51 100644 --- a/packages/cli/src/options/globalOptions.ts +++ b/packages/cli/src/options/globalOptions.ts @@ -51,6 +51,18 @@ const globalSingleOptions: CliCommandOptions = { rcConfig: { description: "RC file to supplement command line args, accepted formats: .yml, .yaml, .json", type: "string", + example: { + description: `Supply CLI options from a file. Options can be written as nested maps or dotted keys: + +\`\`\`yaml +# beacon.config.yaml +network: hoodi +rest: + address: 0.0.0.0 + port: 9596 +\`\`\``, + command: "beacon --rcConfig beacon.config.yaml", + }, }, supernode: { From 7f8349ab22b1af2012f68e185bd20fc0435cdca4 Mon Sep 17 00:00:00 2001 From: lodekeeper Date: Thu, 2 Jul 2026 17:40:18 +0000 Subject: [PATCH 03/19] fix(cli): harden flattenObject against non-plain and prototype-polluting inputs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address Gemini review on #9578: guard flattenObject with isPlainObject (reused from @lodestar/utils) so non-object input (an empty/scalar rc config makes readFile return undefined/a primitive) returns {} instead of throwing on Object.entries, and non-plain object values (Date/Buffer/typed arrays/arrays) are kept as leaf values rather than silently dropped or mis-flattened. Skip the __proto__ key as prototype-pollution defense-in-depth; objects whose own `constructor` shadows the function are already rejected by isPlainObject. Adds regression tests for all three cases. 🤖 Generated with AI assistance --- packages/cli/src/util/object.ts | 16 ++++++++++++++-- packages/cli/test/unit/util/object.test.ts | 19 +++++++++++++++++++ 2 files changed, 33 insertions(+), 2 deletions(-) diff --git a/packages/cli/src/util/object.ts b/packages/cli/src/util/object.ts index 70f0938ce0bb..42c06bae0c3d 100644 --- a/packages/cli/src/util/object.ts +++ b/packages/cli/src/util/object.ts @@ -1,4 +1,4 @@ -import {RecursivePartial} from "@lodestar/utils"; +import {RecursivePartial, isPlainObject} from "@lodestar/utils"; /** * Removes (mutates) all properties with a value === undefined, recursively @@ -27,10 +27,22 @@ export function removeUndefinedRecursive(obj: T) * last in the file wins. */ export function flattenObject(obj: Record, parentKey?: string): Record { + // Guard non-plain input: an empty or scalar rc config file makes `readFile` return `undefined` + // or a primitive, which would otherwise throw on `Object.entries`. `isPlainObject` also rejects + // arrays and class instances (Date, Buffer, typed arrays); those are handled as leaf values below. + if (!isPlainObject(obj)) { + return {}; + } const flattened: Record = {}; for (const [key, value] of Object.entries(obj)) { + // Skip prototype-polluting keys as defense-in-depth (config files can be semi-trusted). + if (key === "__proto__") { + continue; + } const prefixedKey = parentKey ? `${parentKey}.${key}` : key; - if (value != null && typeof value === "object" && !Array.isArray(value)) { + // Only recurse into plain objects; arrays and class instances (e.g. Date) are kept as leaf + // values — recursing into them would silently drop or mis-flatten them. + if (isPlainObject(value)) { Object.assign(flattened, flattenObject(value as Record, prefixedKey)); } else { flattened[prefixedKey] = value; diff --git a/packages/cli/test/unit/util/object.test.ts b/packages/cli/test/unit/util/object.test.ts index 1a192d46092d..e6c3d33e7fe8 100644 --- a/packages/cli/test/unit/util/object.test.ts +++ b/packages/cli/test/unit/util/object.test.ts @@ -66,4 +66,23 @@ describe("util / flattenObject", () => { it("drops empty nested maps and keeps sibling keys", () => { expect(flattenObject({rest: {}, network: "hoodi"})).toEqual({network: "hoodi"}); }); + + it("returns an empty object for non-plain input instead of throwing", () => { + // e.g. an empty or scalar rc config file makes readFile return undefined / a primitive + expect(flattenObject(undefined as unknown as Record)).toEqual({}); + expect(flattenObject(null as unknown as Record)).toEqual({}); + expect(flattenObject("network: hoodi" as unknown as Record)).toEqual({}); + expect(flattenObject(42 as unknown as Record)).toEqual({}); + }); + + it("skips the __proto__ key and does not pollute Object.prototype", () => { + const malicious = JSON.parse('{"__proto__": {"polluted": true}, "network": "hoodi"}'); + expect(flattenObject(malicious)).toEqual({network: "hoodi"}); + expect(({} as Record).polluted).toBeUndefined(); + }); + + it("keeps non-plain object values (e.g. Date) as leaves instead of dropping them", () => { + const genesisTime = new Date("2024-01-01T00:00:00Z"); + expect(flattenObject({chain: {genesisTime}})).toEqual({"chain.genesisTime": genesisTime}); + }); }); From 69000790de6d6f7f2578bb40c26ac7c6cf7c7939 Mon Sep 17 00:00:00 2001 From: lodekeeper Date: Thu, 2 Jul 2026 17:40:18 +0000 Subject: [PATCH 04/19] docs(cli): note rcConfig flag+prefix nesting caveat MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address Codex review on #9578: an option that is both a value/flag and a prefix (e.g. network, metrics, builder) can't express both the scalar and its sub-options under one nested YAML key; document that those are set with dotted keys. flattenObject itself is unchanged (it faithfully flattens valid input). 🤖 Generated with AI assistance --- packages/cli/src/options/globalOptions.ts | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/packages/cli/src/options/globalOptions.ts b/packages/cli/src/options/globalOptions.ts index 47a28c524a51..afee97919d9c 100644 --- a/packages/cli/src/options/globalOptions.ts +++ b/packages/cli/src/options/globalOptions.ts @@ -60,7 +60,9 @@ network: hoodi rest: address: 0.0.0.0 port: 9596 -\`\`\``, +\`\`\` + +Note: an option that is both a value/flag and a prefix (e.g. \`network\` with \`network.maxPeers\`, or the \`metrics\`/\`builder\` enable flags with their \`.port\` settings) can't carry both forms under one nested key — set those with dotted keys, e.g. \`metrics: true\` alongside \`metrics.port: 8008\`.`, command: "beacon --rcConfig beacon.config.yaml", }, }, From 54b1316594c5b7352f1ad00163b727a97b2617ec Mon Sep 17 00:00:00 2001 From: lodekeeper Date: Sat, 4 Jul 2026 13:51:10 +0000 Subject: [PATCH 05/19] docs(cli): clarify rcConfig flag+prefix caveat with a concrete example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Nico found the previous Note unclear. Rewrite it around a concrete case (the metrics enable flag vs its metrics.port sub-option) and show the dotted-key form in a yaml block, since YAML can't give one key both a value and nested children. 🤖 Generated with AI assistance Co-Authored-By: Claude Opus 4.8 --- packages/cli/src/options/globalOptions.ts | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/packages/cli/src/options/globalOptions.ts b/packages/cli/src/options/globalOptions.ts index afee97919d9c..f8205c4ad396 100644 --- a/packages/cli/src/options/globalOptions.ts +++ b/packages/cli/src/options/globalOptions.ts @@ -62,7 +62,13 @@ rest: port: 9596 \`\`\` -Note: an option that is both a value/flag and a prefix (e.g. \`network\` with \`network.maxPeers\`, or the \`metrics\`/\`builder\` enable flags with their \`.port\` settings) can't carry both forms under one nested key — set those with dotted keys, e.g. \`metrics: true\` alongside \`metrics.port: 8008\`.`, +A few options are both a value/flag and a prefix for other options — e.g. \`metrics\` is an on/off flag but also has sub-options like \`metrics.port\`. YAML can't give one key both a value and nested children, so configure these with dotted keys instead of nesting: + +\`\`\`yaml +# enable metrics AND set its port +metrics: true +metrics.port: 8008 +\`\`\``, command: "beacon --rcConfig beacon.config.yaml", }, }, From c2828d4399dbf5b71943f1835d51790edeed2a9e Mon Sep 17 00:00:00 2001 From: lodekeeper Date: Sat, 4 Jul 2026 18:22:34 +0000 Subject: [PATCH 06/19] feat(cli): accept nested `enabled` for on/off flags in rcConfig MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Translate `{prefix}.enabled` -> `{prefix}` after flattening the rc config, so on/off flags whose internal config nests the toggle under `.enabled` (metrics, rest, builder) can be written in the natural nested form: metrics: enabled: true port: 8008 No CLI option is registered with an `.enabled` suffix, so the rewrite is unambiguous; a bare `{prefix}` already set (mixed dotted/nested) is left as a conflict. Updates the rcConfig docs example to the nested form (drops the dotted-key caveat) and adds unit tests for the translation. Addresses nflaig review on #9578. 🤖 Generated with AI assistance Co-Authored-By: Claude Opus 4.8 --- packages/cli/src/options/globalOptions.ts | 16 +++---- packages/cli/src/util/object.ts | 34 +++++++++++++++ packages/cli/test/unit/util/object.test.ts | 50 +++++++++++++++++++++- 3 files changed, 90 insertions(+), 10 deletions(-) diff --git a/packages/cli/src/options/globalOptions.ts b/packages/cli/src/options/globalOptions.ts index f8205c4ad396..dbe691778b46 100644 --- a/packages/cli/src/options/globalOptions.ts +++ b/packages/cli/src/options/globalOptions.ts @@ -1,7 +1,7 @@ import {ACTIVE_PRESET} from "@lodestar/params"; import {CliCommandOptions} from "@lodestar/utils"; import {NetworkName, networkNames} from "../networks/index.js"; -import {flattenObject, readFile} from "../util/index.js"; +import {flattenObject, readFile, translateEnabledKeys} from "../util/index.js"; import {IParamsArgs, paramsOptions} from "./paramsOptions.js"; type GlobalSingleArgs = { @@ -60,15 +60,12 @@ network: hoodi rest: address: 0.0.0.0 port: 9596 +metrics: + enabled: true + port: 8008 \`\`\` -A few options are both a value/flag and a prefix for other options — e.g. \`metrics\` is an on/off flag but also has sub-options like \`metrics.port\`. YAML can't give one key both a value and nested children, so configure these with dotted keys instead of nesting: - -\`\`\`yaml -# enable metrics AND set its port -metrics: true -metrics.port: 8008 -\`\`\``, +For an on/off flag such as \`--metrics\`, use \`enabled\` under the nested map (\`metrics.enabled\`) or the dotted \`metrics\` key.`, command: "beacon --rcConfig beacon.config.yaml", }, }, @@ -90,7 +87,8 @@ metrics.port: 8008 export const rcConfigOption: [string, string, (configPath: string) => Record] = [ "rcConfig", globalSingleOptions.rcConfig.description as string, - (configPath: string): Record => flattenObject(readFile(configPath, ["json", "yml", "yaml"])), + (configPath: string): Record => + translateEnabledKeys(flattenObject(readFile(configPath, ["json", "yml", "yaml"]))), ]; export type GlobalArgs = GlobalSingleArgs & IParamsArgs; diff --git a/packages/cli/src/util/object.ts b/packages/cli/src/util/object.ts index 42c06bae0c3d..d77380407978 100644 --- a/packages/cli/src/util/object.ts +++ b/packages/cli/src/util/object.ts @@ -50,3 +50,37 @@ export function flattenObject(obj: Record, parentKey?: string): } return flattened; } + +/** + * Rewrites `{prefix}.enabled` keys to the bare `{prefix}` flag. + * + * Some options are exposed as an on/off boolean flag (`--metrics`, `--rest`, `--builder`) whose + * internal config shape nests the toggle under `.enabled` (e.g. `{metrics: {enabled, port}}`). This + * lets an rc config file be written in the natural nested form: + * + * ```yaml + * metrics: + * enabled: true + * port: 8008 + * ``` + * + * which {@link flattenObject} turns into `{"metrics.enabled": true, "metrics.port": 8008}`. The CLI + * registers the toggle as the bare `metrics` flag (there is no `metrics.enabled` option), so rewrite + * `{prefix}.enabled` -> `{prefix}` to match a registered option. No CLI option is registered with an + * `.enabled` suffix, so this is unambiguous. If the bare `{prefix}` key is already set (e.g. mixed + * dotted and nested forms), the `.enabled` key is left untouched so the conflict surfaces as an + * "unknown argument" error rather than being silently overridden. + */ +export function translateEnabledKeys(flattened: Record): Record { + const suffix = ".enabled"; + const translated: Record = {}; + for (const [key, value] of Object.entries(flattened)) { + const prefix = key.endsWith(suffix) ? key.slice(0, -suffix.length) : ""; + if (prefix && !(prefix in flattened)) { + translated[prefix] = value; + } else { + translated[key] = value; + } + } + return translated; +} diff --git a/packages/cli/test/unit/util/object.test.ts b/packages/cli/test/unit/util/object.test.ts index e6c3d33e7fe8..59de9bc85b36 100644 --- a/packages/cli/test/unit/util/object.test.ts +++ b/packages/cli/test/unit/util/object.test.ts @@ -1,5 +1,5 @@ import {describe, expect, it} from "vitest"; -import {flattenObject} from "../../../src/util/object.js"; +import {flattenObject, translateEnabledKeys} from "../../../src/util/object.js"; describe("util / flattenObject", () => { it("flattens nested maps into dot-notation keys", () => { @@ -86,3 +86,51 @@ describe("util / flattenObject", () => { expect(flattenObject({chain: {genesisTime}})).toEqual({"chain.genesisTime": genesisTime}); }); }); + +describe("util / translateEnabledKeys", () => { + it("rewrites `{prefix}.enabled` to the bare `{prefix}` flag", () => { + expect(translateEnabledKeys({"metrics.enabled": true, "metrics.port": 8008})).toEqual({ + metrics: true, + "metrics.port": 8008, + }); + }); + + it("translates the nested form produced by flattenObject (metrics: {enabled, port})", () => { + expect(translateEnabledKeys(flattenObject({metrics: {enabled: true, port: 8008}}))).toEqual({ + metrics: true, + "metrics.port": 8008, + }); + }); + + it("handles multiple prefixes independently", () => { + expect( + translateEnabledKeys({"metrics.enabled": true, "builder.enabled": false, "builder.url": "http://localhost"}) + ).toEqual({ + metrics: true, + builder: false, + "builder.url": "http://localhost", + }); + }); + + it("leaves `{prefix}.enabled` untouched when the bare `{prefix}` is already set (conflict surfaces later)", () => { + expect(translateEnabledKeys({metrics: false, "metrics.enabled": true})).toEqual({ + metrics: false, + "metrics.enabled": true, + }); + }); + + it("is a no-op when there are no `.enabled` keys", () => { + expect(translateEnabledKeys({"rest.port": 9596, network: "hoodi"})).toEqual({ + "rest.port": 9596, + network: "hoodi", + }); + }); + + it("does not translate a top-level key literally named `enabled`", () => { + expect(translateEnabledKeys({enabled: true})).toEqual({enabled: true}); + }); + + it("strips `.enabled` from a deeply-prefixed key", () => { + expect(translateEnabledKeys({"a.b.enabled": true})).toEqual({"a.b": true}); + }); +}); From d7943c441dc96e4f465fbc647ec1d9ba5bc48436 Mon Sep 17 00:00:00 2001 From: lodekeeper Date: Sat, 4 Jul 2026 19:00:32 +0000 Subject: [PATCH 07/19] docs(cli): trim rcConfig example per review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address nflaig review on #9578: - drop the flag/prefix Note (the example is sufficient) - remove the redundant example lead-in; fold the "nested maps or dotted keys" hint into the option description instead - drop the example command line and the config file name from the yaml Make the option-level `example.command` optional (rcConfig is the only option with an example, and it is illustrative config with no command to show) and skip the command block in docsgen when it is absent. 🤖 Generated with AI assistance Co-Authored-By: Claude Opus 4.8 --- packages/cli/docsgen/markdown.ts | 16 +++++++++------- packages/cli/src/options/globalOptions.ts | 13 ++++--------- packages/utils/src/command.ts | 4 +++- 3 files changed, 16 insertions(+), 17 deletions(-) diff --git a/packages/cli/docsgen/markdown.ts b/packages/cli/docsgen/markdown.ts index a83397a01482..d73af7957040 100644 --- a/packages/cli/docsgen/markdown.ts +++ b/packages/cli/docsgen/markdown.ts @@ -23,15 +23,17 @@ function sanitizeDescription(description: string): string { }); } -function renderExampleBody(example: CliExample, lodestarCommand?: string): string { - const cliExample = [ - `\`\`\`sh -${lodestarCommand ? `${lodestarCommand} ` : ""}${example.command} -\`\`\``, - ]; +function renderExampleBody(example: Partial>, lodestarCommand?: string): string { + const cliExample: string[] = []; if (example.description) { - cliExample.unshift(sanitizeDescription(example.description)); + cliExample.push(sanitizeDescription(example.description)); + } + + if (example.command) { + cliExample.push(`\`\`\`sh +${lodestarCommand ? `${lodestarCommand} ` : ""}${example.command} +\`\`\``); } return cliExample.join(DEFAULT_SEPARATOR); diff --git a/packages/cli/src/options/globalOptions.ts b/packages/cli/src/options/globalOptions.ts index dbe691778b46..961ea75568cd 100644 --- a/packages/cli/src/options/globalOptions.ts +++ b/packages/cli/src/options/globalOptions.ts @@ -49,13 +49,11 @@ const globalSingleOptions: CliCommandOptions = { }, rcConfig: { - description: "RC file to supplement command line args, accepted formats: .yml, .yaml, .json", + description: + "RC file to supplement command line args, accepted formats: .yml, .yaml, .json. Options can be written as nested maps or dotted keys.", type: "string", example: { - description: `Supply CLI options from a file. Options can be written as nested maps or dotted keys: - -\`\`\`yaml -# beacon.config.yaml + description: `\`\`\`yaml network: hoodi rest: address: 0.0.0.0 @@ -63,10 +61,7 @@ rest: metrics: enabled: true port: 8008 -\`\`\` - -For an on/off flag such as \`--metrics\`, use \`enabled\` under the nested map (\`metrics.enabled\`) or the dotted \`metrics\` key.`, - command: "beacon --rcConfig beacon.config.yaml", +\`\`\``, }, }, diff --git a/packages/utils/src/command.ts b/packages/utils/src/command.ts index 497dd72a225e..664a848013a5 100644 --- a/packages/utils/src/command.ts +++ b/packages/utils/src/command.ts @@ -8,7 +8,9 @@ export interface CliExample { // biome-ignore lint/suspicious/noExplicitAny: We need to use `any` type here export interface CliOptionDefinition extends Options { - example?: Omit; + // `command` is optional for option examples: some options are illustrated by config alone + // (e.g. an rc config file snippet) with no accompanying command line to show. + example?: Partial>; // Ensure `type` property matches type of `T` type: T extends string ? "string" From 440318e3ea58131f6fea67d44a00b1e851699ead Mon Sep 17 00:00:00 2001 From: lodekeeper Date: Sat, 4 Jul 2026 20:10:34 +0000 Subject: [PATCH 08/19] fix(cli): repair rcConfig docs rendering, keep example minimal MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The trimmed rcConfig example started with a ```yaml fence, but renderOption emits the example body inline after "example: ", so the fence opener landed mid-line ("example: ```yaml") and MDX stopped treating the page as markdown — every option below rcConfig rendered as raw source. - add a one-line lead-in before the yaml block so the fence starts at line start again (renders correctly) - restore the example command per review - revert the renderExampleBody / CliExample.command-optional change; no longer needed once the command is back, and keeps the PR diff minimal 🤖 Generated with AI assistance Co-Authored-By: Claude Opus 4.8 --- packages/cli/docsgen/markdown.ts | 16 +++++++--------- packages/cli/src/options/globalOptions.ts | 8 +++++--- packages/utils/src/command.ts | 4 +--- 3 files changed, 13 insertions(+), 15 deletions(-) diff --git a/packages/cli/docsgen/markdown.ts b/packages/cli/docsgen/markdown.ts index d73af7957040..a83397a01482 100644 --- a/packages/cli/docsgen/markdown.ts +++ b/packages/cli/docsgen/markdown.ts @@ -23,17 +23,15 @@ function sanitizeDescription(description: string): string { }); } -function renderExampleBody(example: Partial>, lodestarCommand?: string): string { - const cliExample: string[] = []; +function renderExampleBody(example: CliExample, lodestarCommand?: string): string { + const cliExample = [ + `\`\`\`sh +${lodestarCommand ? `${lodestarCommand} ` : ""}${example.command} +\`\`\``, + ]; if (example.description) { - cliExample.push(sanitizeDescription(example.description)); - } - - if (example.command) { - cliExample.push(`\`\`\`sh -${lodestarCommand ? `${lodestarCommand} ` : ""}${example.command} -\`\`\``); + cliExample.unshift(sanitizeDescription(example.description)); } return cliExample.join(DEFAULT_SEPARATOR); diff --git a/packages/cli/src/options/globalOptions.ts b/packages/cli/src/options/globalOptions.ts index 961ea75568cd..39c04d5d2d41 100644 --- a/packages/cli/src/options/globalOptions.ts +++ b/packages/cli/src/options/globalOptions.ts @@ -49,11 +49,12 @@ const globalSingleOptions: CliCommandOptions = { }, rcConfig: { - description: - "RC file to supplement command line args, accepted formats: .yml, .yaml, .json. Options can be written as nested maps or dotted keys.", + description: "RC file to supplement command line args, accepted formats: .yml, .yaml, .json", type: "string", example: { - description: `\`\`\`yaml + description: `Options can be written as nested maps or dotted keys: + +\`\`\`yaml network: hoodi rest: address: 0.0.0.0 @@ -62,6 +63,7 @@ metrics: enabled: true port: 8008 \`\`\``, + command: "beacon --rcConfig beacon.config.yaml", }, }, diff --git a/packages/utils/src/command.ts b/packages/utils/src/command.ts index 664a848013a5..497dd72a225e 100644 --- a/packages/utils/src/command.ts +++ b/packages/utils/src/command.ts @@ -8,9 +8,7 @@ export interface CliExample { // biome-ignore lint/suspicious/noExplicitAny: We need to use `any` type here export interface CliOptionDefinition extends Options { - // `command` is optional for option examples: some options are illustrated by config alone - // (e.g. an rc config file snippet) with no accompanying command line to show. - example?: Partial>; + example?: Omit; // Ensure `type` property matches type of `T` type: T extends string ? "string" From 2f496f0b13d6a55857738f649803948cfbcdb2e8 Mon Sep 17 00:00:00 2001 From: lodekeeper Date: Sat, 4 Jul 2026 20:55:43 +0000 Subject: [PATCH 09/19] docs(cli): render rcConfig example as a bare yaml block MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Drop the "example:" label and the command line from the rcConfig docs so it shows just the config snippet (per review). docsgen now renders an option example that has no command as a standalone block instead of forcing an inline "example: " prefix, which also keeps the code fence at line start. - rcConfig example is the yaml snippet only (no lead-in, no command) - renderExampleBody handles command-less examples - CliOptionDefinition.example allows an optional command 🤖 Generated with AI assistance Co-Authored-By: Claude Opus 4.8 --- packages/cli/docsgen/markdown.ts | 21 +++++++++++++-------- packages/cli/src/options/globalOptions.ts | 5 +---- packages/utils/src/command.ts | 3 ++- 3 files changed, 16 insertions(+), 13 deletions(-) diff --git a/packages/cli/docsgen/markdown.ts b/packages/cli/docsgen/markdown.ts index a83397a01482..e347d5a00111 100644 --- a/packages/cli/docsgen/markdown.ts +++ b/packages/cli/docsgen/markdown.ts @@ -23,15 +23,17 @@ function sanitizeDescription(description: string): string { }); } -function renderExampleBody(example: CliExample, lodestarCommand?: string): string { - const cliExample = [ - `\`\`\`sh -${lodestarCommand ? `${lodestarCommand} ` : ""}${example.command} -\`\`\``, - ]; +function renderExampleBody(example: Partial>, lodestarCommand?: string): string { + const cliExample: string[] = []; if (example.description) { - cliExample.unshift(sanitizeDescription(example.description)); + cliExample.push(sanitizeDescription(example.description)); + } + + if (example.command) { + cliExample.push(`\`\`\`sh +${lodestarCommand ? `${lodestarCommand} ` : ""}${example.command} +\`\`\``); } return cliExample.join(DEFAULT_SEPARATOR); @@ -139,7 +141,10 @@ function renderOption(optionName: string, option: CliOptionDefinition): string | } if (option.example) { - commandOption.push(`example: ${renderExampleBody(option.example)}`); + // Command examples get an "example:" label; config-only snippets render as a standalone block + commandOption.push( + option.example.command ? `example: ${renderExampleBody(option.example)}` : renderExampleBody(option.example) + ); } return commandOption.join(DEFAULT_SEPARATOR).concat(LINE_BREAK); diff --git a/packages/cli/src/options/globalOptions.ts b/packages/cli/src/options/globalOptions.ts index 39c04d5d2d41..e97cb605bbba 100644 --- a/packages/cli/src/options/globalOptions.ts +++ b/packages/cli/src/options/globalOptions.ts @@ -52,9 +52,7 @@ const globalSingleOptions: CliCommandOptions = { description: "RC file to supplement command line args, accepted formats: .yml, .yaml, .json", type: "string", example: { - description: `Options can be written as nested maps or dotted keys: - -\`\`\`yaml + description: `\`\`\`yaml network: hoodi rest: address: 0.0.0.0 @@ -63,7 +61,6 @@ metrics: enabled: true port: 8008 \`\`\``, - command: "beacon --rcConfig beacon.config.yaml", }, }, diff --git a/packages/utils/src/command.ts b/packages/utils/src/command.ts index 497dd72a225e..1a133de42ebb 100644 --- a/packages/utils/src/command.ts +++ b/packages/utils/src/command.ts @@ -8,7 +8,8 @@ export interface CliExample { // biome-ignore lint/suspicious/noExplicitAny: We need to use `any` type here export interface CliOptionDefinition extends Options { - example?: Omit; + // `command` is optional: some option examples are config snippets shown on their own + example?: Partial>; // Ensure `type` property matches type of `T` type: T extends string ? "string" From a4db343c77c2ae7d903e47389ac8e761511d14e9 Mon Sep 17 00:00:00 2001 From: lodekeeper Date: Sat, 4 Jul 2026 21:28:57 +0000 Subject: [PATCH 10/19] docs(cli): keep rcConfig example inline, drop docsgen change MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per review, don't modify docsgen for a single CLI flag — too invasive for the scope. Revert 2f496f0b13: the rcConfig example keeps its lead-in and command so it renders through the existing docsgen path unchanged; markdown.ts/command.ts are back to base. 🤖 Generated with AI assistance Co-Authored-By: Claude Opus 4.8 --- packages/cli/docsgen/markdown.ts | 21 ++++++++------------- packages/cli/src/options/globalOptions.ts | 5 ++++- packages/utils/src/command.ts | 3 +-- 3 files changed, 13 insertions(+), 16 deletions(-) diff --git a/packages/cli/docsgen/markdown.ts b/packages/cli/docsgen/markdown.ts index e347d5a00111..a83397a01482 100644 --- a/packages/cli/docsgen/markdown.ts +++ b/packages/cli/docsgen/markdown.ts @@ -23,17 +23,15 @@ function sanitizeDescription(description: string): string { }); } -function renderExampleBody(example: Partial>, lodestarCommand?: string): string { - const cliExample: string[] = []; +function renderExampleBody(example: CliExample, lodestarCommand?: string): string { + const cliExample = [ + `\`\`\`sh +${lodestarCommand ? `${lodestarCommand} ` : ""}${example.command} +\`\`\``, + ]; if (example.description) { - cliExample.push(sanitizeDescription(example.description)); - } - - if (example.command) { - cliExample.push(`\`\`\`sh -${lodestarCommand ? `${lodestarCommand} ` : ""}${example.command} -\`\`\``); + cliExample.unshift(sanitizeDescription(example.description)); } return cliExample.join(DEFAULT_SEPARATOR); @@ -141,10 +139,7 @@ function renderOption(optionName: string, option: CliOptionDefinition): string | } if (option.example) { - // Command examples get an "example:" label; config-only snippets render as a standalone block - commandOption.push( - option.example.command ? `example: ${renderExampleBody(option.example)}` : renderExampleBody(option.example) - ); + commandOption.push(`example: ${renderExampleBody(option.example)}`); } return commandOption.join(DEFAULT_SEPARATOR).concat(LINE_BREAK); diff --git a/packages/cli/src/options/globalOptions.ts b/packages/cli/src/options/globalOptions.ts index e97cb605bbba..39c04d5d2d41 100644 --- a/packages/cli/src/options/globalOptions.ts +++ b/packages/cli/src/options/globalOptions.ts @@ -52,7 +52,9 @@ const globalSingleOptions: CliCommandOptions = { description: "RC file to supplement command line args, accepted formats: .yml, .yaml, .json", type: "string", example: { - description: `\`\`\`yaml + description: `Options can be written as nested maps or dotted keys: + +\`\`\`yaml network: hoodi rest: address: 0.0.0.0 @@ -61,6 +63,7 @@ metrics: enabled: true port: 8008 \`\`\``, + command: "beacon --rcConfig beacon.config.yaml", }, }, diff --git a/packages/utils/src/command.ts b/packages/utils/src/command.ts index 1a133de42ebb..497dd72a225e 100644 --- a/packages/utils/src/command.ts +++ b/packages/utils/src/command.ts @@ -8,8 +8,7 @@ export interface CliExample { // biome-ignore lint/suspicious/noExplicitAny: We need to use `any` type here export interface CliOptionDefinition extends Options { - // `command` is optional: some option examples are config snippets shown on their own - example?: Partial>; + example?: Omit; // Ensure `type` property matches type of `T` type: T extends string ? "string" From 5307c3ec999cfde0d51ec5f0c833dcf05800c48c Mon Sep 17 00:00:00 2001 From: lodekeeper Date: Sat, 4 Jul 2026 21:39:01 +0000 Subject: [PATCH 11/19] docs(cli): use beacon-config.yaml in rcConfig example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per review (r3523885164): hyphenated filename so the example doesn't visually conflate the file name with the dotted option keys the feature introduces; also matches the existing rc-config.yml / rcconfig.yml docs examples. 🤖 Generated with AI assistance Co-Authored-By: Claude Opus 4.8 --- packages/cli/src/options/globalOptions.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/cli/src/options/globalOptions.ts b/packages/cli/src/options/globalOptions.ts index 39c04d5d2d41..01c7b77a27a1 100644 --- a/packages/cli/src/options/globalOptions.ts +++ b/packages/cli/src/options/globalOptions.ts @@ -63,7 +63,7 @@ metrics: enabled: true port: 8008 \`\`\``, - command: "beacon --rcConfig beacon.config.yaml", + command: "beacon --rcConfig beacon-config.yaml", }, }, From c8a47f104d41c045e9a63d65368c603b649bbb14 Mon Sep 17 00:00:00 2001 From: lodekeeper Date: Sat, 4 Jul 2026 22:19:36 +0000 Subject: [PATCH 12/19] docs(cli): drop "example:" label from rcConfig docs, keep command MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per review: keep the command in the example, but render it as a clean standalone block (yaml + command) without the inline "example:" label or lead-in text. Minimal docsgen change — renderOption no longer prefixes an option example with "example: "; rcConfig is the only option with an example. 🤖 Generated with AI assistance Co-Authored-By: Claude Opus 4.8 --- packages/cli/docsgen/markdown.ts | 4 +++- packages/cli/src/options/globalOptions.ts | 4 +--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/cli/docsgen/markdown.ts b/packages/cli/docsgen/markdown.ts index a83397a01482..4c01f1c84367 100644 --- a/packages/cli/docsgen/markdown.ts +++ b/packages/cli/docsgen/markdown.ts @@ -139,7 +139,9 @@ function renderOption(optionName: string, option: CliOptionDefinition): string | } if (option.example) { - commandOption.push(`example: ${renderExampleBody(option.example)}`); + // Render option examples as a standalone block (no "example:" label). rcConfig — the only + // option with an example — is a config-file snippet where the inline label just adds noise. + commandOption.push(renderExampleBody(option.example)); } return commandOption.join(DEFAULT_SEPARATOR).concat(LINE_BREAK); diff --git a/packages/cli/src/options/globalOptions.ts b/packages/cli/src/options/globalOptions.ts index 01c7b77a27a1..cfb7043818d9 100644 --- a/packages/cli/src/options/globalOptions.ts +++ b/packages/cli/src/options/globalOptions.ts @@ -52,9 +52,7 @@ const globalSingleOptions: CliCommandOptions = { description: "RC file to supplement command line args, accepted formats: .yml, .yaml, .json", type: "string", example: { - description: `Options can be written as nested maps or dotted keys: - -\`\`\`yaml + description: `\`\`\`yaml network: hoodi rest: address: 0.0.0.0 From f801040717188fbde65ed77403ba02356367a704 Mon Sep 17 00:00:00 2001 From: lodekeeper Date: Sat, 4 Jul 2026 22:51:20 +0000 Subject: [PATCH 13/19] docs(cli): keep "example:" label, revert docsgen tweak MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The "example:" keyword isn't worth a docsgen change — revert c8a47f104d so docsgen stays at base. rcConfig keeps the command + lead-in + "example:" label, rendering through the existing path. PR back to feature + example only. 🤖 Generated with AI assistance Co-Authored-By: Claude Opus 4.8 --- packages/cli/docsgen/markdown.ts | 4 +--- packages/cli/src/options/globalOptions.ts | 4 +++- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/cli/docsgen/markdown.ts b/packages/cli/docsgen/markdown.ts index 4c01f1c84367..a83397a01482 100644 --- a/packages/cli/docsgen/markdown.ts +++ b/packages/cli/docsgen/markdown.ts @@ -139,9 +139,7 @@ function renderOption(optionName: string, option: CliOptionDefinition): string | } if (option.example) { - // Render option examples as a standalone block (no "example:" label). rcConfig — the only - // option with an example — is a config-file snippet where the inline label just adds noise. - commandOption.push(renderExampleBody(option.example)); + commandOption.push(`example: ${renderExampleBody(option.example)}`); } return commandOption.join(DEFAULT_SEPARATOR).concat(LINE_BREAK); diff --git a/packages/cli/src/options/globalOptions.ts b/packages/cli/src/options/globalOptions.ts index cfb7043818d9..01c7b77a27a1 100644 --- a/packages/cli/src/options/globalOptions.ts +++ b/packages/cli/src/options/globalOptions.ts @@ -52,7 +52,9 @@ const globalSingleOptions: CliCommandOptions = { description: "RC file to supplement command line args, accepted formats: .yml, .yaml, .json", type: "string", example: { - description: `\`\`\`yaml + description: `Options can be written as nested maps or dotted keys: + +\`\`\`yaml network: hoodi rest: address: 0.0.0.0 From 5f96ad397181c98475e69e1e9e79c5f108a64670 Mon Sep 17 00:00:00 2001 From: lodekeeper Date: Sat, 4 Jul 2026 22:59:55 +0000 Subject: [PATCH 14/19] docs(cli): drop command from rcConfig example, keep "example:" label MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The command line was the noisy part; keep the "example:" label + yaml example but drop the command. Minimal docsgen change: example.command is now optional and renderExampleBody skips the sh block when absent; renderOption still labels the block "example:". rcConfig is the only option with an example. 🤖 Generated with AI assistance Co-Authored-By: Claude Opus 4.8 --- packages/cli/docsgen/markdown.ts | 16 +++++++++------- packages/cli/src/options/globalOptions.ts | 1 - packages/utils/src/command.ts | 3 ++- 3 files changed, 11 insertions(+), 9 deletions(-) diff --git a/packages/cli/docsgen/markdown.ts b/packages/cli/docsgen/markdown.ts index a83397a01482..d73af7957040 100644 --- a/packages/cli/docsgen/markdown.ts +++ b/packages/cli/docsgen/markdown.ts @@ -23,15 +23,17 @@ function sanitizeDescription(description: string): string { }); } -function renderExampleBody(example: CliExample, lodestarCommand?: string): string { - const cliExample = [ - `\`\`\`sh -${lodestarCommand ? `${lodestarCommand} ` : ""}${example.command} -\`\`\``, - ]; +function renderExampleBody(example: Partial>, lodestarCommand?: string): string { + const cliExample: string[] = []; if (example.description) { - cliExample.unshift(sanitizeDescription(example.description)); + cliExample.push(sanitizeDescription(example.description)); + } + + if (example.command) { + cliExample.push(`\`\`\`sh +${lodestarCommand ? `${lodestarCommand} ` : ""}${example.command} +\`\`\``); } return cliExample.join(DEFAULT_SEPARATOR); diff --git a/packages/cli/src/options/globalOptions.ts b/packages/cli/src/options/globalOptions.ts index 01c7b77a27a1..b4decd72715a 100644 --- a/packages/cli/src/options/globalOptions.ts +++ b/packages/cli/src/options/globalOptions.ts @@ -63,7 +63,6 @@ metrics: enabled: true port: 8008 \`\`\``, - command: "beacon --rcConfig beacon-config.yaml", }, }, diff --git a/packages/utils/src/command.ts b/packages/utils/src/command.ts index 497dd72a225e..1a133de42ebb 100644 --- a/packages/utils/src/command.ts +++ b/packages/utils/src/command.ts @@ -8,7 +8,8 @@ export interface CliExample { // biome-ignore lint/suspicious/noExplicitAny: We need to use `any` type here export interface CliOptionDefinition extends Options { - example?: Omit; + // `command` is optional: some option examples are config snippets shown on their own + example?: Partial>; // Ensure `type` property matches type of `T` type: T extends string ? "string" From 60b66486af700b897db22cddef0d11ab37514494 Mon Sep 17 00:00:00 2001 From: lodekeeper Date: Sat, 4 Jul 2026 23:18:24 +0000 Subject: [PATCH 15/19] docs(cli): use command-agnostic options in rcConfig example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit rcConfig is a global option, so its example renders in every command's CLI docs (beacon, validator, bootnode). The previous example used `rest.*`, which is beacon-only and makes no sense in the validator/bootnode reference. Use options available in all commands (network, logLevel, metrics) — still demoing a nested map + the .enabled translation via metrics. 🤖 Generated with AI assistance Co-Authored-By: Claude Opus 4.8 --- packages/cli/src/options/globalOptions.ts | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/packages/cli/src/options/globalOptions.ts b/packages/cli/src/options/globalOptions.ts index b4decd72715a..bc0648308d99 100644 --- a/packages/cli/src/options/globalOptions.ts +++ b/packages/cli/src/options/globalOptions.ts @@ -56,9 +56,7 @@ const globalSingleOptions: CliCommandOptions = { \`\`\`yaml network: hoodi -rest: - address: 0.0.0.0 - port: 9596 +logLevel: debug metrics: enabled: true port: 8008 From bf161a1cee9c8a942a142b8d2a0ba3b608d1e3ef Mon Sep 17 00:00:00 2001 From: lodekeeper Date: Sat, 4 Jul 2026 23:33:01 +0000 Subject: [PATCH 16/19] refactor(cli): drop unused command from option examples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit No CLI option uses example.command — rcConfig is the only option with an example, and it's a config snippet with no command. Remove command from the option-example type, render the description directly in renderOption, and restore renderExampleBody to its original form (now used only by command-level examples). Docs output unchanged. 🤖 Generated with AI assistance Co-Authored-By: Claude Opus 4.8 --- packages/cli/docsgen/markdown.ts | 20 +++++++++----------- packages/utils/src/command.ts | 4 ++-- 2 files changed, 11 insertions(+), 13 deletions(-) diff --git a/packages/cli/docsgen/markdown.ts b/packages/cli/docsgen/markdown.ts index d73af7957040..2edb72f5af61 100644 --- a/packages/cli/docsgen/markdown.ts +++ b/packages/cli/docsgen/markdown.ts @@ -23,17 +23,15 @@ function sanitizeDescription(description: string): string { }); } -function renderExampleBody(example: Partial>, lodestarCommand?: string): string { - const cliExample: string[] = []; +function renderExampleBody(example: CliExample, lodestarCommand?: string): string { + const cliExample = [ + `\`\`\`sh +${lodestarCommand ? `${lodestarCommand} ` : ""}${example.command} +\`\`\``, + ]; if (example.description) { - cliExample.push(sanitizeDescription(example.description)); - } - - if (example.command) { - cliExample.push(`\`\`\`sh -${lodestarCommand ? `${lodestarCommand} ` : ""}${example.command} -\`\`\``); + cliExample.unshift(sanitizeDescription(example.description)); } return cliExample.join(DEFAULT_SEPARATOR); @@ -140,8 +138,8 @@ function renderOption(optionName: string, option: CliOptionDefinition): string | commandOption.push(`default: \`${defaultValue}\``); } - if (option.example) { - commandOption.push(`example: ${renderExampleBody(option.example)}`); + if (option.example?.description) { + commandOption.push(`example: ${sanitizeDescription(option.example.description)}`); } return commandOption.join(DEFAULT_SEPARATOR).concat(LINE_BREAK); diff --git a/packages/utils/src/command.ts b/packages/utils/src/command.ts index 1a133de42ebb..423a188832f3 100644 --- a/packages/utils/src/command.ts +++ b/packages/utils/src/command.ts @@ -8,8 +8,8 @@ export interface CliExample { // biome-ignore lint/suspicious/noExplicitAny: We need to use `any` type here export interface CliOptionDefinition extends Options { - // `command` is optional: some option examples are config snippets shown on their own - example?: Partial>; + // Option examples are a description block only (e.g. an rc config snippet); no command line + example?: Omit; // Ensure `type` property matches type of `T` type: T extends string ? "string" From b5b9c93c5bd743c871d7c46421fe92c1f51f791c Mon Sep 17 00:00:00 2001 From: lodekeeper Date: Sun, 5 Jul 2026 08:21:32 +0000 Subject: [PATCH 17/19] docs(cli): show dotted-key form in rcConfig example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address nflaig review (r3524527982): the description says options can be written as nested maps or dotted keys, but the example only showed the nested form. Demonstrate both — `metrics` as a nested map and `metrics.port` as a dotted key — and drop the trailing colon per the suggestion. 🤖 Generated with AI assistance Co-Authored-By: Claude Opus 4.8 --- packages/cli/src/options/globalOptions.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/cli/src/options/globalOptions.ts b/packages/cli/src/options/globalOptions.ts index bc0648308d99..215aec461e4c 100644 --- a/packages/cli/src/options/globalOptions.ts +++ b/packages/cli/src/options/globalOptions.ts @@ -52,14 +52,14 @@ const globalSingleOptions: CliCommandOptions = { description: "RC file to supplement command line args, accepted formats: .yml, .yaml, .json", type: "string", example: { - description: `Options can be written as nested maps or dotted keys: + description: `Options can be written as nested maps or dotted keys \`\`\`yaml network: hoodi logLevel: debug -metrics: +metrics: # nested map enabled: true - port: 8008 +metrics.port: 8008 # dotted key \`\`\``, }, }, From f035e9dc3e69a548e8094c8c8b10f19b8685bfe7 Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Sun, 5 Jul 2026 09:37:06 +0100 Subject: [PATCH 18/19] Apply suggestion from @nflaig --- packages/cli/src/options/globalOptions.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/cli/src/options/globalOptions.ts b/packages/cli/src/options/globalOptions.ts index 215aec461e4c..082a841822df 100644 --- a/packages/cli/src/options/globalOptions.ts +++ b/packages/cli/src/options/globalOptions.ts @@ -57,9 +57,9 @@ const globalSingleOptions: CliCommandOptions = { \`\`\`yaml network: hoodi logLevel: debug -metrics: # nested map +metrics: enabled: true -metrics.port: 8008 # dotted key + port: 8008 \`\`\``, }, }, From b151a8840aa1ad4d5ea29e92623ff16625568eed Mon Sep 17 00:00:00 2001 From: lodekeeper Date: Sun, 5 Jul 2026 08:45:29 +0000 Subject: [PATCH 19/19] chore: re-trigger CI MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🤖 Generated with AI assistance