Solarboat CLI 🚀

Built with love for Rust and infrastructure automation by Youssef Hussein (@devqik)

Solarboat is a modern CLI for Infrastructure as Code (IaC) and GitOps workflows, providing intelligent Terraform operations, automatic dependency detection, and seamless stateful/stateless module handling.

✨ Features

• Intelligent Terraform Operations
  • Detects changed modules automatically
  • Handles stateful/stateless modules smartly
  • Propagates dependencies
  • Runs modules in parallel (with safety limits)
  • Detailed, readable reporting
  • Path-based filtering for targeted runs
• Coming Soon
  • AI agent
  • Automatic state management
  • Custom workflow automation

📦 Installation

With Cargo (Recommended):

cargo install solarboat
# Or install a specific version
cargo install solarboat --version 0.8.9

From Release Binaries:

curl -L https://github.com/devqik/solarboat/releases/latest/download/solarboat-x86_64-unknown-linux-gnu.tar.gz | tar xz
sudo mv solarboat /usr/local/bin/

From Source:

git clone https://github.com/devqik/solarboat.git
cd solarboat
cargo build

🛠️ Usage

Common Commands

# Scan for changed Terraform modules
solarboat scan

# Scan a specific directory
solarboat scan --path ./terraform-modules

# Scan with custom default branch
solarboat scan --default-branch develop

# Plan Terraform changes
solarboat plan

# Plan in parallel
solarboat plan --parallel 4

# Save plans to directory
solarboat plan --output-dir ./terraform-plans

# Ignore workspaces
solarboat plan --ignore-workspaces dev,staging

# Plan all stateful modules
solarboat plan --all

# Apply changes (dry-run by default)
solarboat apply

# Apply for real
solarboat apply --dry-run=false

# Ignore workspaces
solarboat apply --ignore-workspaces prod,staging

# Apply all stateful modules
solarboat apply --all

# Real-time output
solarboat plan --watch

# Combine flags
solarboat plan --all --watch --var-files vars.tfvars

Command Overview

• scan: Analyze repo for changed modules and dependencies. No changes made.
• plan: Generate Terraform plans for changed modules. Supports parallelism, workspace filtering, and output directory.
• apply: Apply changes to infrastructure. Dry-run by default, supports real-time output and workspace filtering.

Default Branch

• Compares changes against main by default. Use --default-branch to override.

Parallel Processing

• Use --parallel N (max 4) to process modules in parallel. Ex: solarboat plan --parallel 3
• In --watch mode, parallelism is forced to 1 for clean output.

Watch Mode

• --watch streams real-time Terraform output. Great for debugging and monitoring.
• Without --watch, operations run silently for CI/CD cleanliness.

Timeout Handling

• Initialization: 5 min
• Planning: 10 min
• Apply: 30 min

⚙️ Configuration

Solarboat supports flexible configuration via JSON files.

Quick Start:

1. Create solarboat.json in your project root:

{
  "global": {
    "ignore_workspaces": ["dev", "test"],
    "var_files": ["global.tfvars"],
    "workspace_var_files": {
      "prod": ["prod.tfvars"]
    }
  },
  "modules": {
    "infrastructure/networking": {
      "ignore_workspaces": ["test"],
      "var_files": ["networking.tfvars"],
      "workspace_var_files": {
        "prod": ["networking-prod.tfvars"]
      }
    }
  }
}

2. Run Solarboat as usual. It auto-loads your config.

Environment-Specific Config:

SOLARBOAT_ENV=prod solarboat plan

Solarboat will look for solarboat.prod.json if set.

Config Precedence:

1. CLI arguments (highest)
2. Module config
3. Global config
4. Defaults (lowest)

More: See CONFIGURATION.md for full docs.

🧑‍💻 GitHub Actions Integration

Solarboat comes with a GitHub Action for CI/CD automation.

GitHub Token Requirements

The GitHub token is optional and only needed for:

• 📝 PR Comments: Automatic plan summaries posted to pull requests
• 📊 Enhanced Integration: Access to GitHub API features

Most common scenarios:

• ✅ Basic Usage: No token required for core functionality (scan, plan, apply)
• ✅ PR Comments: Use ${{ secrets.GITHUB_TOKEN }} (automatically provided by GitHub)
• ⚠️ Custom Permissions: Use custom token only if default permissions aren't sufficient

Basic Workflow (Minimal Setup):

name: Infrastructure CI/CD
on: [push, pull_request]

