Simple, cross-platform encrypted secrets manager with automatic sync, IPFS audit logs, and multi-environment support. Just run lsh sync and start managing your secrets.
npm install lsh-frameworkThe simplest way to sync .env files across all your machines.
lsh is an encrypted secrets manager that syncs your environment files across development machines with AES-256 encryption via the IPFS network. Push once, pull anywhere.



- Type Safety Milestone - All @typescript-eslint/no-explicit-any warnings eliminated (51+ → 0)
- Constants Centralization - Hardcoded strings moved to constants modules
- API Response Builder - Standardized API responses with sendSuccess, sendError, ApiErrors
- Test Coverage - 59 new tests for constants modules (142 total constants tests)
- Code Quality - Lint warnings reduced from 744 to 550 (26.1% reduction)
See Release Notes for full details.
``bashInstall
npm install -g lsh-framework
That's it! Your secrets are now encrypted and synced.
Why LSH?
| Feature | LSH | dotenv-vault | 1Password | Doppler |
|---------|-----|--------------|-----------|---------|
| Free | Yes | Limited | No | No |
| Self-Hosted | Yes | No | No | No |
| Auto Rotation | Built-in | No | No | No |
| IPFS Storage | Yes | No | No | No |
| Setup Time | 2 min | 5 min | 10 min | 10 min |
Core Commands
`bash
Setup
lsh init # Interactive setup wizard
lsh key # Generate encryption keyDaily use
lsh push # Upload encrypted .env to cloud
lsh pull # Download .env from cloud
lsh sync # Smart sync (auto push/pull)
lsh list # List local secrets
lsh env # List cloud environmentsGet/Set individual secrets
lsh get API_KEY # Get a secret value
lsh set API_KEY xxx # Set a secret value
printenv | lsh set # Batch import from stdinMulti-environment
lsh push --env prod
lsh pull --env staging
`How It Works
`
Your Machine Storacha (IPFS Network)
┌─────────────┐ ┌─────────────────────┐
│ .env │ AES-256 │ Encrypted Blob │
│ (secrets) │ ───encrypt───► │ (content-addressed)│
└─────────────┘ └─────────────────────┘
│
▼
Another Machine ┌─────────────────────┐
┌─────────────┐ AES-256 │ Registry │
│ .env │ ◄──decrypt──── │ (points to blob) │
│ (secrets) │ └─────────────────────┘
└─────────────┘
`1. Your
.env is encrypted locally with AES-256
2. Encrypted data uploads to IPFS via Storacha
3. A registry tracks the latest version per repository
4. Other machines pull via the content ID (CID)
5. Decryption happens locally with your shared keyInstallation
$3
- Node.js 20.18.0+
- npm 10.0.0+$3
`bash
npm install -g lsh-framework
lsh --version
`$3
`bash
Interactive setup (handles everything)
lsh initOr manual setup:
lsh key # Generate encryption key
echo "LSH_SECRETS_KEY=..." >> .env
lsh push # Push to cloud
`Multi-Host Sync
The killer feature. Sync secrets across all your machines:
`bash
Machine 1: Push secrets
cd ~/repos/my-project
lsh pushMachine 2: Pull secrets (same encryption key)
cd ~/repos/my-project
lsh pullThat's it - your .env is synced!
`$3
`bash
1. Install LSH
npm install -g lsh-framework2. Authenticate with Storacha (one-time)
lsh storacha login your@email.com3. Add your encryption key
echo "LSH_SECRETS_KEY=your-shared-key" > .env4. Pull secrets
lsh pull
`Multi-Environment Support
`bash
Development
lsh push --env devStaging
lsh push --file .env.staging --env stagingProduction
lsh push --file .env.prod --env prodPull any environment
lsh pull --env prod
`Team Collaboration
Setup (Team Lead):
`bash
lsh key # Generate team key
lsh push --env prod # Push team secrets
Share LSH_SECRETS_KEY via 1Password/LastPass
`Team Members:
`bash
Get key from 1Password
echo "LSH_SECRETS_KEY=shared-key" > .env
lsh pull --env prod
Done!
`Automatic Secret Rotation
Use the built-in daemon for automated rotation:
`bash
Start daemon
lsh daemon startSchedule monthly key rotation
lsh cron add \
--name "rotate-keys" \
--schedule "0 0 1 " \
--command "./scripts/rotate.sh && lsh push"List scheduled jobs
lsh cron list
`Export Formats
Export secrets in multiple formats:
`bash
lsh list --format json # JSON
lsh list --format yaml # YAML
lsh list --format toml # TOML
lsh list --format export # Shell export statementsLoad into current shell
eval "$(lsh list --format export)"
`Security
- AES-256-CBC encryption for all secrets
- Content-addressed storage - tamper-proof IPFS CIDs
- Zero-knowledge - Storacha never sees your unencrypted data
- Local-first - Works offline with cached secrets
$3
DO:
- Store
LSH_SECRETS_KEY in shell profile (~/.zshrc)
- Share keys via password manager (1Password, etc.)
- Use different keys per project/team
- Rotate keys periodicallyDON'T:
- Commit
LSH_SECRETS_KEY to git
- Share keys in plain text (Slack, email)
- Store production secrets in dev environmentTroubleshooting
$3
`bash
Check what environments exist
lsh envPush if missing
lsh push --env dev
`$3
Wrong encryption key. Make sure
LSH_SECRETS_KEY matches.`bash
Check current key
cat .env | grep LSH_SECRETS_KEYIf lost, generate new key and re-push
lsh key
lsh push --force
`$3
`bash
lsh storacha login your@email.com
Check email for verification
`$3
v3.0.0 fix: Pull now automatically checks the Storacha registry when local metadata is missing.
`bash
If secrets were pushed before, pull should auto-recover
lsh pullIf truly no secrets exist, push first
lsh push
`Documentation
- Secrets Guide - Complete secrets management guide
- Smart Sync Guide - One-command sync guide
- Quick Reference - Daily use cheatsheet
- Installation - Detailed installation
- Developer Guide - Contributing to LSH
Advanced Features
LSH includes a full automation platform:
- Persistent Daemon - Background job execution
- Cron Scheduling - Time-based job scheduling
- REST API - HTTP API for integration
- CI/CD Webhooks - GitHub/GitLab webhook support
- POSIX Shell - Interactive shell with ZSH features
`bash
Start daemon
lsh daemon startAPI server
LSH_API_KEY=xxx lsh api start --port 3030Interactive shell
lsh -i
`Configuration
$3
`bash
Required
LSH_SECRETS_KEY=Optional - Storacha (default enabled)
LSH_STORACHA_ENABLED=trueOptional - Supabase backend
SUPABASE_URL=https://xxx.supabase.co
SUPABASE_ANON_KEY=Optional - API server
LSH_API_ENABLED=true
LSH_API_PORT=3030
LSH_API_KEY=
`$3
`
~/.config/lsh/lshrc # LSH configuration
~/.lsh/secrets-cache/ # Encrypted secrets cache
~/.lsh/secrets-metadata.json # Metadata index
`Contributing
`bash
git clone https://github.com/gwicho38/lsh.git
cd lsh
npm install
npm run build
npm test
npm link
`See CLAUDE.md for development guidelines.
License
MIT
Support
- Issues: https://github.com/gwicho38/lsh/issues
- Discussions: https://github.com/gwicho38/lsh/discussions
---
Stop copying
.env files. Start syncing.`bash
npm install -g lsh-framework
lsh init
``