ship

README

Ship CLI

A collection of CloudShip AI team curated MCP servers that run on top of Dagger engine with the ability to use it as a framework to build MCP servers that run securely in containers.

Ship provides both a powerful CLI for infrastructure analysis and a comprehensive SDK for building custom Model Context Protocol (MCP) servers that integrate with AI assistants like Claude, Cursor, and others.

🤖 For LLMs and AI Assistants: Complete installation and usage instructions specifically designed for AI consumption are available in llms.txt. This includes MCP server setup, integration examples, and best practices for AI-driven infrastructure analysis with all 7 MCP tools.

🚀 Features

CLI Tools

• 🔍 Terraform Linting: Catch errors and enforce best practices with TFLint
• 🛡️ Security Scanning: Multi-cloud security analysis with Checkov and Trivy
• 💰 Cost Estimation: Estimate infrastructure costs with Infracost and OpenInfraQuote
• 📝 Documentation Generation: Auto-generate beautiful Terraform module documentation
• 📊 Infrastructure Diagrams: Visualize your infrastructure with InfraMap integration
• 🤖 AI Assistant Integration: Built-in MCP server for Claude Desktop, Cursor, and other AI tools
• 🐳 Containerized Tools: All tools run in containers via Dagger - no local installations needed
• ☁️ Cloud Integration: Seamlessly works with AWS, Azure, GCP, and other cloud providers
• 🔧 CI/CD Ready: Perfect for integration into your existing pipelines

Ship SDK Framework

• 🏗️ MCP Server Builder: Fluent API for building custom MCP servers
• 🔧 Container Tool Framework: Run any tool securely in Docker containers via Dagger
• 📦 Pre-built Ship Tools: Curated collection of infrastructure tools ready to use
• 🎯 Three Usage Patterns: Pure framework, cherry-pick tools, or everything plus custom extensions
• 🔒 Security First: All tools run in isolated containers with no local dependencies
• ⚡ Performance Optimized: Leverages Dagger's caching and parallel execution
• 🧪 Test Coverage: Comprehensive test suite with integration tests
• 📚 Rich Documentation: Complete API reference and usage examples

📊 Privacy & Telemetry

Ship CLI collects anonymous usage telemetry to help us improve the tool. This data is completely anonymous and helps us understand which features are most valuable.

What we collect:

• Command usage patterns (e.g., which MCP tools are used)
• Tool execution frequency
• Anonymous system identifiers (no personal information)

What we DON'T collect:

• File contents or code
• Personal information
• Project names or paths
• Error details or sensitive data

Opt-out anytime:

# Disable telemetry via environment variable
export SHIP_TELEMETRY=false

# Or disable in config
ship vars set telemetry.enabled false

The telemetry system is powered by PostHog and uses industry-standard privacy practices.

📚 Table of Contents

• Installation
• Quick Start
  • CLI Usage
  • Ship SDK Framework
• Demo
• Available Tools
• Command Reference
• Authentication
• Using External Dagger Modules
• Contributing
• License

🎬 Demo

Terraform Tools in Action

This demo shows Ship CLI running terraform-docs, tflint, and security scanning on a Terraform module - all without any local tool installations!

OpenInfraQuote - Advanced Cost Analysis

OpenInfraQuote provides highly accurate AWS cost estimation by analyzing your Terraform plans against real AWS pricing data. It supports 100+ AWS resource types with region-specific pricing!

📦 Installation

Quick Install with curl (Recommended)

# Install Ship CLI and SDK with one command
curl -fsSL https://raw.githubusercontent.com/cloudshipai/ship/main/install.sh | bash

# Verify installation
ship version

Install with Go

# Install directly with Go
go install github.com/cloudshipai/ship/cmd/ship@latest

# Verify installation
ship version

For Ship SDK Development

# Add Ship SDK to your Go project
go mod init my-mcp-server
go get github.com/cloudshipai/ship/pkg/ship
go get github.com/cloudshipai/ship/pkg/tools  # Optional: for Ship tools

From Source

# Clone the repository
git clone https://github.com/cloudshipai/ship.git
cd ship

# Build and install
go build -o ship ./cmd/ship
sudo mv ship /usr/local/bin/

# Or just run directly
go run ./cmd/ship [command]

🏃 Quick Start

1. Basic CLI Usage

# Navigate to your Terraform project
cd your-terraform-project

# Run a comprehensive analysis
ship tf lint                # Check for errors and best practices
ship tf checkov             # Security scanning
ship tf cost                # Estimate AWS/Azure/GCP costs
ship tf docs                # Generate documentation

