85 lines
3.6 KiB
Markdown
85 lines
3.6 KiB
Markdown
# 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.
|