docs: add comprehensive documentation for secure credential storage

- Add security best practices reference page covering all storage methods
- Update authentication docs with keyring storage option
- Update installation docs to mention secure-storage feature
- Update profiles documentation with detailed keyring usage
- Add security page to documentation index

Completes documentation for #180

Author: joshrotenberg

docs/src/SUMMARY.md

@@ -78,6 +78,7 @@
 
 - [Environment Variables](./reference/environment-variables.md)
 - [Configuration File](./reference/config-file.md)
+- [Security Best Practices](./reference/security.md)
 - [Troubleshooting](./reference/troubleshooting.md)
 - [Best Practices](./reference/best-practices.md)
 - [API Reference](./reference/api.md)

docs/src/features/profiles.md

@@ -215,29 +215,150 @@ jobs:
             --data @database.json --wait
 ```
 
+## Secure Credential Storage
+
+### Using OS Keyring (Recommended)
+
+When compiled with the `secure-storage` feature, redisctl can store credentials in your operating system's secure keyring instead of plaintext in the config file.
+
+#### Supported Platforms
+- **macOS**: Keychain
+- **Windows**: Windows Credential Store  
+- **Linux**: Secret Service (GNOME Keyring, KWallet)
+
+#### Installation with Secure Storage
+```bash
+# Install from source with secure storage
+cargo install redisctl --features secure-storage
+
+# Or build locally
+cargo build --release --features secure-storage
+```
+
+#### Creating Secure Profiles
+```bash
+# Create profile with keyring storage
+redisctl profile set prod-secure \
+  --deployment cloud \
+  --api-key "your-api-key" \
+  --api-secret "your-api-secret" \
+  --use-keyring  # Store in OS keyring
+
+# For Enterprise profiles
+redisctl profile set enterprise-secure \
+  --deployment enterprise \
+  --url "https://cluster.example.com:9443" \
+  --username "[email protected]" \
+  --password "your-password" \
+  --use-keyring
+```
+
+#### How It Works
+When using `--use-keyring`, credentials are:
+1. Stored securely in your OS keyring
+2. Referenced in config.toml with `keyring:` prefix
+3. Retrieved automatically when needed
+
+Example config.toml with keyring references:
+```toml
+[profiles.prod-secure]
+deployment_type = "cloud"
+api_key = "keyring:prod-secure-api-key"      # Stored in keyring
+api_secret = "keyring:prod-secure-api-secret" # Stored in keyring  
+api_url = "https://api.redislabs.com/v1"     # Non-sensitive, plaintext
+```
+
+#### Storage Priority
+Credentials are resolved in this order:
+1. **Environment variables** (highest priority)
+2. **OS keyring** (if value starts with `keyring:`)
+3. **Plaintext** in config file (fallback)
+
+#### Managing Keyring Credentials
+```bash
+# Update credentials (will update keyring if already using it)
+redisctl profile set prod-secure \
+  --api-key "new-key" \
+  --use-keyring
+
+# View profile (keyring values are masked)
+redisctl profile show prod-secure
+# Output:
+# Profile: prod-secure
+# Type: cloud
+# API Key: keyring:...
+# API URL: https://api.redislabs.com/v1
+```
+
 ## Security Best Practices
 
-### Protecting Credentials
+### Credential Storage Options
+
+Choose the appropriate storage method based on your security requirements:
+
+1. **OS Keyring (Most Secure)**
+   - Use `--use-keyring` when creating profiles
+   - Credentials encrypted by OS
+   - Requires `secure-storage` feature
+   ```bash
+   redisctl profile set prod --use-keyring ...
+   ```
+
+2. **Environment Variables (CI/CD Friendly)**
+   - No storage, runtime only
+   - Good for automation
+   ```bash
+   export REDIS_CLOUD_API_KEY="key"
+   export REDIS_CLOUD_API_SECRET="secret"
+   ```
 
-1. **Never commit credentials**: Keep config.toml in .gitignore
-2. **Use environment variables**: Store secrets in environment
-3. **Restrict file permissions**: 
+3. **Plaintext Config (Development Only)**
+   - Simple but insecure
+   - Only for development/testing
+   - Protect with file permissions:
    ```bash
    chmod 600 ~/.config/redisctl/config.toml
    ```
-4. **Rotate credentials regularly**: Update API keys periodically
 
-### Secure Profile Template
+### Security Checklist
+
+1. **Never commit credentials**: Add config.toml to .gitignore
+2. **Use keyring for production**: Store production credentials securely
+3. **Rotate credentials regularly**: Update API keys periodically
+4. **Audit profile usage**: Monitor credential access
+5. **Use environment variables in CI/CD**: Keep secrets out of config files
+
+### Secure Profile Templates
+
+#### Production with Keyring
+```bash
+# Create secure production profile
+redisctl profile set production \
+  --deployment cloud \
+  --api-key "$PROD_KEY" \
+  --api-secret "$PROD_SECRET" \
+  --use-keyring
+```
+
+#### CI/CD with Environment Variables
 ```toml
-# Use environment variables for sensitive data
-[profiles.secure]
+# config.toml for CI/CD
+[profiles.ci]
 deployment_type = "cloud"
 api_key = "${REDIS_CLOUD_API_KEY}"
 api_secret = "${REDIS_CLOUD_API_SECRET}"