2. Ship SDK Framework

Build your own MCP servers using the Ship SDK:

Quick Example: Echo Server

# Create a new Go project
mkdir my-mcp-server && cd my-mcp-server
go mod init my-mcp-server
go get github.com/cloudshipai/ship/pkg/ship

Create main.go:

package main

import (
    "context"
    "log"
    "github.com/cloudshipai/ship/pkg/ship"
    "github.com/cloudshipai/ship/pkg/dagger"
)

func main() {
    // Create a simple echo tool
    echoTool := ship.NewContainerTool("echo", ship.ContainerToolConfig{
        Description: "Echo a message",
        Image:       "alpine:latest",
        Parameters: []ship.Parameter{
            {Name: "message", Type: "string", Description: "Message to echo", Required: true},
        },
        Execute: func(ctx context.Context, params map[string]interface{}, engine *dagger.Engine) (*ship.ToolResult, error) {
            message := params["message"].(string)
            result, err := engine.Container().From("alpine:latest").WithExec([]string{"echo", message}).Stdout(ctx)
            if err != nil {
                return &ship.ToolResult{Error: err}, err
            }
            return &ship.ToolResult{Content: result}, nil
        },
    })

    // Build and start the MCP server
    server := ship.NewServer("echo-server", "1.0.0").AddTool(echoTool).Build()
    if err := server.ServeStdio(); err != nil {
        log.Fatalf("Server failed: %v", err)
    }
}

# Build and run your MCP server
go build -o echo-server .
./echo-server

Three Usage Patterns

1. Pure Ship SDK (Custom Tools Only):

server := ship.NewServer("custom-server", "1.0.0").
    AddContainerTool("my-tool", ship.ContainerToolConfig{...}).
    Build()

2. Cherry-Pick Ship Tools:

import "github.com/cloudshipai/ship/pkg/tools"

server := ship.NewServer("hybrid-server", "1.0.0").
    AddTool(tools.NewTFLintTool()).
    AddContainerTool("my-custom-tool", config).
    Build()

3. Everything Plus Custom Extensions:

import "github.com/cloudshipai/ship/pkg/tools/all"

server := all.AddAllTools(
    ship.NewServer("full-server", "1.0.0").
    AddContainerTool("my-extension", config),
).Build()

Integration with AI Assistants

Configure your custom MCP server in Claude Code:

{
  "mcpServers": {
    "my-server": {
      "command": "/path/to/my-mcp-server"
    }
  }
}

📚 Learn More: Check out the Ship SDK Documentation for complete guides, API reference, and examples.

3. Real-World CLI Example

# Clone a sample Terraform project
git clone https://github.com/terraform-aws-modules/terraform-aws-vpc.git
cd terraform-aws-vpc/examples/simple

# Run all tools
ship tf lint
ship tf checkov
ship tf trivy
ship tf cost
ship tf docs > README.md
ship tf diagram . --hcl -o infrastructure.png

4. Generate Infrastructure Diagrams

Visualize your infrastructure with InfraMap integration:

# Generate diagram from Terraform files (no state file needed!)
ship tf diagram . --hcl --format png -o infrastructure.png

# Generate from existing state file
ship tf diagram terraform.tfstate -o current-state.png

# Generate SVG for web documentation
ship tf diagram . --hcl --format svg -o architecture.svg

# Filter by provider (AWS only)
ship tf diagram terraform.tfstate --provider aws -o aws-resources.png

# Show all resources without filtering (raw mode)
ship tf diagram . --hcl --raw -o complete-diagram.png

# Real-world example
cd /path/to/your/terraform/project
ship tf diagram . --hcl -o docs/infrastructure-diagram.png

5. AI Assistant Integration (MCP)

Ship CLI includes a built-in MCP (Model Context Protocol) server that makes all functionality available to AI assistants like Claude Desktop and Cursor:

# Start MCP server for AI assistant integration
ship mcp

# Configure in Claude Desktop (claude_desktop_config.json):
{
  "mcpServers": {
    "ship-cli": {
      "command": "ship",
      "args": ["mcp"],
      "env": {
        "AWS_PROFILE": "your-profile"
      }
    }
  }
}

What AI assistants can do with Ship CLI:

• Terraform Analysis: "Analyze this Terraform code for costs and security"
• Documentation: "Generate docs for this Terraform module"
• Cost Analysis: "Estimate infrastructure costs for this project"
• Security Scanning: "Run security scans on this Terraform configuration"
• Infrastructure Diagrams: "Generate a visual diagram of this infrastructure"

