eric/geth
Watch
1
0
Fork
You've already forked geth
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
geth/docs/command-stability.md

3.6 KiB
Raw Permalink Blame History

Command Stability

This document classifies the current geth CLI surface for scripts and downstream projects. The compatibility rules in docs/compatibility.md apply to stable commands after the first deployment tag.

Stability Levels

  • Stable: intended for scripts once the first deployment tag exists. Command names, flag names, argument meanings, and --json field meanings should not change within a major release.
  • Experimental: useful and tested, but the command may still change as the subsystem is hardened. Scripts should pin a geth version and expect migration notes.
  • Prototype: proves a shape or workflow. Do not build durable automation on it without expecting replacement or incompatible changes.

Stable

The following command families are intended to be stable automation surfaces:

  • geth init
  • geth --home <dir> ...
  • geth daemon run [--ephemeral]
  • geth daemon install|start|stop|status|uninstall
  • geth daemon service install|uninstall|start|stop|status|print
  • geth status
  • geth doctor
  • geth node id
  • geth backup create|restore
  • geth node list|rename|revoke|grant|revoke-grant|endpoint-add|endpoint-revoke
  • geth node enroll request|submit|import|list|approve|sync
  • geth peer export|import|list|ping|auth-check
  • geth keychain init|status|admin-add|admin-revoke|allowed-signers|verify
  • geth keychain sign-file|verify-file
  • geth keychain explain|explain-signer
  • geth auth explain|grant|revoke|sync
  • geth sync status|now
  • geth wait daemon|peer|sync
  • geth secret status|create|rotate|bearer
  • Local CAS object commands: geth cas add|get|hash|has|pin|unpin|cleanup|providers|list|fetch
  • File-root metadata commands: geth cas root add|list|scan|sync|apply
  • File-conflict metadata commands: geth cas conflict record|list|resolve
  • SSH certificate and revocation metadata commands under geth ssh cert ... and geth ssh revocation ...
  • geth ssh proxy
  • Restricted geth ssh admin-shell help|status|node-id
  • geth db add|status|changes|sync
  • geth kv create|set|get|sync
  • geth document create|status|set|get|sync
  • geth pubsub pub|sub
  • geth pipe listen|connect|send|recv|forward-tcp|forward-unix
  • geth completions
  • geth guide

Experimental

The following commands are tested but may still change while the subsystem settles:

  • geth overlay status|plan|join|leave|interface-plan|up|down|peers|send|recv
  • geth cas add-private
  • geth cas get-private
  • geth keychain verify-sigchain
  • geth keychain bundle-create|bundle-extract

Migration expectation: overlay membership records and authorization resources should remain readable, but packet runtime flags, platform activation details, and route metadata may change before the first deployment tag. Private CAS writes use an AES-256-GCM envelope, but the command family remains experimental while key envelopes, remote sharing, and forward-secrecy/PCS properties are explicitly out of scope. Prototype BLAKE3-XOR envelopes from earlier pre-deployment builds are rejected with a clear error and should be recreated from plaintext.

The SSHSIGCHAIN verifier and canonical bundle conversion are experimental while SSHSIGCHAIN signing, append storage, automatic distribution, import, head persistence, and independently generated wire vectors are completed. The prior test-only static commands were removed and are not a compatibility path.

Adding Commands

New commands should enter this file in the same change that introduces the CLI surface. Experimental and prototype commands should include a migration or removal expectation before users are encouraged to automate against them.