feat(cli): seictl gov subcommands for in-cluster governance operations

[bdchatham]

Problem

Operators today run seienv vote / seienv propose-upgrade (in slanders/seienv) to perform fleet-wide governance operations against EC2 validators via SSH. With validators migrating to Kubernetes via sei-k8s-controller, the canonical operator tool going forward is seictl. seictl does not yet expose governance commands — it needs gov subcommands that resolve a SeiNode's sidecar URL from the K8s API and submit the sign-tx tasks introduced in the sister issue.

Impact

• User-visible replacement for seienv vote / seienv propose-upgrade.
• Closes the loop on the K8s-native validator-governance workflow.
• Without it, the sidecar task surface exists but there's no ergonomic way for human operators to call it.

Relevant experts

• platform-engineer — K8s client integration, kubeconfig handling, sidecar discovery
• product-engineer — CLI ergonomics, fan-out across deployments

Proposed approach

1. New top-level cobra command seictl gov in cmd/gov/ with subcommands:
   • seictl gov vote <proposal-id> <yes|no|abstain|no_with_veto> --validator <seinode-name> [--namespace <ns>] [--fees <fees>] [--memo <memo>]
   • seictl gov submit-proposal software-upgrade <name> --validator <seinode-name> --height <h> [--info <url>] [--deposit <amt>] [--fees <fees>]
   • seictl gov deposit <proposal-id> <amount> --validator <seinode-name> [--fees <fees>]
