@debros/root-cli

The RootWallet command-line interface. Manage crypto wallets, vault passwords, SSH keys, and cloud sync from the terminal.

See the main README for full command reference and installation instructions.

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Run tests
pnpm test

# Type check
pnpm type-check

# Run in dev mode (watch)
pnpm dev

Project Structure

src/
├── commands/        # One file per CLI command (init, sign, vault-ssh, sync-push, etc.)
├── lib/             # Shared utilities
│   ├── session.ts           # Wallet session (mnemonic caching + keychain)
│   ├── keystore-file.ts     # Keystore read/write
│   ├── vault-unlock.ts      # Vault key derivation from seed
│   ├── vault-file.ts        # Vault file I/O (V1 + V2)
│   ├── agent-protocol.ts    # Agent approve wire protocol
│   ├── agent-session.ts     # Agent scoped session management
│   ├── agent-client.ts      # Client-side agent request helper
│   ├── agent-keychain.ts    # Agent session OS keychain integration
│   ├── keychain.ts          # Wallet session OS keychain integration
│   ├── sync-config.ts       # Cloud sync configuration
│   ├── orama-gateway-client.ts  # Orama Network gateway HTTP client
│   ├── unlock.ts            # Password prompt + mnemonic decryption
│   ├── password.ts          # Password input helpers
│   ├── hex.ts               # Hex encoding utilities
│   └── output.ts            # Stderr output helpers
├── index.ts         # CLI entry point (commander setup)
test/
├── lib/             # Unit tests for lib modules
└── commands/        # Integration tests for commands

Architecture

• CLI framework: Commander.js v13
• Crypto: All crypto via @debros/root-core (no direct noble/scure imports)
• Test runner: Vitest v3
• Bundler: tsup (ESM output)
• Session model: Mnemonic encrypted with random key, key stored in OS keychain
• Agent protocol: Unix socket IPC for external app integration — see Agent Protocol docs

Key Conventions

• All key material (Uint8Array) is zeroed after use via .fill(0)
• Passwords are never passed as CLI arguments — always prompted via stdin
• Session and agent session use separate OS keychain entries
• Output goes to stderr (info(), fatal()); only command results go to stdout