591 lines
13 KiB
Markdown
591 lines
13 KiB
Markdown
# CLI Profile Management
|
|
|
|
The Attune CLI supports multiple named profiles, similar to SSH config or Kubernetes kubeconfig. This allows you to easily switch between different Attune servers (development, staging, production, etc.) without constantly changing configuration.
|
|
|
|
## Overview
|
|
|
|
Profiles are named configurations that store:
|
|
- API endpoint URL
|
|
- Authentication tokens (access and refresh)
|
|
- Output format preference (optional)
|
|
- Description (optional)
|
|
|
|
Each profile maintains its own authentication state, so you can be logged into multiple servers simultaneously.
|
|
|
|
## Configuration File
|
|
|
|
Profiles are stored in `~/.config/attune/config.yaml` (respects `$XDG_CONFIG_HOME`):
|
|
|
|
```yaml
|
|
current_profile: staging
|
|
profiles:
|
|
default:
|
|
api_url: http://localhost:8080
|
|
description: Default local server
|
|
staging:
|
|
api_url: https://staging.example.com
|
|
auth_token: eyJhbGc... # (stored securely)
|
|
refresh_token: eyJhbGc...
|
|
description: Staging environment
|
|
production:
|
|
api_url: https://api.example.com
|
|
auth_token: eyJhbGc...
|
|
refresh_token: eyJhbGc...
|
|
output_format: json
|
|
description: Production environment
|
|
default_output_format: table
|
|
```
|
|
|
|
## Profile Commands
|
|
|
|
### List All Profiles
|
|
|
|
```bash
|
|
attune config profiles
|
|
```
|
|
|
|
Output:
|
|
```
|
|
Profiles
|
|
• default
|
|
• staging (current)
|
|
• production
|
|
```
|
|
|
|
### Show Current Profile
|
|
|
|
```bash
|
|
attune config current
|
|
```
|
|
|
|
Output:
|
|
```
|
|
staging
|
|
```
|
|
|
|
### Add a Profile
|
|
|
|
```bash
|
|
attune config add-profile <name> --api-url <url> [--description <desc>]
|
|
```
|
|
|
|
Examples:
|
|
```bash
|
|
# Add staging profile
|
|
attune config add-profile staging \
|
|
--api-url https://staging.example.com \
|
|
--description "Staging environment"
|
|
|
|
# Add production profile
|
|
attune config add-profile production \
|
|
--api-url https://api.example.com \
|
|
--description "Production environment"
|
|
|
|
# Add local development profile with custom port
|
|
attune config add-profile dev \
|
|
--api-url http://localhost:3000 \
|
|
--description "Local development server"
|
|
```
|
|
|
|
### Switch Profile
|
|
|
|
```bash
|
|
attune config use <profile-name>
|
|
```
|
|
|
|
Example:
|
|
```bash
|
|
attune config use staging
|
|
# ✓ Switched to profile 'staging'
|
|
```
|
|
|
|
### Show Profile Details
|
|
|
|
```bash
|
|
attune config show-profile <profile-name>
|
|
```
|
|
|
|
Example:
|
|
```bash
|
|
attune config show-profile staging
|
|
```
|
|
|
|
Output:
|
|
```
|
|
Profile: staging
|
|
╭───────────────┬─────────────────────────────╮
|
|
│ Key ┆ Value │
|
|
╞═══════════════╪═════════════════════════════╡
|
|
│ API URL ┆ https://staging.example.com │
|
|
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
|
|
│ Auth Token ┆ *** │
|
|
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
|
|
│ Refresh Token ┆ *** │
|
|
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
|
|
│ Description ┆ Staging environment │
|
|
╰───────────────┴─────────────────────────────╯
|
|
```
|
|
|
|
### Remove a Profile
|
|
|
|
```bash
|
|
attune config remove-profile <profile-name>
|
|
```
|
|
|
|
Example:
|
|
```bash
|
|
attune config remove-profile old-dev
|
|
# ✓ Profile 'old-dev' removed
|
|
```
|
|
|
|
**Note**: You cannot remove:
|
|
- The `default` profile
|
|
- The currently active profile (switch to another profile first)
|
|
|
|
## Using Profiles
|
|
|
|
### Runtime Profile Override
|
|
|
|
Use the `--profile` flag to temporarily use a different profile without switching:
|
|
|
|
```bash
|
|
# List packs on production without switching
|
|
attune --profile production pack list
|
|
|
|
# Execute action on staging
|
|
attune --profile staging action execute monitoring.check
|
|
|
|
# Get execution from different environment
|
|
attune --profile dev execution show 123
|
|
```
|
|
|
|
The `--profile` flag is available on all commands and does not change your current profile setting.
|
|
|
|
### Environment Variable
|
|
|
|
Set the `ATTUNE_PROFILE` environment variable:
|
|
|
|
```bash
|
|
export ATTUNE_PROFILE=staging
|
|
attune pack list # Uses staging profile
|
|
```
|
|
|
|
### Precedence
|
|
|
|
When determining which profile to use:
|
|
|
|
1. `--profile` command-line flag (highest priority)
|
|
2. `ATTUNE_PROFILE` environment variable
|
|
3. `current_profile` in config file
|
|
4. `default` profile (fallback)
|
|
|
|
## Authentication Per Profile
|
|
|
|
Each profile maintains its own authentication state. You need to log in separately for each profile:
|
|
|
|
```bash
|
|
# Login to staging
|
|
attune config use staging
|
|
attune auth login --username admin
|
|
|
|
# Login to production
|
|
attune config use production
|
|
attune auth login --username admin
|
|
|
|
# Now you're authenticated to both environments
|
|
```
|
|
|
|
### Check Authentication Status
|
|
|
|
```bash
|
|
# Check current profile authentication
|
|
attune auth whoami
|
|
|
|
# Check specific profile
|
|
attune --profile staging auth whoami
|
|
attune --profile production auth whoami
|
|
```
|
|
|
|
### Logout from Profile
|
|
|
|
```bash
|
|
# Logout from current profile
|
|
attune auth logout
|
|
|
|
# Logout from specific profile
|
|
attune --profile staging auth logout
|
|
```
|
|
|
|
## Use Cases
|
|
|
|
### Development Workflow
|
|
|
|
```bash
|
|
# Setup profiles
|
|
attune config add-profile local --api-url http://localhost:8080
|
|
attune config add-profile staging --api-url https://staging.example.com
|
|
attune config add-profile prod --api-url https://api.example.com
|
|
|
|
# Work on local
|
|
attune config use local
|
|
attune pack install https://github.com/myorg/my-pack
|
|
|
|
# Test on staging
|
|
attune --profile staging pack list
|
|
|
|
# Deploy to production
|
|
attune --profile prod pack install https://github.com/myorg/my-pack --ref v1.0.0
|
|
```
|
|
|
|
### Multi-Tenant Management
|
|
|
|
```bash
|
|
# Setup tenant profiles
|
|
attune config add-profile tenant-a --api-url https://tenant-a.example.com
|
|
attune config add-profile tenant-b --api-url https://tenant-b.example.com
|
|
|
|
# Login to each tenant
|
|
attune config use tenant-a
|
|
attune auth login --username admin
|
|
|
|
attune config use tenant-b
|
|
attune auth login --username admin
|
|
|
|
# Monitor both tenants
|
|
attune --profile tenant-a execution list --status failed
|
|
attune --profile tenant-b execution list --status failed
|
|
```
|
|
|
|
### CI/CD Integration
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
# Deploy script for CI/CD
|
|
|
|
# Add ephemeral profile for CI environment
|
|
attune config add-profile ci --api-url "$CI_ATTUNE_API_URL"
|
|
|
|
# Login with CI credentials
|
|
attune --profile ci auth login \
|
|
--username "$CI_USERNAME" \
|
|
--password "$CI_PASSWORD"
|
|
|
|
# Deploy pack
|
|
attune --profile ci pack install "$PACK_REPO_URL" --ref "$GIT_TAG"
|
|
|
|
# Verify deployment
|
|
attune --profile ci pack show "$PACK_NAME"
|
|
|
|
# Cleanup (optional - config is typically ephemeral in CI)
|
|
attune config remove-profile ci
|
|
```
|
|
|
|
### Scripting with Profiles
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
# Check health across all environments
|
|
|
|
PROFILES=("dev" "staging" "production")
|
|
|
|
for profile in "${PROFILES[@]}"; do
|
|
echo "Checking $profile..."
|
|
|
|
# Execute health check
|
|
result=$(attune --profile "$profile" \
|
|
action execute core.health_check \
|
|
--wait -j 2>/dev/null)
|
|
|
|
if [ $? -eq 0 ]; then
|
|
status=$(echo "$result" | jq -r '.status')
|
|
echo " $profile: $status"
|
|
else
|
|
echo " $profile: ERROR"
|
|
fi
|
|
done
|
|
```
|
|
|
|
## Profile Configuration Options
|
|
|
|
### Per-Profile Output Format
|
|
|
|
Set a default output format for a specific profile:
|
|
|
|
```bash
|
|
attune config use production
|
|
attune config set output_format json
|
|
```
|
|
|
|
Now all commands on the production profile will default to JSON output:
|
|
|
|
```bash
|
|
attune config use production
|
|
attune pack list # Outputs JSON
|
|
|
|
attune config use staging
|
|
attune pack list # Outputs table (default)
|
|
```
|
|
|
|
### Update Profile API URL
|
|
|
|
```bash
|
|
# Switch to profile
|
|
attune config use staging
|
|
|
|
# Update API URL
|
|
attune config set api_url https://new-staging.example.com
|
|
|
|
# Or update directly
|
|
attune config add-profile staging --api-url https://new-staging.example.com
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
### 1. Use Descriptive Names
|
|
|
|
```bash
|
|
# Good
|
|
attune config add-profile staging-us-east --api-url ...
|
|
attune config add-profile prod-eu-west --api-url ...
|
|
|
|
# Avoid
|
|
attune config add-profile s1 --api-url ...
|
|
attune config add-profile p1 --api-url ...
|
|
```
|
|
|
|
### 2. Add Descriptions
|
|
|
|
```bash
|
|
attune config add-profile staging \
|
|
--api-url https://staging.example.com \
|
|
--description "Staging environment (US East)"
|
|
```
|
|
|
|
### 3. Keep Local as Default
|
|
|
|
Keep the `default` profile pointing to localhost for quick local testing:
|
|
|
|
```bash
|
|
# Default profile should be local
|
|
attune config use default
|
|
attune config get api_url
|
|
# http://localhost:8080
|
|
```
|
|
|
|
### 4. Profile Naming Convention
|
|
|
|
Use a consistent naming scheme:
|
|
- Environment-based: `dev`, `staging`, `prod`
|
|
- Region-based: `prod-us`, `prod-eu`, `prod-asia`
|
|
- Tenant-based: `tenant-acme`, `tenant-globex`
|
|
- Purpose-based: `local`, `ci`, `testing`
|
|
|
|
### 5. Verify Before Destructive Operations
|
|
|
|
Always verify you're on the correct profile before destructive operations:
|
|
|
|
```bash
|
|
# Check current profile
|
|
attune config current
|
|
|
|
# Or show API URL
|
|
attune config get api_url
|
|
|
|
# Then proceed
|
|
attune pack uninstall dangerous-pack
|
|
```
|
|
|
|
### 6. Use --profile for Queries
|
|
|
|
For read-only queries, use `--profile` instead of switching:
|
|
|
|
```bash
|
|
# Good - doesn't change current profile
|
|
attune --profile prod execution list
|
|
|
|
# Less ideal - changes current profile
|
|
attune config use prod
|
|
attune execution list
|
|
```
|
|
|
|
## Security Considerations
|
|
|
|
### Token Storage
|
|
|
|
Authentication tokens are stored in plaintext in the config file. Ensure proper file permissions:
|
|
|
|
```bash
|
|
chmod 600 ~/.config/attune/config.yaml
|
|
```
|
|
|
|
**Future Enhancement**: OS keyring integration for secure token storage.
|
|
|
|
### Production Profiles
|
|
|
|
For production profiles:
|
|
1. Use strong passwords
|
|
2. Enable MFA (when available)
|
|
3. Regularly rotate credentials
|
|
4. Limit token lifetime
|
|
5. Use service accounts in CI/CD
|
|
|
|
### Profile Separation
|
|
|
|
Keep credentials separated:
|
|
- Use different usernames for different environments
|
|
- Don't share production credentials with staging
|
|
- Use least-privilege access per environment
|
|
|
|
## Troubleshooting
|
|
|
|
### Profile Not Found
|
|
|
|
```
|
|
Error: Profile 'staging' does not exist
|
|
```
|
|
|
|
**Solution**: Add the profile first:
|
|
```bash
|
|
attune config add-profile staging --api-url https://staging.example.com
|
|
```
|
|
|
|
### Cannot Remove Active Profile
|
|
|
|
```
|
|
Error: Cannot remove active profile 'staging'. Switch to another profile first.
|
|
```
|
|
|
|
**Solution**: Switch to another profile:
|
|
```bash
|
|
attune config use default
|
|
attune config remove-profile staging
|
|
```
|
|
|
|
### Authentication Failed
|
|
|
|
If authentication fails after switching profiles:
|
|
|
|
```bash
|
|
# Check if logged in
|
|
attune auth whoami
|
|
|
|
# If not, login
|
|
attune auth login --username your-username
|
|
```
|
|
|
|
### Wrong API URL
|
|
|
|
If commands are hitting the wrong server:
|
|
|
|
```bash
|
|
# Check current profile
|
|
attune config current
|
|
|
|
# Check API URL
|
|
attune config get api_url
|
|
|
|
# Switch if needed
|
|
attune config use correct-profile
|
|
```
|
|
|
|
## Migration from Old Config
|
|
|
|
If you have an old single-server config, it will be migrated to a `default` profile on first run with the new version.
|
|
|
|
Old format:
|
|
```yaml
|
|
api_url: http://localhost:8080
|
|
auth_token: ...
|
|
refresh_token: ...
|
|
output_format: table
|
|
```
|
|
|
|
New format:
|
|
```yaml
|
|
current_profile: default
|
|
profiles:
|
|
default:
|
|
api_url: http://localhost:8080
|
|
auth_token: ...
|
|
refresh_token: ...
|
|
default_output_format: table
|
|
```
|
|
|
|
**Note**: Manual migration may be required. Back up your config before upgrading:
|
|
|
|
```bash
|
|
cp ~/.config/attune/config.yaml ~/.config/attune/config.yaml.backup
|
|
```
|
|
|
|
## Examples
|
|
|
|
### Complete Setup Example
|
|
|
|
```bash
|
|
# Setup local development
|
|
attune config add-profile local \
|
|
--api-url http://localhost:8080 \
|
|
--description "Local development"
|
|
|
|
# Setup staging
|
|
attune config add-profile staging \
|
|
--api-url https://staging.example.com \
|
|
--description "Staging environment"
|
|
|
|
# Setup production
|
|
attune config add-profile production \
|
|
--api-url https://api.example.com \
|
|
--description "Production environment"
|
|
|
|
# Login to each
|
|
for profile in local staging production; do
|
|
attune config use "$profile"
|
|
attune auth login --username admin
|
|
done
|
|
|
|
# Set production to always output JSON
|
|
attune config use production
|
|
attune config set output_format json
|
|
|
|
# Go back to local for development
|
|
attune config use local
|
|
|
|
# List all profiles
|
|
attune config profiles
|
|
```
|
|
|
|
### Profile Comparison Script
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
# Compare pack versions across environments
|
|
|
|
PACK_NAME="monitoring"
|
|
|
|
echo "Pack: $PACK_NAME"
|
|
echo "---"
|
|
|
|
for profile in dev staging production; do
|
|
version=$(attune --profile "$profile" pack show "$PACK_NAME" -j 2>/dev/null | jq -r '.version')
|
|
|
|
if [ -n "$version" ] && [ "$version" != "null" ]; then
|
|
echo "$profile: $version"
|
|
else
|
|
echo "$profile: Not installed"
|
|
fi
|
|
done
|
|
```
|
|
|
|
## Related Commands
|
|
|
|
- `attune config list` - Show all configuration for current profile
|
|
- `attune config get <key>` - Get specific config value
|
|
- `attune config set <key> <value>` - Set config value for current profile
|
|
- `attune config path` - Show config file location
|
|
- `attune auth whoami` - Check authentication status
|
|
|
|
## See Also
|
|
|
|
- [CLI Documentation](cli.md)
|
|
- [Configuration Guide](../README.md#configuration)
|
|
- [Authentication](cli.md#authentication) |