2. Fan-out flags for fleet-wide ops (mirrors seienv's implicit fan-out):
   • --deployment <seinodedeployment-name> — resolves all SeiNodes owned by the deployment and submits in parallel
   • --threads N — parallelism cap (default 10)
3. Sidecar discovery: K8s client (controller-runtime or client-go) fetches the SeiNode, resolves its headless Service DNS or Pod IP, constructs the sidecar URL (http://<seinode>-0.<seinode>.<ns>.svc.cluster.local:7777). Existing NewSidecarClientFromPodDNS helper covers this shape.
4. Kubeconfig: uses standard clientcmd resolution (KUBECONFIG env, ~/.kube/config, in-cluster service-account if running in a pod).
5. Output: task UUID printed immediately; if --wait is passed (default true), polls task status until terminal and prints {txHash, height, rawLog}.
6. Idempotency: caller-supplied UUID via --task-id flag; CLI auto-generates and prints if not provided. Enables operator retry without double-voting.
7. Error handling: surface sidecar task errors verbatim; on partial-failure across a fleet fan-out, print a per-validator status table and exit non-zero.

Acceptance criteria

• Three subcommands implemented (vote, submit-proposal software-upgrade, deposit)
• Single-validator and --deployment fleet fan-out modes work
• Idempotent retry via --task-id works as documented
• Per-validator status table for fan-out mode
• Help text + examples included on every subcommand
• Integration test against a kind cluster with two SeiNodes + a local seid devnet
• User-facing docs in docs/gov.md mirroring slanders/seienv/cheatsheet.md governance section

Out of scope

• Non-gov tx commands (staking, distribution, IBC) — same pattern, separate issues
• Proposal types beyond software-upgrade in the initial cut (param-change, community-pool, text proposals) — additive later
• Web UI / dashboard
• Authn handshake — wires in when "Sidecar authn + authz middleware" lands; until then, CLI calls the unauthenticated endpoint

References

• Coral session 2026-05-11
• Predecessor: slanders/seienv cmd/vote.go, cmd/propose.go, propose.sh, cheatsheet.md
• Sister issue: sidecar sign-tx task family (this repo)
• Sidecar discovery pattern: sidecar/client/client.go (NewSidecarClientFromPodDNS)
• Cobra command structure: main.go:43-52

Sequencing

Phase 1, step 4 of 5 in the governance-flow migration. Depends on step 3 (sign-tx task family). Step 5 (authn) is the final hardening pass and lands after this.

[bdchatham]

Workstream cross-reference

This issue is part of a 5-issue sequence to migrate Sei validator governance flows from slanders/seienv (SSH + seid tx on EC2 hosts) to in-cluster execution via seictl + the sidecar API.

Step	Issue	Scope
1	sei-protocol/sei-k8s-controller#219	CRD validator.operatorKeyring surface
2	#162	Sidecar production keyring backend
3	#163	Sidecar sign-tx task family (gov vote / submit-proposal / deposit)
4	#164 (this issue)	seictl gov CLI subcommands
5	#165	Sidecar authn + authz middleware (deliberate last step)

Per a team sequencing decision, steps 1–4 ship the core flow; step 5 closes the authn gap as the final hardening pass. The token-presenting auth handshake for this CLI lands as part of #165.

[bdchatham]

Design doc merged (#166): docs/design/in-pod-governance-signing.md

Implementation specifics for this issue are captured in Component D — seictl gov CLI subcommands: cobra command tree under cmd/gov/, full flag taxonomy for vote / submit-proposal software-upgrade / deposit, sidecar discovery via headless Service DNS (<name>-0.<name>.<ns>.svc.cluster.local:7777), kubeconfig resolution, --deployment fan-out across SeiNodeDeployment validators with per-validator outcome table, idempotent --task-id, --wait/--timeout polling, Phase-4 token-minting stub.

Cross-section context (operator runbook, output format examples, integration with the genesis-network validation gate) lives in the same doc.

[bdchatham]

Rev2 update (design doc merged in #167)

Two changes per rev2:

1. CLI targets the kube-rbac-proxy port, not the sidecar port

TLS terminates at https://<seinode>-0.<seinode>.<ns>.svc.cluster.local:8443 (proxy), not http://...:7777 (sidecar — now loopback-only). TLS verification uses the kubeconfig's CA chain by default; --certificate-authority <path> and --insecure-skip-tls-verify flags available for atypical setups.

func resolveSidecarURL(ctx context.Context, dyn dynamic.Interface, name, ns string) (string, error) {
    return fmt.Sprintf("https://%s-0.%s.%s.svc.cluster.local:8443", name, name, ns), nil
}

2. Authentication via standard kubeconfig exec credential plugin

No special token minting in seictl. The CLI reads kubeconfig and the credential plugin (typically aws eks get-token for EKS) supplies the bearer transparently. For AWS clusters: aws sso login --profile <p> once per session → aws eks get-token configured in the kubeconfig → seictl picks up the bearer on each call.

The originally-designed TokenRequest/CreateToken block is deleted. seictl operates as a kubectl-shaped CLI, not a service-account-impersonator.

Output renders the proxy-resolved caller identity:

$ seictl gov vote 5 yes --validator my-validator
Submitted task abc-123 to https://my-validator-0...:8443
  as: arn:aws:iam::123:role/aws-reserved/sso.amazonaws.com/AWSReservedSSO_SeiPlatformGov_xxx
  groups: [sei-platform-governance, system:authenticated]
Waiting for inclusion ...
✓ tx 0xB7E2... included at height 1234567 (code=0, gasUsed=142318)

Unchanged

The cobra command structure (seictl gov vote/submit-proposal software-upgrade/deposit), sidecar discovery via headless Service DNS, --deployment fan-out across SeiNodeDeployment validators, idempotent --task-id, dry-run mode, and per-validator outcome table for fan-out are all unchanged from the original issue scope.

See docs/design/in-pod-governance-signing.md Component D delta for full code-grade detail.

[bdchatham]

Rev3 update (design doc PR #169)

Rev3 simplifies the CLI's task-submission shape. Net for this issue: slightly simpler than rev2.

Changes vs the rev2 update I commented earlier

Item	rev2 (commented earlier)	rev3 (now)
Submission URL	`POST :8443/v0/tasks//`	`POST :8443/v0/tasks` (body-typed)
Per-class path construction	CLI built path from task class	CLI submits to a single URL; `type` is in the JSON body
AWS SSO flow	Unchanged	Unchanged — `aws sso login` → kubeconfig exec credential plugin → bearer flows transparently
TLS verification	Unchanged — kubeconfig CA chain	Unchanged
Output format	`as: ` line reflects the proxy-resolved caller	Unchanged

What's unchanged

• Cobra command tree: `seictl gov vote/submit-proposal software-upgrade/deposit`
• Sidecar discovery via headless Service DNS
• `--deployment` fan-out across SeiNodeDeployment validators with per-validator outcome table
• Idempotent `--task-id`
• `--dry-run` flag
• Output rendering with caller-identity surfacing (`as: `)

See `docs/design/in-pod-governance-signing.md` Component D delta for full code-grade detail.