Pilum

A cloud-agnostic build and deployment CLI. Define your service once, deploy to any cloud provider.

pilum deploy --tag=v1.0.0

Pilum handles the build → push → deploy pipeline while your infrastructure-as-code (Terraform, Pulumi) defines the actual resources.

Pilum is dogfooded as the deployment tool for every SID Technologies product — dozens of services shipped to Cloud Run, Cloud Run Jobs, Cloudflare Pages, npm, and Homebrew with it, daily, since December 2025.

Provider status, honestly:

• Battle-tested daily: GCP Cloud Run, GCP Cloud Run Jobs, Cloudflare Pages, npm, Homebrew
• Implemented and command-level reviewed, less exercised: AWS Lambda, Azure Container Apps — feedback from real-world use wanted

Not sure Pilum fits your stack? Read When to Use Pilum (and When Not To) — it includes the cases where the answer is no.

Installation

Homebrew

brew tap sid-technologies/pilum
brew install pilum

From source

go install github.com/sid-technologies/pilum@latest

Features

• Recipe-driven deployments - Define reusable deployment workflows in YAML
• Recipe-driven validation - Each recipe declares required fields, no Go code per provider
• Multi-cloud support - GCP Cloud Run, AWS Lambda, Azure Container Apps, Homebrew, and more
• Parallel execution - Deploy multiple services concurrently with step barriers
• Dependency ordering - Wave-based deployment respects depends_on across services
• Deployment locks - Prevent concurrent deploys with automatic stale lock cleanup
• GitHub commit status - Post pending/success/failure status to commits from CI
• Step filtering - Run only build steps, only deploy steps, or custom tag combinations
• Environment overrides - Per-environment config (staging, prod) via environments block
• Git-aware filtering - Deploy only services with changes since base branch
• Dry-run mode - Preview commands before executing
• JSON output - Machine-readable output for scripting and AI agents
• Editor support - JSON Schema for autocompletion and validation in VS Code, JetBrains, etc.
• Beautiful CLI - Animated spinners, colored output, clear progress

Quick Start

1. Initialize a service (optional)

Use the interactive init command to generate a pilum.yaml:

pilum init

This walks you through:

1. Selecting a provider (GCP, AWS, Homebrew, etc.)
2. Selecting a service type (Cloud Run, Lambda, etc.)
3. Filling in required and optional fields
4. Choosing a build language (Go, Python, Rust, Node)

2. Or create a service configuration manually

Create a pilum.yaml in your project:

# yaml-language-server: $schema=https://raw.githubusercontent.com/SID-Technologies/pilum/main/schemas/pilum.yaml.schema.json
name: my-api
provider: gcp
project: my-gcp-project
region: us-central1
registry_name: gcr.io/my-gcp-project

build:
  language: go
  version: "1.23"

3. Validate your configuration

pilum check

This validates your pilum.yaml against the recipe's required fields and the JSON Schema:

• Errors (check fails): an unknown key inside a block, such as cloud_run.cpu_throtling (with a "did you mean" suggestion), or a value of the wrong type that Pilum would ignore, such as min_instances: "2". environments blocks are checked too.
• Warnings: an unknown top-level key (custom recipes may read their own; keys a service's recipe names aren't reported), or a number where a string is expected, which Pilum reads as text (version: 1.20 reads as 1.2; quote it).

Other commands print the same problems as warnings and carry on.

4. Deploy

# Deploy all services
pilum deploy --tag=v1.0.0

# Deploy specific service
pilum deploy my-api --tag=v1.0.0

# Preview without executing
pilum deploy --dry-run --tag=v1.0.0

# Build and push only (no deploy)
pilum publish --tag=v1.0.0

Recipes

Pilum uses a cooking metaphor: recipes define deployment workflows, ingredients generate cloud-specific commands.

Each recipe defines:

• Steps - Ordered commands to execute (build, push, deploy)
• Required fields - What your pilum.yaml must contain
• Optional fields - Additional configuration options with defaults

Built-in Recipes

Recipe	Provider	Description
gcp-cloud-run	gcp	Deploy to Google Cloud Run
gcp-cloud-run-job	gcp	Deploy batch jobs to Google Cloud Run Jobs
gcp-mig-container	gcp	Roll a new container image onto an existing managed instance group (COS + startup script)
aws-lambda	aws	Deploy to AWS Lambda
azure-container-apps	azure	Deploy to Azure Container Apps
cloudflare-pages	cloudflare	Deploy to Cloudflare Pages
homebrew	homebrew	Publish Homebrew formula
npm	npm	Publish npm packages

Use pilum recipes to list all recipes, or pilum recipes <name> to see required fields, optional fields, and deployment steps for a specific recipe.

Custom Recipes

Create your own recipes in recipes/:

以上為 README 的開頭部分。其餘內容請閱讀原文。 檢視完整 README ↗