🕶️ Cloakx - Secure Secret Manager

Cloakx is a powerful, developer-friendly secret management tool that combines a secure CLI and beautiful web UI. Manage encrypted secrets locally with ease — perfect for developers, DevOps, and teams.

🔐 Secure. Simple. Scalable. Store API keys, tokens, database credentials, and sensitive data with military-grade encryption (AES-256-GCM) and password protection.

---

✨ Key Features

🔐 Security

• AES-256-GCM encryption for all secrets
• PBKDF2 password hashing
• Password-protected vault access
• Local-first architecture (no cloud required)
• Session management with auto-logout

💾 Secret Management

• Add, retrieve, update, and delete secrets in seconds
• Multiple environment support (default, production, staging, custom)
• Metadata tagging for organizing secrets
• Expiration tracking for time-sensitive secrets
• Bulk import/export with .env format support

🌐 User Interfaces

• CLI: Full-featured command-line interface with 17+ commands
• Web UI: Modern, responsive dashboard for browser-based access
• Environment Switching: Easily manage secrets across environments
• Real-time Sync: Keep secrets synchronized

🚀 Developer Features

• Command injection with run command (auto-inject as env vars)
• One-time encryption/decryption utilities
• JSON and YAML export/import
• Git-friendly (add ~/.cloakx to .gitignore)
• Cross-platform support (Windows, macOS, Linux)

---

📦 Installation

Option 1: Global NPM Installation

npm install -g cloakx
# or with yarn
yarn global add cloakx
# or with pnpm
pnpm add -g cloakx

Option 2: Local Project Installation

npm install cloakx
npx cloakx --help

Option 3: Development Installation (from source)

git clone https://github.com/yourusername/cloak.git
cd cloak
npm install
npm run build
node dist/src/index.js --help

---

🚀 Quick Start (2 minutes)

1. Initialize & Login

cloakx login
# Creates a new vault with your password

2. Add Your First Secret

cloakx set API_KEY "sk_live_abc123xyz"
cloakx set DATABASE_URL "postgres://localhost:5432/mydb"

3. Retrieve Secrets

cloakx get API_KEY
# Output: sk_live_abc123xyz

cloakx get DATABASE_URL
# Output: postgres://localhost:5432/mydb

4. List All Secrets

cloakx list
# Shows all stored keys

5. Start Web UI

cloakx web
# Opens http://127.0.0.1:1201

---

🎯 Multi-Parameter Commands (Pro Tips)

Combine Parameters for Advanced Usage

Most Cloakx commands support multiple parameters that can be combined in any order:

Common Parameters

• --env <environment> - Specify which environment to use
• --expires <duration> - Set expiration time (7d, 24h, 2026-12-31)
• --tags <tags> - Add comma-separated tags (payment,critical,stripe)

Real-World Examples

Production Environment with Expiration & Tags:

# Set API key for production with 7-day expiration
cloakx set API_KEY "sk_live_abc123" --env production --expires 7d --tags "payment,external"

# Update database password with 30-day expiration
cloakx upd DB_PASSWORD "newpass" --env production --expires 30d --tags "database,critical"

Multi-Environment Management:

# Development
cloakx set DATABASE_URL "localhost:5432" --env development --tags "local"

# Staging
cloakx set DATABASE_URL "staging.db.com" --env staging --expires 30d --tags "database,staging"

# Production
cloakx set DATABASE_URL "prod.db.com" --env production --expires 90d --tags "database,critical"

Filtering with Multiple Parameters:

# List critical secrets in production environment
cloakx list --env production --tag critical

# Show all payment-related secrets
cloakx list --tag payment

# View expired secrets across all environments
cloakx list --expired

Parameter Order Doesn't Matter:

# All of these work identically:
cloakx set KEY "value" --env prod --expires 7d --tags "tag1"
cloakx set KEY "value" --tags "tag1" --env prod --expires 7d
cloakx set KEY "value" --expires 7d --tags "tag1" --env prod

Command Parameter Reference Table

Command	--env	--expires	--tags	--file	--masked	--expired	--tag
set	✅	✅	✅	-	-	-	-
update	✅	✅	✅	-	-	-	-
get	✅	-	-	-	-	-	-
list	✅	-	-	-	-	✅	✅
del	✅	-	-	-	-	-	-
export	✅	-	-	✅	✅	-	-
import	✅	-	-	-	-	-	-
run	✅	-	-	-	-	-	-

---

📖 Complete CLI Command Reference

🔐 Authentication Commands

login - Initialize or authenticate vault

cloakx login
# Interactive: Enter your vault password
# Creates ~/.cloakx/ directory with encrypted vault

logout - Clear current session

cloakx logout
# Session is cleared, requires login for next operations

status - Check authentication status

cloakx status
# Shows login status and active environment

change-password - Update vault password

cloakx change-password
# Interactive: Old password → New password → Confirm
# Re-encrypts entire vault with new password

---

💾 Secret Management Commands

set | add - Add or update a secret

# Basic usage
cloakx set DATABASE_URL "postgres://localhost:5432/mydb"
cloakx add API_KEY "sk_live_123abc"

# With specific environment
cloakx set DATABASE_URL "postgres://prod.com/db" --env production

# With tags (for organization)
cloakx set STRIPE_KEY "rk_test_123" --tags "payment,stripe,critical"

# With expiration
cloakx set TEMP_TOKEN "token_xyz" --expires "7d"
cloakx set API_KEY "key_abc" --expires "2026-12-31"

