npm package: @micoverde/harbormaster
Description: Command-line interface for Harbormaster Feature Flag Management
Author: Warren
Latest version: 2.1.0

# Harbormaster CLI

> Command-line interface for Control Tower Feature Flag Management

[![npm version](https://img.shields.io/npm/v/@harbormaster/cli.svg)](https://www.npmjs.com/package/@harbormaster/cli)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

## Overview

Harbormaster CLI is a powerful command-line tool for managing feature flags in your Control Tower deployment. It enables developers to perform all feature flag operations directly from the terminal, making it perfect for automation, CI/CD pipelines, and developer workflows.

## Features

- 🚀 **Full Feature Flag Management** - Create, read, update, delete, enable, and disable flags
- 🔧 **Configuration Management** - Flexible configuration with multiple override layers
- 🎨 **Multiple Output Formats** - Table, JSON, and YAML output formats
- 🔐 **Secure Authentication** - API key-based authentication
- ⚡ **Fast & Reliable** - Built with TypeScript, retry logic, and caching
- 🔄 **CI/CD Ready** - Non-interactive mode with proper exit codes
- 📊 **Verbose Logging** - Debug mode for troubleshooting

## Installation

### Global Installation (Recommended)

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

### Local Installation

```bash
npm install --save-dev @harbormaster/cli
```

### Using npx (No Installation)

```bash
npx @harbormaster/cli <command>
```

## Quick Start

### 1. Initialize Configuration

```bash
hm config init
```

This creates a configuration file at `~/.config/harbormaster/config.json` with default settings.

### 2. Authenticate

```bash
hm auth login
# or
hm auth login --api-key YOUR_API_KEY
```

### 3. List Feature Flags

```bash
hm flags list
```

### 4. Create a Feature Flag

```bash
hm flags create darkMode --name "Dark Mode" --type boolean --default-value false
```

### 5. Enable a Flag

```bash
hm flags enable darkMode --environment production
```

## Configuration

### Configuration Hierarchy

The CLI uses a hierarchical configuration system (highest to lowest priority):

1. **Command-line flags** (highest priority)
2. **Environment variables**
3. **Project configuration** (`.harbormaster.json`)
4. **User configuration** (`~/.config/harbormaster/config.json`)
5. **Default values** (lowest priority)

### Environment Variables

```bash
export HARBORMASTER_API_KEY="your-api-key"
export HARBORMASTER_API_ENDPOINT="http://localhost:3000"
export HARBORMASTER_PROJECT="my-project"
export HARBORMASTER_ENVIRONMENT="production"
export HARBORMASTER_OUTPUT_FORMAT="json"
export HARBORMASTER_DEBUG="1"
```

### Project Configuration

Create a `.harbormaster.json` in your project root:

```json
{
  "apiEndpoint": "http://localhost:3000",
  "defaultProject": "my-app",
  "defaultEnvironment": "development",
  "output": {
    "format": "table",
    "colors": true,
    "verbose": false
  }
}
```

## Commands

### Flags Management

#### List Flags

```bash
# List all flags
hm flags list

# List flags for specific environment
hm flags list --environment production

# Show status across all environments
hm flags list --all-envs

# Output as JSON
hm flags list --format json
```

#### Get Flag Details

```bash
hm flags get darkMode
hm flags get darkMode --format json
```

#### Create Flag

```bash
# Boolean flag
hm flags create darkMode --type boolean --default-value false

# String flag with description
hm flags create apiVersion \
  --name "API Version" \
  --type string \
  --default-value "v1" \
  --description "Current API version"

# Number flag
hm flags create maxUsers --type number --default-value 100

# JSON flag
hm flags create config --type json --default-value '{"theme":"light"}'
```

#### Update Flag

```bash
hm flags update darkMode --name "Dark Mode Theme"
hm flags update darkMode --description "Enable dark mode UI"
hm flags update darkMode --default-value true
```

#### Delete Flag

```bash
# With confirmation prompt
hm flags delete darkMode

# Skip confirmation
hm flags delete darkMode --yes
```

#### Enable/Disable Flags

```bash
# Enable in default environment
hm flags enable darkMode

# Enable in specific environment
hm flags enable darkMode --environment production

# Disable flag
hm flags disable darkMode --environment staging
```

### Configuration Management

```bash
# Initialize configuration
hm config init

# Set configuration value
hm config set apiEndpoint http://api.example.com
hm config set defaultProject my-app
hm config set output.format json

# Get configuration value
hm config get apiEndpoint
hm config get output.format

# List all configuration
hm config list
```

### Authentication

```bash
# Login with interactive prompt
hm auth login

# Login with API key
hm auth login --api-key YOUR_API_KEY

# Check auth status
hm auth status

# Logout
hm auth logout
```

## Global Options

All commands support these global options:

```bash
-c, --config <path>          # Path to configuration file
-e, --api-endpoint <url>     # API endpoint URL
-k, --api-key <key>          # API key for authentication
-p, --project <id>           # Project ID or key
-E, --environment <name>     # Environment name
-f, --format <type>          # Output format (table|json|yaml)
-v, --verbose                # Verbose output
--no-cache                   # Disable caching
--non-interactive            # Non-interactive mode for CI/CD
```

### Examples

```bash
# Use custom API endpoint
hm flags list --api-endpoint http://staging.example.com

# Use specific project
hm flags list --project my-other-app

# JSON output with verbose logging
hm flags get darkMode --format json --verbose

# Non-interactive mode (for CI/CD)
hm flags enable newFeature --environment production --non-interactive --yes
```

## CI/CD Integration

### Exit Codes

- `0` - Success
- `1` - General error
- `2` - Authentication error
- `3` - Not found
- `4` - Validation error
- `5` - Network error

### GitHub Actions Example

```yaml
name: Deploy Feature Flags

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Setup Node.js
        uses: actions/setup-node@v2
        with:
          node-version: '18'

      - name: Install Harbormaster CLI
        run: npm install -g @harbormaster/cli

      - name: Enable feature flag
        run: |
          hm auth login --api-key ${{ secrets.HARBORMASTER_API_KEY }}
          hm flags enable newFeature --environment production --non-interactive
```

### GitLab CI Example

```yaml
deploy-flags:
  stage: deploy
  script:
    - npm install -g @harbormaster/cli
    - hm auth login --api-key $HARBORMASTER_API_KEY
    - hm flags enable newFeature --environment production --non-interactive
  only:
    - main
```

## Output Formats

### Table Format (Default)

```
┌──────────────┬──────────┬─────────────┬────────────┐
│ Flag Key     │ Type     │ Development │ Production │
├──────────────┼──────────┼─────────────┼────────────┤
│ darkMode     │ boolean  │ ✓ enabled   │ ✗ disabled │
│ newFeature   │ boolean  │ ✓ enabled   │ ✗ disabled │
└──────────────┴──────────┴─────────────┴────────────┘
```

### JSON Format

```json
[
  {
    "id": "1",
    "key": "darkMode",
    "name": "Dark Mode",
    "type": "boolean",
    "defaultValue": false,
    "environments": {
      "development": { "enabled": true },
      "production": { "enabled": false }
    }
  }
]
```

### YAML Format

```yaml
- id: '1'
  key: darkMode
  name: Dark Mode
  type: boolean
  defaultValue: false
  environments:
    development:
      enabled: true
    production:
      enabled: false
```

## Development

### Setup

```bash
# Clone repository
git clone https://github.com/micoverde/feature-flag-harbormaster.git
cd feature-flag-harbormaster/packages/cli

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Watch mode for development
npm run watch
```

### Testing

```bash
# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Watch mode
npm run test:watch
```

## Troubleshooting

### Enable Debug Mode

```bash
export HARBORMASTER_DEBUG=1
hm flags list --verbose
```

### Common Issues

**Authentication Failed**
- Verify your API key is correct
- Check that the API endpoint is accessible
- Ensure your API key has the necessary permissions

**Connection Timeout**
- Increase timeout: `hm config set network.timeout 60000`
- Check network connectivity to API endpoint
- Verify API endpoint URL is correct

**Config Not Found**
- Run `hm config init` to create configuration
- Check config file location: `hm config list`

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.

## License

MIT License - see [LICENSE](../../LICENSE) for details.

## Links

- [GitHub Repository](https://github.com/micoverde/feature-flag-harbormaster)
- [Control Tower Documentation](../../README.md)
- [Report Issues](https://github.com/micoverde/feature-flag-harbormaster/issues)