jobs:
  terraform:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Scan for Changes
        uses: devqik/solarboat@v0.8.9
        with:
          command: scan

      - name: Plan Infrastructure
        if: github.event_name == 'pull_request'
        uses: devqik/solarboat@v0.8.9
        with:
          command: plan
          output-dir: terraform-plans
          # Add token for PR comments
          github_token: ${{ secrets.GITHUB_TOKEN }}

      - name: Apply Changes
        if: github.ref == 'refs/heads/main'
        uses: devqik/solarboat@v0.8.9
        with:
          command: apply
          apply-dryrun: false

Production Workflow (Full Features):

name: Infrastructure Automation
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read
  pull-requests: write # For PR comments

jobs:
  infrastructure:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Plan Infrastructure Changes
        if: github.event_name == 'pull_request'
        uses: devqik/solarboat@v0.8.9
        with:
          command: plan
          config: ./infrastructure/solarboat.json
          terraform-version: "1.8.0"
          solarboat-version: "v0.8.9"
          parallel: 3
          ignore-workspaces: dev,test
          output-dir: terraform-plans
          github_token: ${{ secrets.GITHUB_TOKEN }}

      - name: Apply Infrastructure Changes
        if: github.ref == 'refs/heads/main'
        uses: devqik/solarboat@v0.8.9
        with:
          command: apply
          apply-dryrun: false
          config: ./infrastructure/solarboat.json
          terraform-version: "1.8.0"
          parallel: 2
          continue-on-error: false

Pipeline-Supplied Commits (New Feature)

Solarboat now supports intelligent change detection with pipeline-supplied commit information for more reliable CI/CD workflows.

Automatic Detection (Recommended)

The GitHub Action automatically detects the appropriate commits based on the event:

• Pull Requests: Uses base.sha and head.sha from the PR
• Main Branch Pushes: Uses before and after commit hashes
• Local Mode: Falls back to checking recent commits (configurable)

Manual Commit Specification

For advanced use cases, you can manually specify commit ranges:

- name: Custom Commit Comparison
  uses: devqik/solarboat@v0.8.9
  with:
    command: plan
    base-commit: abc1234
    head-commit: def5678
    base-branch: main
    head-branch: feature/new-module

Local Development Mode

When no commit information is provided, Solarboat runs in local mode:

- name: Local Development Mode
  uses: devqik/solarboat@v0.8.9
  with:
    command: plan
    recent-commits: 5 # Check last 5 commits for changes

Action Inputs:

Action Outputs:

Advanced Examples:

Conditional workflows based on outputs:

- name: Plan Infrastructure
  id: plan
  uses: devqik/solarboat@v0.8.9
  with:
    command: plan
    github_token: ${{ secrets.GITHUB_TOKEN }}

- name: Notify on Changes
  if: steps.plan.outputs.changed-modules != '0'
  run: |
    echo "🚨 ${{ steps.plan.outputs.changed-modules }} modules changed!"
    echo "Plans available at: ${{ steps.plan.outputs.plans-path }}"

Multi-environment with configuration:

- name: Plan Staging
  uses: devqik/solarboat@v0.8.9
  with:
    command: plan
    config: ./configs/solarboat.staging.json
    path: ./environments/staging

- name: Plan Production
  uses: devqik/solarboat@v0.8.9
  with:
    command: plan
    config: ./configs/solarboat.prod.json
    path: ./environments/production
    ignore-workspaces: dev,staging,test

Error handling:

- name: Apply with Error Handling
  uses: devqik/solarboat@v0.8.9
  with:
    command: apply
    apply-dryrun: false
    continue-on-error: true

- name: Handle Failures
  if: failure()
  run: |
    echo "🚨 Infrastructure apply failed!"
    echo "Check logs and retry manually"

Permissions

For PR comments, ensure your workflow has the correct permissions:

permissions:
  contents: read # Read repository contents
  pull-requests: write # Comment on pull requests

Note: ${{ secrets.GITHUB_TOKEN }} is automatically provided by GitHub with repository access. Custom tokens are only needed for cross-repository access or enhanced permissions.

Contributing 🤝

Contributions are welcome! Please feel free to submit a Pull Request.

License 📄

This project is licensed under the BSD-3-Clause License - see the LICENSE file for details.

Support 💬

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Wiki

Acknowledgments 🙏

This project needs your support! If you find Solarboat CLI useful, please consider:

• ⭐ Starring the project on GitHub
• 🛠️ Contributing with code, documentation, or bug reports
• 💡 Suggesting new features or improvements
• 🌟 Sharing it with other developers

Your support will help make this project better and encourage its continued development.

~ Youssef Hussein (@devqik (Creator)