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 daemon run
geth daemon service install|uninstall|start|stop|status|print
geth status
geth node id
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 sigchain|verify-sigchain|import-sigchain|verify-checkpoint|fetch|explain|explain-signer
geth auth explain|grant|revoke|sync
geth sync status|now
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

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.

Prototype

The following commands intentionally do not claim a stable security or storage contract yet:

geth cas add-private
geth cas get-private

Migration expectation: prototype private CAS envelopes may be replaced by an audited AEAD/key-envelope design. Existing prototype blobs may need an explicit re-encryption or export/import workflow.

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.

3.1 KiB Raw Blame History