Available MCP Tools:

• lint - Code linting and best practices
• checkov - Security analysis with Checkov
• trivy - Security analysis with Trivy
• cost - Cost estimation with OpenInfraQuote
• docs - Documentation generation
• diagram - Infrastructure diagram generation

Pre-built Workflows:

• security_audit - Comprehensive security audit process
• cost_optimization - Cost optimization analysis workflow

See the MCP Integration Guide for complete setup instructions.

6. CI/CD Integration

# GitHub Actions Example
name: Terraform Analysis
on: [pull_request]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Ship CLI
        run: |
          go install github.com/cloudshipai/ship/cmd/ship@latest
      
      - name: Run Security Scan
        run: ship tf checkov
      
      - name: Estimate Costs
        run: ship tf cost
        env:
          INFRACOST_API_KEY: ${{ secrets.INFRACOST_API_KEY }}

🛠️ Available Tools

Tool	Command	Description	Docker Image
InfraMap	ship tf diagram	Infrastructure diagram generation	cycloid/inframap:latest
TFLint	ship tf lint	Terraform linter for syntax and best practices	ghcr.io/terraform-linters/tflint
Checkov	ship tf checkov	Comprehensive security and compliance scanner	bridgecrew/checkov
Infracost	ship tf infracost	Cloud cost estimation with breakdown	infracost/infracost
Trivy	ship tf trivy	Vulnerability scanner for IaC	aquasec/trivy
terraform-docs	ship tf docs	Auto-generate module documentation	quay.io/terraform-docs/terraform-docs
OpenInfraQuote	ship tf cost	Alternative cost analysis tool	gruebel/openinfraquote

📋 Command Reference

Module Management

# List all available modules (built-in, user, project)
ship modules list

# Show detailed information about a module
ship modules info terraform-tools

# Create a new custom module template
ship modules new my-custom-tool --type docker --description "My custom analysis tool"

# Filter modules by type or source
ship modules list --type docker --source user
ship modules list --trusted  # Show only trusted modules

Infrastructure Diagrams

# Generate diagram from Terraform files
ship tf diagram . --hcl --format png

# Generate from state file
ship tf diagram terraform.tfstate --format svg

# Filter by provider
ship tf diagram . --hcl --provider aws --format png

Linting

# Basic linting
ship tf lint

# Lint specific directory
ship tf lint ./modules/vpc

# Lint with custom config
ship tf lint --config .tflint.hcl

Security Scanning

# Checkov scan (recommended)
ship tf checkov

# Trivy scan (alternative)
ship tf trivy

# Scan specific frameworks
ship tf checkov --framework terraform,arm

Cost Estimation

Using Infracost

# Estimate costs for current directory
ship tf infracost

# Estimate with specific cloud provider
ship tf infracost --cloud aws

# Compare costs between branches
ship tf infracost --compare-to main

Using OpenInfraQuote (More Accurate)

# Analyze costs with OpenInfraQuote
ship tf cost

# Analyze specific plan file
ship tf cost terraform.tfplan.json

# Use specific AWS region for pricing
ship tf cost --region us-west-2

OpenInfraQuote Features:

• 🎯 Accurate Pricing: Uses real-time AWS pricing API data
• 📊 Detailed Breakdown: Shows costs per resource with hourly/monthly rates
• 🌍 Region-Specific: Accounts for regional price variations
• 📈 100+ Resources: Supports EC2, RDS, S3, ELB, Lambda, and more
• 🔄 JSON Output: Machine-readable format for automation

Documentation

# Generate markdown documentation
ship tf docs

# Generate with specific filename
ship tf docs --filename API.md

# Save to specific output file
ship tf docs --output documentation.md

Infrastructure Diagram Generation

# Generate PNG diagram from Terraform HCL files
ship tf diagram . --hcl --format png -o infrastructure.png

# Generate SVG diagram from state file
ship tf diagram terraform.tfstate --format svg -o current-state.svg

# Generate DOT format for programmatic processing
ship tf diagram . --hcl --format dot -o infrastructure.dot

# Filter by specific cloud provider
ship tf diagram . --hcl --provider aws --format png

# Generate PDF for documentation
ship tf diagram . --hcl --format pdf -o docs/infrastructure.pdf

🔐 Authentication

AWS

# Ship CLI automatically uses your AWS credentials from:
# 1. Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
# 2. AWS credentials file (~/.aws/credentials)
# 3. IAM role (when running on EC2/ECS/Lambda)

Azure

