Selkie CLI

Zero-trust secret management command-line interface.

Installation

``bash


Install from npm

npm install -g selkie-cli

Or use npx

npx selkie-cli --help
`

$3

`bash


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

$3

`bash


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
`

$3

`bash


List objects you have access to

selkie list

Get and decrypt a secret

selkie get

Create a new secret

selkie create --type ssh-key --name "Production Server" --paranoid

Update a secret (creates new version)

selkie update

Delete a secret

selkie delete
`

$3

`bash


Grant user access to an object

selkie grant --role CONSUMER

Revoke user access

selkie revoke
`

$3

`bash


Show current authenticated user

selkie whoami

Display recovery mnemonic (SAVE THIS SECURELY)

selkie backup

Recover account from mnemonic

selkie recover

Logout

selkie logout
`

Architecture

$3

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

$3

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

`bash


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)