Harbormaster CLI

Command-line interface for Control Tower Feature Flag Management

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)

npm install -g @harbormaster/cli

Local Installation

npm install --save-dev @harbormaster/cli

Using npx (No Installation)

npx @harbormaster/cli <command>

Quick Start

1. Initialize Configuration

hm config init

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

2. Authenticate

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

3. List Feature Flags

hm flags list

4. Create a Feature Flag

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

5. Enable a Flag

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

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:

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

Commands

Flags Management

List Flags

# 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

hm flags get darkMode
hm flags get darkMode --format json

Create Flag

# 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

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

# With confirmation prompt
hm flags delete darkMode

# Skip confirmation
hm flags delete darkMode --yes

Enable/Disable Flags

# 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

# 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

# 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:

-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

# 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

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

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

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

YAML Format

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

Development

Setup

# 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

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Watch mode
npm run test:watch

Troubleshooting

Enable Debug Mode

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 for guidelines.

License

MIT License - see LICENSE for details.

Links

• GitHub Repository
• Control Tower Documentation
• Report Issues