Selkie CLI

Zero-trust secret management command-line interface.

Installation

# Install from npm
npm install -g selkie-cli

# Or use npx
npx selkie-cli --help

From Source

# From repository root
npm install
npm run build --workspace=packages/cli

# Link for local development
cd packages/cli
npm link

Configuration

The CLI stores configuration in your OS-specific config directory:

• macOS: ~/Library/Preferences/selkie-cli/
• Linux: ~/.config/selkie-cli/
• Windows: %APPDATA%\selkie-cli\

Sensitive credentials (JWT tokens, encrypted keys) are stored securely in your OS keychain using keytar.

Usage

First-Time Setup

# Check if server is running
selkie config

# Register a new account
selkie register --server http://localhost:3847

# Or login to existing account
selkie login --server http://localhost:3847

Managing Secrets

# List objects you have access to
selkie list

# Get and decrypt a secret
selkie get <objectId>

# Create a new secret
selkie create --type ssh-key --name "Production Server" --paranoid

# Update a secret (creates new version)
selkie update <objectId>

# Delete a secret
selkie delete <objectId>

Access Control

# Grant user access to an object
selkie grant <objectId> <userId> --role CONSUMER

# Revoke user access
selkie revoke <objectId> <userId>

Account Management

# Show current authenticated user
selkie whoami

# Display recovery mnemonic (SAVE THIS SECURELY)
selkie backup

# Recover account from mnemonic
selkie recover

# Logout
selkie logout

Architecture

Services

1. ConfigService (src/services/config.service.ts)

   • Manages non-sensitive CLI configuration
   • Stores server URL, current user info
   • Uses conf package for persistent storage

2. TokenStorageService (src/services/token-storage.service.ts)

   • Securely stores JWT tokens and encrypted keys in OS keychain
   • Uses keytar for cross-platform keychain access
   • Stores: JWT token, encrypted UMK, KDF params, encrypted private key, public key

3. ApiClientService (src/services/api-client.service.ts)

   • HTTP client for Selkie backend communication
   • Automatically includes JWT token in Authorization header
   • Handles errors and provides typed responses

Client-Side Cryptography

All cryptographic operations occur client-side. The backend never sees:

• User passwords
• Plaintext User Master Keys (UMK)
• User private keys
• Plaintext secrets

Key hierarchy:

1. Password → KEK (via Argon2id) → UMK
2. UMK → User Private Key
3. User Private Key → unwrap DEK
4. DEK → decrypt secret

Development

# Run in development mode (ts-node)
npm run dev

# Build TypeScript
npm run build

# Watch mode
npm run watch

# Lint
npm run lint

Security Notes

• JWT tokens stored in OS keychain, not config files
• Encrypted UMK stored in keychain (not plaintext)
• User private key always encrypted with UMK
• DEKs never stored, only wrapped versions
• Password never leaves the client
• All crypto happens client-side

Dependencies

• commander: CLI framework
• axios: HTTP client
• chalk: Terminal colors
• ora: Loading spinners
• inquirer: Interactive prompts
• conf: Configuration management
• keytar: OS keychain access
• bip39: BIP39 mnemonic support
• tweetnacl: Crypto operations

Phase 6A Complete

This implements Phase 6A: CLI Foundation

• ✅ CLI package initialized
• ✅ Commander.js framework set up
• ✅ Config management (server URL, user info)
• ✅ Secure token storage (OS keychain)
• ✅ HTTP client with auth headers

Next: Phase 6B (Crypto Operations) and Phase 6C (Auth Commands)