geth/docs/command-stability.md

# 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 sigchain|verify-sigchain|import-sigchain|verify-checkpoint|fetch|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`

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.

## 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.