# Set Azure credentials
export ARM_CLIENT_ID="your-client-id"
export ARM_CLIENT_SECRET="your-client-secret"
export ARM_SUBSCRIPTION_ID="your-subscription-id"
export ARM_TENANT_ID="your-tenant-id"

GCP

# Set GCP credentials
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"

Infracost

# Get free API key
infracost auth login

# Or set directly
export INFRACOST_API_KEY="your-api-key"

🏗️ Architecture

Ship CLI uses Dagger to run all tools in containers, providing:

• Consistency: Same tool versions across all environments
• Isolation: No conflicts with local installations
• Security: Tools run in sandboxed containers
• Simplicity: No need to install or manage tool versions

🤝 Contributing

We welcome contributions! See our Contributing Guide for details.

Adding New Tools

1. Create a new module in internal/dagger/modules/
2. Add CLI command in internal/cli/
3. Update documentation
4. Submit a pull request

📚 Documentation

CLI Documentation

• CLI Reference - Complete command reference
• MCP Integration Guide - AI assistant integration setup
• Dynamic Module Discovery - Extensible module system
• Dagger Modules - How to add new tools
• Development Guide - For contributors
• Technical Spec - Architecture and design

Ship SDK Documentation

• 📖 Ship SDK Overview - Framework introduction and concepts
• 🚀 Quick Start Guide - Step-by-step getting started
• 📋 API Reference - Complete API documentation
• 🎯 Usage Patterns - Advanced patterns and best practices
• 🛠️ Ship Tools Reference - Pre-built tools documentation
• ❓ FAQ - Frequently asked questions

🧪 Testing

# Run all tests
go test ./...

# Run integration tests
go test -v ./internal/dagger/modules/

# Test specific module
go test -v -run TestTFLintModule ./internal/dagger/modules/

🧩 Using External Dagger Modules

Ship CLI is designed to be extensible! You can use any Dagger module without modifying Ship CLI itself.

Using Published Dagger Modules

# Use any Dagger module directly
ship run dagger call --mod github.com/username/my-module@v1.0.0 analyze --source .

# Example: Using a custom security scanner
ship run dagger call --mod github.com/security/scanner@latest scan \
  --directory . \
  --severity high

# Example: Custom cost analyzer
ship run dagger call --mod github.com/finops/analyzer@v2.1.0 estimate \
  --terraform-dir . \
  --currency USD

Creating Your Own Dagger Module

1. Initialize a new Dagger module:

dagger init --sdk=go my-custom-tool
cd my-custom-tool

1. Define your tool's functionality:

// main.go
package main

import (
    "context"
    "dagger.io/dagger"
)

type MyCustomTool struct{}

// Analyze runs custom analysis on source code
func (m *MyCustomTool) Analyze(
    ctx context.Context,
    // Directory containing code to analyze
    source *dagger.Directory,
    // +optional
    // Output format (json, text, markdown)
    format string,
) (string, error) {
    return dag.Container().
        From("alpine:latest").
        WithMountedDirectory("/src", source).
        WithWorkdir("/src").
        WithExec([]string{"your-analysis-command", "--format", format}).
        Stdout(ctx)
}

1. Publish your module:

# Push to GitHub
git init
git add .
git commit -m "Initial module"
git remote add origin https://github.com/yourusername/my-custom-tool
git push -u origin main
git tag v1.0.0
git push --tags

1. Use your module with Ship CLI:

# Now anyone can use your module!
ship run dagger call --mod github.com/yourusername/my-custom-tool@v1.0.0 \
  analyze --source . --format json

Module Ideas We'd Love to See

• Cloud Security Scanner: Deep security analysis for AWS/Azure/GCP
• Kubernetes Analyzer: K8s manifest validation and cluster analysis
• Database Tools: Schema validation, migration checks, documentation
• Performance Profiler: Infrastructure performance analysis
• Compliance Checkers: SOC2, HIPAA, PCI-DSS validators
• Custom Cost Analyzers: Organization-specific cost allocation

🤝 Community

• Share Your Modules: Tag them with #ship-cli on GitHub
• Get Help: Open an issue
• Contribute: See our Contributing Guide

📈 Roadmap

• Dynamic module discovery and installation (ship modules install)
• Support for Atlantis integration
• Policy as Code with Open Policy Agent
• Custom tool configurations
• Web UI for results visualization
• Integration with more cloud providers

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Ship CLI wouldn't be possible without these amazing open source projects:

• Dagger - For containerized execution
• Cobra - For CLI framework
• All the individual tool maintainers

---

Built with ❤️ by the CloudshipAI team