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

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.