# Solarboat CLI 🚀
[](https://github.com/devqik/solarboat/actions/workflows/release.yml)
[](https://crates.io/crates/solarboat)
[](https://solarboat.io)
> Built with love for Rust and infrastructure automation by [Youssef Hussein (@devqik)](https://devqik.com)
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.
<img src="./solarboat.png" alt="Solarboat Logo" width="100%">
---
## ✨ 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):**
```bash
cargo install solarboat
# Or install a specific version
cargo install solarboat --version 0.8.9
```
**From Release Binaries:**
```bash
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:**
```bash
git clone https://github.com/devqik/solarboat.git
cd solarboat
cargo build
```
---
## 🛠️ Usage
### Common Commands
```bash
# 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:
```json
{
"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:**
```bash
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](./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):**
```yaml
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):**
```yaml
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:
```yaml
- 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:
```yaml
- name: Local Development Mode
uses: devqik/solarboat@v0.8.9
with:
command: plan
recent-commits: 5 # Check last 5 commits for changes
```
### **Action Inputs:**
| `command` | Command to run (`scan`, `plan`, `apply`) | - | ✅ |
| `github_token` | GitHub token for PR comments | - | ❌ |
| `config` | Path to Solarboat configuration file | auto-detect | ❌ |
| `output-dir` | Directory for plan files | `terraform-plans` | ❌ |
| `apply-dryrun` | Run apply in dry-run mode | `true` | ❌ |
| `ignore-workspaces` | Comma-separated workspaces to ignore | - | ❌ |
| `var-files` | Comma-separated var files to use | - | ❌ |
| `path` | Directory to scan for modules | `.` | ❌ |
| `all` | Process all stateful modules | `false` | ❌ |
| `watch` | Show real-time output | `false` | ❌ |
| `parallel` | Number of parallel processes (max 4) | `1` | ❌ |
| `default-branch` | Default git branch for comparisons | `main` | ❌ |
| `recent-commits` | Recent commits to check (local mode) | `5` | ❌ |
| `base-commit` | Base commit SHA for comparison | auto-detect | ❌ |
| `head-commit` | Head commit SHA for comparison | auto-detect | ❌ |
| `base-branch` | Base branch name for comparison | auto-detect | ❌ |
| `head-branch` | Head branch name for comparison | auto-detect | ❌ |
| `solarboat-version` | Solarboat CLI version to use | `latest` | ❌ |
| `terraform-version` | Terraform version to use | `latest` | ❌ |
| `continue-on-error` | Continue workflow on Solarboat failure | `false` | ❌ |
### **Action Outputs:**
| `result` | Command result (`success` or `failure`) |
| `plans-path` | Path to generated Terraform plans |
| `changed-modules` | Number of changed modules detected |
### **Advanced Examples:**
**Conditional workflows based on outputs:**
```yaml
- 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:**
```yaml
- 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:**
```yaml
- 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:
```yaml
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](LICENSE) file for details.
## Support 💬
- Issues: [GitHub Issues](https://github.com/devqik/solarboat/issues)
- Discussions: [GitHub Discussions](https://github.com/devqik/solarboat/discussions)
- Documentation: [Wiki](https://github.com/devqik/solarboat/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](https://devqik.com) (Creator)