+api_url = "${REDIS_API_URL:-https://api.redislabs.com/v1}"
+```
 
-# Store in secure vault
-# export REDIS_CLOUD_API_KEY=$(vault read -field=key secret/redis)
-# export REDIS_CLOUD_API_SECRET=$(vault read -field=secret secret/redis)
+#### Development with Mixed Storage
+```toml
+# Development profile with mixed storage
+[profiles.dev]
+deployment_type = "enterprise"
+url = "https://dev-cluster:9443"     # Non-sensitive
+username = "[email protected]"         # Non-sensitive
+password = "keyring:dev-password"    # Sensitive, in keyring
+insecure = true                      # Dev setting
 ```
 
 ### Profile Audit

docs/src/getting-started/authentication.md

@@ -17,7 +17,36 @@ Redis Cloud uses API key authentication:
 
 ### Setting Up Authentication
 
-Use environment variables:
+#### Option 1: Secure OS Keyring (Recommended)
+
+When compiled with the `secure-storage` feature, store credentials securely in your OS keyring:
+
+```bash
+# Install with secure storage support
+cargo install redisctl --features secure-storage
+
+# Create secure profile
+redisctl profile set cloud \
+  --deployment cloud \
+  --api-key "your-account-key" \
+  --api-secret "your-secret-key" \
+  --use-keyring  # Stores in OS keyring
+
+# Test it works
+redisctl --profile cloud api cloud get /
+```
+
+Your config will contain secure references:
+```toml
+[profiles.cloud]
+deployment_type = "cloud"
+api_key = "keyring:cloud-api-key"      # Actual value in OS keyring
+api_secret = "keyring:cloud-api-secret" # Actual value in OS keyring
+```
+
+#### Option 2: Environment Variables
+
+Use environment variables (good for CI/CD):
 
 ```bash
 export REDIS_CLOUD_API_KEY="your-account-key"
@@ -27,7 +56,9 @@ export REDIS_CLOUD_API_SECRET="your-secret-key"
 redisctl api cloud get /
 ```
 
-Or create a configuration file at `~/.config/redisctl/config.toml`:
+#### Option 3: Configuration File (Development Only)
+
+For development only, you can use plaintext config at `~/.config/redisctl/config.toml`:
 
 ```toml
 [profiles.cloud]
@@ -36,6 +67,8 @@ api_key = "your-account-key"
 api_secret = "your-secret-key"
 ```
 
+⚠️ **Warning**: This stores credentials in plaintext. Use keyring or environment variables for production!
+
 ## Redis Enterprise
 
 Redis Enterprise uses basic authentication with username/password.
@@ -47,6 +80,38 @@ Redis Enterprise uses basic authentication with username/password.
 
 ### Setting Up Authentication
 
+#### Option 1: Secure OS Keyring (Recommended)
+
+Store credentials securely in your OS keyring:
+
+```bash
+# Create secure profile
+redisctl profile set enterprise \
+  --deployment enterprise \
+  --url "https://cluster.example.com:9443" \
+  --username "[email protected]" \
+  --password "your-password" \
+  --use-keyring  # Stores in OS keyring
+
+# For self-signed certificates
+redisctl profile set enterprise --insecure true
+
+# Test it works
+redisctl --profile enterprise api enterprise get /v1/cluster
+```
+
+Your config will contain secure references:
+```toml
+[profiles.enterprise]
+deployment_type = "enterprise"
+url = "https://cluster.example.com:9443"
+username = "keyring:enterprise-username"  # Actual value in OS keyring
+password = "keyring:enterprise-password"  # Actual value in OS keyring
+insecure = false
+```
+
+#### Option 2: Environment Variables
+
 Use environment variables:
 
 ```bash
@@ -61,7 +126,9 @@ export REDIS_ENTERPRISE_INSECURE="true"
 redisctl api enterprise get /v1/cluster
 ```
 
-Or add to `~/.config/redisctl/config.toml`:
+#### Option 3: Configuration File (Development Only)
+
+For development only, add to `~/.config/redisctl/config.toml`:
 
 ```toml
 [profiles.enterprise]
@@ -72,6 +139,8 @@ password = "your-password"
 insecure = true  # For self-signed certs
 ```
 
+⚠️ **Warning**: This stores credentials in plaintext. Use keyring or environment variables for production!
+
 ## Security Tips
 
 1. **Never commit credentials** - Use environment variables or secure vaults

docs/src/getting-started/installation.md

@@ -24,15 +24,35 @@ Download the `.zip` file from the releases page and extract to a directory in yo
 If you have Rust installed:
 
 ```bash
+# Basic installation
 cargo install redisctl
+
+# With secure credential storage support (recommended)
+cargo install redisctl --features secure-storage
 ```
 
+### Feature Flags
+
+| Feature | Description |
+|---------|-------------|
+| `secure-storage` | Enables OS keyring support for secure credential storage (recommended) |
+| `cloud-only` | Builds only Cloud functionality (smaller binary) |
+| `enterprise-only` | Builds only Enterprise functionality (smaller binary) |
+
 ## From Source
 
 ```bash
 git clone https://github.com/joshrotenberg/redisctl.git
 cd redisctl
+
+# Basic installation
 cargo install --path crates/redisctl
+
+# With secure storage support (recommended)
+cargo install --path crates/redisctl --features secure-storage
+
+# Development build with all features
+cargo build --release --all-features
 ```
 
 ## Docker