npm package: @gitboiler/gitboiler-cli
Description: CLI to manage GitLab environment variables
Author: GitBoiler Team
Latest version: 0.0.1

# GitBoiler 🚀

CLI to manage GitLab environment variables in an intuitive and efficient way.

## Features

- 🔧 Complete GitLab environment variables management
- 📁 Synchronization with local `.env` files
- 🎯 Support for multiple environments (develop, production, etc.)
- 📊 Diff visualization before applying changes
- 🔒 Support for protected and masked variables
- ⚡ Intuitive command-line interface
- 🚀 Powered by GitBeaker for robust GitLab API integration

## Installation

```bash
# Install dependencies and make globally executable
pnpm run setup

# Or manually:
pnpm install
pnpm link --global
```

## Initial Setup


### Manual Configuration

Before using GitBoiler, you need to configure it:

```bash
gitboiler init
```

You will be prompted to provide:
- GitLab URL (e.g., https://gitlab.com)
- GitLab access token
- Project ID

### How to get GitLab Access Token

1. Go to your GitLab instance
2. Navigate to Settings > Access Tokens
3. Create a new token with `api` scope
4. Copy the generated token

### How to get Project ID

1. Go to your project in GitLab
2. The ID appears right below the project name on the main page

## Usage

### List Variables

```bash
# List all variables
gitboiler list

# List variables from specific environment
gitboiler list -e production
```

### Set Variable

```bash
# Set variable in develop environment (default)
gitboiler set DATABASE_URL "postgresql://localhost:5432/mydb"

# Set variable in specific environment
gitboiler set API_KEY "secret123" -e production

# Set protected and masked variable
gitboiler set SECRET_TOKEN "ultra-secret" -e production --protected --masked
```

### Delete Variable

```bash
# Delete variable from develop environment
gitboiler delete OLD_CONFIG

# Delete variable from specific environment
gitboiler delete TEMP_KEY -e staging
```

### Push Local Variables to GitLab

```bash
# Push .env.develop file to GitLab
gitboiler push -e develop

# Push specific file
gitboiler push -e production -f .env.prod

# Preview changes without applying (dry-run)
gitboiler push -e develop --dry-run

# Push with protection flags for new variables
gitboiler push -e production --protected --masked
```

### Pull GitLab Variables to Local

```bash
# Pull GitLab variables to .env.develop
gitboiler pull -e develop

# Pull to specific file
gitboiler pull -e production -f .env.prod

# Preview what would be pulled (dry-run)
gitboiler pull -e develop --dry-run

# Merge with existing local variables (preserve local)
gitboiler pull -e develop --merge
```

### Sync with .env File

```bash
# Sync .env.develop file with GitLab (bidirectional - removes GitLab-only vars)
gitboiler sync -e develop

# Sync with merge mode (preserves GitLab-only variables)
gitboiler sync -e develop --merge

# Sync specific file
gitboiler sync -e production -f .env.prod

# Preview changes without applying (dry-run)
gitboiler sync -e develop --dry-run
```

### Compare Differences

```bash
# Show differences between local and GitLab
gitboiler diff -e develop

# Compare specific file
gitboiler diff -e production -f .env.prod
```

## .env File Structure

GitBoiler follows standard `.env` file conventions:

```bash
# .env.develop
DATABASE_URL=postgresql://localhost:5432/dev_db
API_KEY=dev_api_key
DEBUG=true

# .env.production  
DATABASE_URL=postgresql://prod-server:5432/prod_db
API_KEY=prod_api_key
DEBUG=false
```

## Commands Comparison

### Push vs Pull vs Sync vs Diff

- **`push`** - One-way: Local .env → GitLab (only updates GitLab with local changes)
- **`pull`** - One-way: GitLab → Local .env (downloads GitLab variables to local file)
- **`sync`** - Two-way: Local .env ↔ GitLab (synchronizes both, removes extra variables)  
- **`diff`** - Read-only: Shows differences without making changes

**When to use each:**
- Use `push` when you want to deploy local changes to GitLab
- Use `pull` when you want to download GitLab variables to your local environment
- Use `sync` when you want complete synchronization (local and GitLab become identical)
- Use `diff` to preview what would change before running push, pull, or sync

**Pull modes:**
- **Replace mode** (default): Overwrites local file with GitLab variables
- **Merge mode** (`--merge`): Preserves local variables and adds/updates from GitLab

## Environment Scopes

GitBoiler supports all GitLab environment scopes:

### Standard Environments
- `develop`, `staging`, `production` - Specific environments
- Custom environment names (e.g., `qa`, `testing`, `demo`)

### Global Environment (`*`)
The special environment `*` (asterisk) applies to **all branches/environments**:

```bash
# Set a global variable (applies to all environments)
gitboiler set GLOBAL_CONFIG "value" -e "*"

# List global variables
gitboiler list -e "*"

# Pull global variables to .env (without suffix)
gitboiler pull -e "*"
```

**Usage notes:**
- Environment `*` uses `.env` file (no suffix)
- Aliases: `all`, `global` also map to `*`
- Global variables have lower priority than environment-specific ones

## Special Characters

GitLab has limitations with some characters in variable names. GitBoiler automatically converts:

- `/` → `[slash]`
- `*` → `[star]`

Example:
- `PATH/TO/FILE` → `PATH[slash]TO[slash]FILE` in GitLab
- `WILDCARD*PATTERN` → `WILDCARD[star]PATTERN` in GitLab

## Usage Examples

### Typical Workflow

1. **Initialize configuration:**
   ```bash
   gitboiler init
   # Follow the prompts to enter your GitLab URL, token, and project ID
   ```

2. **Create environment file:**
   ```bash
   # Create .env.develop with your variables
   echo "DATABASE_URL=postgres://localhost/myapp_dev" > .env.develop
   echo "API_KEY=your-dev-api-key" >> .env.develop
   ```

3. **Preview differences:**
   ```bash
   gitboiler diff -e develop
   ```

4. **Push to GitLab:**
   ```bash
   gitboiler push -e develop
   ```

5. **Verify in GitLab:**
   ```bash
   gitboiler list -e develop
   ```

### Alternative: Start from GitLab

If you already have variables in GitLab and want to pull them locally:

1. **Initialize configuration:**
   ```bash
   gitboiler init
   # Follow the prompts to enter your GitLab URL, token, and project ID
   ```

2. **Pull variables from GitLab:**
   ```bash
   gitboiler pull -e develop
   ```

3. **Review and update the generated .env file:**
   ```bash
   # Check the .env.develop file and update masked values
   ```

### Managing Multiple Environments

```bash
# Global variables (all environments)
gitboiler push -e "*"

# Development
gitboiler push -e develop -f .env.develop

# Staging
gitboiler push -e staging -f .env.staging  

# Production
gitboiler push -e production -f .env.production
```

### Working with Global Variables

```bash
# Set global variables that apply everywhere
gitboiler set COMPANY_NAME "My Company" -e "*"
gitboiler set SUPPORT_EMAIL "support@company.com" -e "*"

# Pull global variables
gitboiler pull -e "*"    # Creates/updates .env

# List all variables grouped by environment
gitboiler list           # Shows: * (Global/All branches), develop, production, etc.
```

## Available Commands

| Command | Description | Options |
|---------|-------------|--------|
| `init` | Configure GitLab connection | - |
| `list` | List variables | `-e` environment |
| `set <key> <value>` | Set variable | `-e` environment, `--protected`, `--masked` |
| `delete <key>` | Delete variable | `-e` environment |
| `push` | Push local .env to GitLab | `-e` environment, `-f` file, `--dry-run`, `--protected`, `--masked` |
| `pull` | Pull GitLab variables to local .env | `-e` environment, `-f` file, `--dry-run`, `--merge` |
| `sync` | Sync with .env file (bidirectional) | `-e` environment, `-f` file, `--dry-run` |
| `diff` | Show differences | `-e` environment, `-f` file |

## Configuration Files

- `.gitboiler.json` - GitLab connection configuration (don't commit!)
- `.env.*` - Environment variable files per environment

## Development

### Testing

GitBoiler uses Node.js 24.11.1+ native test runner. No external test frameworks required.

```bash
# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage (experimental)
pnpm test:coverage
```

All tests include mocks for GitLab API calls. See [docs/testing.md](docs/testing.md) for detailed testing documentation.

**Test Coverage:**
- ✅ 59 tests across 14 suites
- ✅ 100% coverage of core functionality
- ✅ GitLab API mocked (no real API calls)
- ✅ Edge cases and error handling

### Code Quality

```bash
# Format code
pnpm run format

# Lint code
pnpm run lint

# Check everything
pnpm run check
```

## Security

⚠️ **Important:**

- Add `.gitboiler.json` to your `.gitignore`
- Never commit access tokens
- Use masked variables for sensitive data
- Use protected variables to avoid exposure in logs

## Contributing

Contributions are welcome! Feel free to open issues and pull requests.

## License

ISC