npm package: @phishkatlabs/cli
Description: PhishKat CLI - Command-line interface for secrets management with browser-based SSO authentication
Author: PhishKat Labs
Latest version: 0.1.1

# PhishKat CLI

**Enterprise Secrets Management from Your Terminal**

The PhishKat CLI provides secure command-line access to your organization's secrets, service accounts, and encryption keys with browser-based SSO authentication.

## Features

- **Browser-based SSO**: OAuth 2.0 authentication with automatic token refresh
- **Secrets Management**: Create, read, update, and delete secrets with versioning
- **Service Accounts**: Generate API tokens for CI/CD automation
- **BYOK Support**: Bring your own encryption keys or use PhishKat-managed keys
- **Multiple Output Formats**: Table, JSON, and YAML output for scripting
- **Secure Storage**: AES-256-GCM encrypted credential storage

## Installation

### NPM (Recommended)

```bash
npm install -g @phishkatlabs/cli
```

### Yarn

```bash
yarn global add @phishkatlabs/cli
```

### npx (No Installation)

```bash
npx @phishkatlabs/cli sso login
```

### Verify Installation

```bash
phishkat --version
phishkat --help
```

## Quick Start

### 1. Authenticate

```bash
phishkat sso login
```

This will:
1. Display a user code (e.g., `ABCD-1234`)
2. Open your browser to https://auth.phishkatlabs.com/device
3. Prompt you to authorize the device
4. Store encrypted credentials at `~/.phishkat/credentials`

### 2. Manage Secrets

```bash
# Create a secret
phishkat secrets create DATABASE_URL \
  --value "postgresql://user:pass@host:5432/db" \
  --description "Production database" \
  --tags "env:prod,service:api"

# Get secret value
phishkat secrets get DATABASE_URL

# List all secrets
phishkat secrets list

# Update a secret (creates new version)
phishkat secrets update DATABASE_URL --value "new-connection-string"

# Delete a secret
phishkat secrets delete DATABASE_URL
```

### 3. Service Accounts for CI/CD

```bash
# Create service account
phishkat service-accounts create github-actions \
  --description "GitHub Actions CI/CD"

# Create API token
phishkat service-accounts create-token <service-account-id> \
  --name "prod-token" \
  --expires 90d

# Use token in CI/CD
export PHISHKAT_TOKEN="phk_sa_..."
phishkat secrets get DATABASE_URL
```

## Commands

### Authentication

- `phishkat sso login` - Authenticate with browser-based SSO
- `phishkat sso status` - Check authentication status
- `phishkat sso logout` - Clear stored credentials

### Secrets

- `phishkat secrets create <name>` - Create a new secret
- `phishkat secrets get <name>` - Get secret value
- `phishkat secrets list` - List all secrets
- `phishkat secrets update <name>` - Update a secret
- `phishkat secrets delete <name>` - Delete a secret
- `phishkat secrets describe <name>` - Show detailed information
- `phishkat secrets list-versions <name>` - List version history

### Service Accounts

- `phishkat service-accounts create <name>` - Create service account
- `phishkat service-accounts list` - List all service accounts
- `phishkat service-accounts describe <id>` - Show details
- `phishkat service-accounts create-token <id>` - Generate API token
- `phishkat service-accounts revoke-token <id> <token-id>` - Revoke token
- `phishkat service-accounts delete <id>` - Delete service account

### Key Management (BYOK)

- `phishkat kms generate-key <name>` - Generate PhishKat-managed key
- `phishkat kms import-key <name>` - Import customer-managed key
- `phishkat kms list-keys` - List encryption keys
- `phishkat kms describe-key <id>` - Show key details
- `phishkat kms delete-key <id>` - Delete encryption key

## CI/CD Integration

### GitHub Actions

```yaml
name: Deploy
on: push

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Install PhishKat CLI
        run: npm install -g @phishkatlabs/cli

      - name: Get secrets
        env:
          PHISHKAT_TOKEN: ${{ secrets.PHISHKAT_TOKEN }}
        run: |
          export DATABASE_URL=$(phishkat secrets get DATABASE_URL)
          export API_KEY=$(phishkat secrets get API_KEY)
          ./deploy.sh
```

### GitLab CI

```yaml
deploy:
  script:
    - npm install -g @phishkatlabs/cli
    - export DATABASE_URL=$(phishkat secrets get DATABASE_URL)
    - ./deploy.sh
  variables:
    PHISHKAT_TOKEN: $PHISHKAT_TOKEN
```

