Skip to content

CLI-SPEC.md

Latest commit

 

History

History
162 lines (118 loc) · 3.44 KB

CLI-SPEC.md

File metadata and controls

162 lines (118 loc) · 3.44 KB

CLI Spec

Product goals

The CLI should feel like more than a thin wrapper around functions.

A developer should quickly see:

  • one root -> many identities
  • unlinkability by default
  • optional continuity proofs
  • offline-first operation
  • human-usable recovery workflows

Principles

  • offline-first by default
  • no network required for core operations
  • human-readable output by default
  • --json for scripting
  • safe handling of secrets
  • clear distinction between root types
  • minimal ceremony for first success

Mental model

  • Root — starting secret for derivation
  • Persona — named branch of identity
  • Account — derived child identity for a specific use
  • Private proof — proves shared root without revealing derivation context
  • Full proof — proves shared root and reveals derivation context
  • Mnemonic-backed root — recoverable with phrase / Shamir
  • nsec-backed root — derivation-capable, but not phrase-recoverable

Top-level commands

  • nsec-tree root
  • nsec-tree derive
  • nsec-tree export
  • nsec-tree prove
  • nsec-tree verify
  • nsec-tree shamir
  • nsec-tree profile
  • nsec-tree inspect
  • nsec-tree explain

Root commands

  • nsec-tree root create
  • nsec-tree root restore
  • nsec-tree root import-nsec
  • nsec-tree root inspect

Expected output should make these explicit:

  • root type
  • recoverable yes/no
  • master pubkey / npub
  • warnings when relevant

Derivation commands

  • nsec-tree derive path <path>
  • nsec-tree derive persona <name>
  • nsec-tree derive account <path>

Canonical path syntax:

  • personal
  • personal/forum-burner
  • personal@1/forum-burner@3

Rules:

  • / separates levels
  • @index is optional, default 0
  • names are lowercase, shell-friendly, max 32 chars

Export commands

  • nsec-tree export npub <path>
  • nsec-tree export nsec <path>
  • nsec-tree export identity <path>

Secret-emitting commands should warn in TTY mode and support:

  • --json
  • --quiet
  • --out

Proof commands

  • nsec-tree prove private <path>
  • nsec-tree prove full <path>
  • nsec-tree verify proof <file>
  • nsec-tree verify proof --stdin

Use private rather than blind in user-facing command language.

Shamir commands

  • nsec-tree shamir split
  • nsec-tree shamir recover

Important rule:

  • Shamir operates on mnemonic recovery material
  • it does not upgrade a plain imported nsec into a recovery-capable root

Profiles

Profiles are a CLI convenience layer, not hidden magic.

  • nsec-tree profile save <name>
  • nsec-tree profile list
  • nsec-tree profile use <name>
  • nsec-tree profile show [name]
  • nsec-tree profile remove <name>

Explicit root input remains the default-safe path for scripts.

Inspect and explain

  • nsec-tree inspect path <path>
  • nsec-tree inspect root
  • nsec-tree explain model
  • nsec-tree explain proofs
  • nsec-tree explain recovery

These commands are onboarding tools and part of the wow factor.

Must-have v1

  • root create
  • root restore
  • root import-nsec
  • derive path
  • export npub
  • export nsec
  • prove private
  • prove full
  • verify proof
  • shamir split
  • shamir recover
  • --json

Nice-to-have

  • profile commands
  • inspect commands
  • explain commands
  • QR-oriented output

Example wow flow

nsec-tree root create
nsec-tree derive path personal
nsec-tree derive path anon/forum-burner
nsec-tree export nsec anon/forum-burner
nsec-tree prove private anon/forum-burner