Skip to main content

Getting Started: For General Users

This guide is for users who want a simple, secure way to manage passwords, API keys, and other secrets using the Desktop App or basic CLI commands.

What You'll Learn​

  • Install and set up the Desktop App
  • Create your secure vault
  • Add, view, and manage your secrets
  • Keep your credentials organized and safe

Why secretctl?​

  • Completely Local: Your secrets never leave your computer
  • No Account Required: No sign-up, no cloud sync, no subscription
  • Strong Encryption: Military-grade AES-256 encryption
  • Simple Interface: Easy-to-use desktop application

Build from Source​

The desktop app is currently available by building from source. Pre-built binaries will be available in future releases.

Requirements:

Build Steps:

# Clone the repository
git clone https://github.com/forest6511/secretctl.git
cd secretctl/desktop

# Build the app
wails build

The compiled app will be in desktop/build/bin/.

Step 3: Create Your Vault​

  1. Open the secretctl app
  2. Click "Create New Vault"
  3. Enter a strong master password
  4. Confirm your password
  5. Click "Create"
Choosing a Master Password
  • Minimum 8 characters required, 12+ recommended
  • Mix letters, numbers, and symbols
  • Consider using a passphrase like "correct-horse-battery-staple"
  • Write it down and store it safely - there's no recovery if you forget it!

Step 4: Add Your First Secret​

  1. Click the "+" button or "Add Secret"
  2. Enter a name (e.g., "Gmail Password" or "OPENAI_API_KEY")
  3. Enter the secret value
  4. Optionally add:
    • Notes: Additional information
    • URL: Related website
    • Tags: Categories like "email", "work", "api"
  5. Click "Save"

Step 5: View and Use Secrets​

  • View: Click on any secret to see details
  • Copy: Click the copy icon to copy to clipboard (auto-clears after 30 seconds)
  • Search: Use the search bar to find secrets quickly
  • Filter: Filter by tags or date

Step 6: Stay Secure​

  • The app auto-locks after 15 minutes of inactivity
  • Lock manually: Click the lock icon or use Cmd+L (Mac) / Ctrl+L (Windows)
  • Always lock before leaving your computer

Option 2: Command Line (CLI)​

If you prefer using the terminal:

Install​

macOS (Apple Silicon):

curl -LO https://github.com/forest6511/secretctl/releases/latest/download/secretctl-darwin-arm64
chmod +x secretctl-darwin-arm64
sudo mv secretctl-darwin-arm64 /usr/local/bin/secretctl

macOS (Intel):

curl -LO https://github.com/forest6511/secretctl/releases/latest/download/secretctl-darwin-amd64
chmod +x secretctl-darwin-amd64
sudo mv secretctl-darwin-amd64 /usr/local/bin/secretctl

Linux:

curl -LO https://github.com/forest6511/secretctl/releases/latest/download/secretctl-linux-amd64
chmod +x secretctl-linux-amd64
sudo mv secretctl-linux-amd64 /usr/local/bin/secretctl

Windows: Download secretctl-windows-amd64.exe from GitHub Releases.

Basic Commands​

# Create your vault
secretctl init

# Add a secret
echo "my-password-123" | secretctl set "Gmail Password"

# View a secret
secretctl get "Gmail Password"

# List all secrets
secretctl list

# Delete a secret
secretctl delete "Gmail Password"

Organizing Your Secrets​

Use Key Prefixes​

Organize secrets by category using prefixes:

email/gmail
email/outlook
social/twitter
social/facebook
work/github
work/aws_key
banking/chase

Use Tags​

Add tags when creating secrets:

  • Desktop: Enter tags in the Tags field
  • CLI: echo "value" | secretctl set KEY --tags "work,api,important"

Add Notes and URLs​

Keep track of where each secret is used:

  • Desktop: Fill in the Notes and URL fields
  • CLI: echo "value" | secretctl set KEY --notes "Main account" --url "https://example.com"

Backup Your Secrets​

Create a Backup​

Desktop: Menu → File → Backup Vault

CLI:

secretctl backup -o ~/Desktop/my-secrets-backup.enc

The backup is encrypted with your master password.

Restore from Backup​

Desktop: Menu → File → Restore from Backup

CLI:

secretctl restore ~/Desktop/my-secrets-backup.enc

Keyboard Shortcuts (Desktop App)​

ActionmacOSWindows/Linux
Lock vaultCmd+LCtrl+L
New secretCmd+NCtrl+N
SearchCmd+FCtrl+F
Copy valueCmd+CCtrl+C
QuitCmd+QCtrl+Q

Frequently Asked Questions​

What if I forget my master password?​

Unfortunately, there's no recovery option. The master password is the only way to decrypt your secrets. We recommend:

  • Writing it down and storing it in a safe place
  • Using a memorable passphrase

Are my secrets synced to the cloud?​

No. secretctl is completely local. Your secrets are stored only on your computer in an encrypted file.

Can I use it on multiple computers?​

Yes, but you'll need to manually transfer your vault:

  1. Create a backup on Computer A
  2. Copy the backup file to Computer B
  3. Restore the backup on Computer B

Is it safe?​

Yes. secretctl uses:

  • AES-256-GCM encryption (same as banks and governments)
  • Argon2id key derivation (protects against password cracking)
  • Local-only storage (no network exposure)

Next Steps​