Align CLI flags with lean-quickstart spec (replace --custom-network-config-dir with split flags)

[dimka90]

Problem

gean currently exposes a single --custom-network-config-dir flag in cmd/gean/main.go:29 that bundles the genesis config, validators registry, bootnodes ENRs, and hash-sig key directory under one path. The lean-quickstart Adding a New Client spec mandates separate flags:

Spec flag	Maps to
--genesis (or --custom-genesis / --network)	config.yaml
--validators (or --validator-registry-path)	annotated_validators.yaml
--bootnodes	nodes.yaml

--custom-network-config-dir is not part of the required flag set. Today gean is non-conformant with the onboarding spec, and client-cmds/gean-cmd.sh in lean-quickstart cannot follow the same template as ethlambda/reaman/lantern.

Precedent

ethlambda completed this exact migration on 2026-05-12:

• ethlambda source PR: feat!: align flag names with lean-quickstart spec lambdaclass/ethlambda#321 — drops --custom-network-config-dir, adds five split flags.
• lean-quickstart sister PR: chore: update ethlambda CLI flags to align with the spec blockblaz/lean-quickstart#168 — updates client-cmds/ethlambda-cmd.sh + the ethlambda ansible role.

The two PRs were coordinated: the lean-quickstart side was reviewed first, the source side merged after.

Proposed Fix

Two-step rollout mirroring ethlambda's:

Step 1 — gean source (this repo)

Replace --custom-network-config-dir in cmd/gean/main.go with five flags. The internal file resolution at main.go:63-66 becomes flag-driven instead of derived:

New flag	Replaces internal derivation at	Maps to
--genesis	main.go:63	config.yaml
--validators	main.go:65	annotated_validators.yaml
--bootnodes	main.go:64	nodes.yaml
--validator-config	(not currently read; reserve for future)	validator-config.yaml
--hash-sig-keys-dir	main.go:66	hash-sig-keys/

Files needing updates:

• cmd/gean/main.go:29 — flag declaration + line 46 usage error
• cmd/keygen/main.go:113 — example command in keygen output
• README.md — CLI Flags table and the Checkpoint Sync snippet
• Makefile run / run-node1 / run-node2 targets that pass --custom-network-config-dir

Open decision: keep --custom-network-config-dir as a deprecated alias for one release cycle (softer than ethlambda's hard cut) or drop immediately. Recommend keeping the alias short-term since gean has downstream consumers in lean-quickstart and zeam tooling.

Step 2 — lean-quickstart PR (separate, follow-on)

Update client-cmds/gean-cmd.sh + ansible/roles/gean/tasks/main.yml to use the split flags, mirroring lean-quickstart PR #168's diff line-for-line. Sequencing: open the source PR first; merge the lean-quickstart PR only after the new ghcr.io/geanlabs/gean:devnet4 image ships with the new flag set, otherwise local-devnet boots break.

Verification

• ./bin/gean --help shows the new flags; --custom-network-config-dir is gone or marked deprecated.
• make run / make run-node1 / make run-node2 boot a local 3-node testnet successfully.
• NETWORK_DIR=local-devnet ./spin-node.sh --node gean_0 --generateGenesis boots from a checked-out branch of the lean-quickstart sister PR.

References

• ethlambda PR: feat!: align flag names with lean-quickstart spec lambdaclass/ethlambda#321
• lean-quickstart PR: chore: update ethlambda CLI flags to align with the spec blockblaz/lean-quickstart#168
• Spec doc: https://github.com/blockblaz/lean-quickstart/blob/main/docs/adding-a-new-client.md#required-cli-flags-your-client-must-support