keyvault-sh

Zero-knowledge secrets management CLI for KeyVault.

Installation

npm install -g keyvault-sh
# or
bun add -g keyvault-sh

Quick Start

1. Login with your API token:

   kv login

   Get your API token from keyvault.sh/dashboard/tokens

2. Unlock your vault:

   kv unlock

   Enter your master password to decrypt secrets locally.

3. Initialize a project:

   cd your-project
   kv init

   Select your project and default environment.

4. Pull secrets:

   kv pull

   Downloads and decrypts secrets to .env

5. Run with secrets:

   kv run npm start

   Injects secrets as environment variables.

Commands

Authentication

| Command | Description | |---------|-------------| | kv login | Authenticate with an API token | | kv logout | Clear credentials and session | | kv unlock | Unlock vault with master password | | kv lock | Lock vault (clear session) |

Project Management

| Command | Description | |---------|-------------| | kv init | Set up project configuration | | kv list | List accessible projects |

Secret Operations

| Command | Description | |---------|-------------| | kv pull | Fetch and decrypt secrets | | kv push | Encrypt and upload secrets | | kv run <cmd> | Run command with secrets injected |

Options

kv pull

• -e, --env <id> - Environment ID (overrides .keyvault.json)
• -o, --output <file> - Output file (default: .env)
• -f, --force - Overwrite without confirmation

kv push

• -e, --env <id> - Environment ID (overrides .keyvault.json)
• -i, --input <file> - Input file (default: .env)
• -f, --force - Push without confirmation
• -d, --dry-run - Preview changes without pushing

kv run

• -e, --env <id> - Environment ID (overrides .keyvault.json)

Environment Variables

| Variable | Description | |----------|-------------| | KEYVAULT_TOKEN | API token (overrides config) | | KEYVAULT_API_URL | API URL (default: https://keyvault.sh) |

Configuration Files

~/.keyvault/config.json

Stores your API token and user info. Created by kv login.

.keyvault.json

Project-specific configuration. Created by kv init.

{
  "projectId": "...",
  "environmentId": "...",
  "organizationId": "..."
}

Security

• Zero-knowledge: Your master password never leaves your device
• Local decryption: Secrets are decrypted client-side with AES-256-GCM
• Session caching: Vault key cached for 24 hours with machine-specific encryption
• File permissions: Config files created with 0600 permissions

License

MIT