# 💡 COMBINE MULTIPLE PARAMETERS (any order)
cloakx set API_KEY "sk_live_123" --env production --expires 7d
cloakx set DB_URL "postgres://prod" --env production --expires 30d --tags "database,critical"
cloakx set SECRET "value" --tags "payment" --expires 14d --env staging

Available Options:

• --env <environment> - Target environment (default: current environment)
• --expires <duration> - Expiration time (supports: 7d, 24h, 2026-12-31)
• --tags <tags> - Comma-separated tags (e.g., payment,stripe,critical)

get - Retrieve a secret

# Get from current environment
cloakx get DATABASE_URL

# Get from specific environment
cloakx get DATABASE_URL --env production

# Examples
cloakx get API_KEY
cloakx get STRIPE_KEY --env production

# 💡 RETRIEVE FROM ANY ENVIRONMENT
cloakx get DB_URL --env staging
cloakx get API_KEY --env production

Available Options:

• --env <environment> - Retrieve from specific environment (default: current)

list - Show all secrets

# List in current environment
cloakx list

# List in specific environment
cloakx list --env production
cloakx list --env staging

# Filter by tag
cloakx list --tag critical
cloakx list --tag payment

# Show expired secrets
cloakx list --expired

# 💡 COMBINE FILTERS
cloakx list --env production --tag critical
cloakx list --env staging --tag payment
cloakx list --tag critical --expired

Available Options:

• --env <environment> - Filter by environment
• --tag <tag> - Filter by tag name
• --expired - Show only expired secrets
• --all - Show all environments

update | upd - Modify a secret

# Update value
cloakx update DATABASE_URL "postgres://newhost:5432/db"
cloakx upd API_KEY "new_key_value_456"

# Update with new expiration
cloakx update TEMP_TOKEN "new_token" --expires "30d"

# Update in specific environment
cloakx update DATABASE_URL "postgres://prod-db.com/db" --env production

# 💡 COMBINE MULTIPLE PARAMETERS
cloakx upd API_KEY "new_key" --env production --expires 7d
cloakx update DB_PASSWORD "newpass" --env production --expires 30d --tags "database,critical"

Available Options:

• --env <environment> - Target environment
• --expires <duration> - New expiration time
• --tags <tags> - Update tags

del - Delete a secret

# Delete from current environment
cloakx del API_KEY
cloakx del DATABASE_URL

# Delete from specific environment
cloakx del DATABASE_URL --env staging

# 💡 DELETE FROM ANY ENVIRONMENT
cloakx del SECRET --env production
cloakx del TEMP_TOKEN --env staging

Available Options:

• --env <environment> - Delete from specific environment (default: current)

---

🔧 Utility Commands

encrypt - One-time encryption (no vault storage)

cloakx encrypt "sensitive data here"
# Output: Encrypted base64 string
# Use for: Sharing encrypted values via email/chat

decrypt - One-time decryption

cloakx decrypt "encrypted_base64_string_here"
# Output: Decrypted plaintext
# Use for: Decrypting shared encrypted values

export - Export secrets as files

# Export to stdout (.env format)
cloakx export

# Export to file
cloakx export --file backup.env
cloakx export --file prod-secrets.env --env production

# Export specific secret
cloakx export DATABASE_URL

# Export with masked values
cloakx export --masked

# Copy to clipboard
cloakx export --copy

# 💡 COMBINE PARAMETERS
cloakx export --file .env.production --env production
cloakx export --file .env.staging --env staging --masked
cloakx export DATABASE_URL --env production

Available Options:

• --env <environment> - Export from specific environment
• --file <filename> - Export to file (default: stdout)
• --masked - Hide values (show key=*** only)
• --copy - Copy to clipboard

import - Import secrets from files

# Create a test file first
cat > secrets.env << EOF
DB_HOST=localhost
DB_USER=admin
DB_PASSWORD=secret123
EOF

# Import
cloakx import secrets.env

# Import to specific environment
cloakx import secrets.env --env production
cloakx import backup.env --env staging

# Import without prompting
cloakx import secrets.env --use-existing

# Supported formats
cloakx import config.json      # JSON
cloakx import secrets.env      # .env format
cloakx import config.yaml      # YAML

# 💡 COMBINE PARAMETERS
cloakx import secrets.env --env production --use-existing
cloakx import backup.env --env staging --use-existing

Available Options:

• --env <environment> - Import to specific environment
• --use-existing - Don't prompt on duplicate keys

---

🌍 Environment Management

env - Manage multiple environments

# List all environments
cloakx env list
# Output: default, production, staging, development

# Show current active environment
cloakx env current
# Output: production

# Create new environment
cloakx env create production
cloakx env create staging
cloakx env create development
cloakx env create test

# Switch to environment
cloakx env set default
cloakx env set production
cloakx env set staging

# Delete environment
cloakx env delete test

# Workflow example
cloakx env create production
cloakx env set production
cloakx set DATABASE_URL "postgres://prod.example.com/db"
cloakx set API_KEY "prod_key_xyz"

cloakx env set default
cloakx set DATABASE_URL "postgres://localhost/dev_db"

---

🚀 Advanced Commands

run - Execute command with injected secrets

# Create a test app
cat > app.js << EOF
console.log('DB:', process.env.DATABASE_URL);
console.log('API:', process.env.API_KEY);
EOF

# Run with all secrets injected as env vars
cloakx run node app.js

# Run from specific environment
cloakx run --env production node app.js
cloakx run --env staging npm start

# Run any command
cloakx run python app.py
cloakx run bash script.sh
cloakx run docker run myimage

# 💡 COMBINE WITH PARAMETERS
cloakx run --env production docker build -t myapp .
cloakx run --env staging npm start
cloa