### CircleCI

```yaml
version: 2.1
jobs:
  deploy:
    docker:
      - image: node:20
    steps:
      - run: npm install -g @phishkatlabs/cli
      - run: |
          export DATABASE_URL=$(phishkat secrets get DATABASE_URL)
          ./deploy.sh
    environment:
      PHISHKAT_TOKEN: $PHISHKAT_TOKEN
```

### Jenkins

```groovy
pipeline {
  agent any
  environment {
    PHISHKAT_TOKEN = credentials('phishkat-token')
  }
  stages {
    stage('Deploy') {
      steps {
        sh 'npm install -g @phishkatlabs/cli'
        sh 'export DATABASE_URL=$(phishkat secrets get DATABASE_URL) && ./deploy.sh'
      }
    }
  }
}
```

## Output Formats

### Table Format (Default)

```bash
phishkat secrets list
```

```
┌─────────────────┬──────────────────────┬─────────────┬─────────────┐
│ Name            │ Description          │ Tags        │ Updated     │
├─────────────────┼──────────────────────┼─────────────┼─────────────┤
│ DATABASE_URL    │ Main database        │ env:prod    │ 2 days ago  │
│ API_KEY         │ External API key     │ env:prod    │ 1 week ago  │
└─────────────────┴──────────────────────┴─────────────┴─────────────┘
```

### JSON Format

```bash
phishkat secrets list --format json
```

### YAML Format

```bash
phishkat secrets get my-secret --format yaml
```

### Text Format (Raw Values)

```bash
phishkat secrets get DATABASE_URL
# Output: postgresql://user:pass@host:5432/db

# Perfect for piping to environment variables
export DATABASE_URL=$(phishkat secrets get DATABASE_URL)
```

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `PHISHKAT_AUTH_URL` | Auth service URL | `https://auth.phishkatlabs.com` |
| `PHISHKAT_SECRETS_URL` | Secrets service URL | `https://secrets.phishkatlabs.com` |
| `PHISHKAT_TOKEN` | Service account token for CI/CD | None |

### Credential Storage

Credentials are encrypted and stored at `~/.phishkat/credentials`:

- **Encryption**: AES-256-GCM authenticated encryption
- **Permissions**: 0600 (read/write owner only)
- **Key Derivation**: Device-specific key from hostname
- **Token Expiry**: Access tokens (1h), Refresh tokens (7d)

## Security Best Practices

1. **Never commit tokens to version control**
2. **Use service accounts for CI/CD** (not user credentials)
3. **Rotate tokens regularly** (recommended: 90 days)
4. **Set appropriate token expiration** based on use case
5. **Revoke unused tokens immediately**
6. **Store service account tokens in CI/CD secrets**
7. **Monitor token usage** via `service-accounts describe`

## Troubleshooting

### Authentication Issues

**Session expired:**
```bash
phishkat sso logout
phishkat sso login
```

**Browser doesn't open:**
- Manually open the verification URL shown in your terminal

**Invalid user code:**
- User codes expire after 10 minutes
- Restart login process: `phishkat sso login`

### Token Issues

**Invalid service account token:**
```bash
# Create new token
phishkat service-accounts create-token <service-account-id> --name "new-token"
```

**Token fails in CI/CD:**
```bash
# Verify environment variable is set correctly
echo $PHISHKAT_TOKEN  # Should start with "phk_sa_"
```

### Connection Issues

**Connection refused:**
```bash
# Verify service URLs
echo $PHISHKAT_AUTH_URL
echo $PHISHKAT_SECRETS_URL
```

### Permission Issues

**Cannot access credentials file:**
```bash
# Fix permissions
chmod 600 ~/.phishkat/credentials

# Or re-authenticate
rm ~/.phishkat/credentials
phishkat sso login
```

### Command Errors

**Command not found:**
```bash
# Verify installation
npm list -g @phishkatlabs/cli

# Re-install if needed
npm install -g @phishkatlabs/cli
```

## Support

- **Documentation**: https://docs.phishkatlabs.com/cli
- **Issues**: https://github.com/phishkatlabs/phishkat-cli/issues
- **Email**: support@phishkatlabs.com

## License

Private - PhishKat Labs

---

**Questions?** Contact: ben@phishkatlabs.com