Installation

Homebrew (Recommended)

On macOS or Linux:

brew tap sid-technologies/pilum
brew install pilum

From Source

Requires Go 1.25 or later (the version in Pilum’s go.mod):

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

Binaries built this way report their version as dev, because the release version is injected at build time.

Verify Installation

pilum --version

Output:

pilum v0.9.0

The number is whatever release you installed.

Requirements

Pilum doesn’t talk to cloud APIs directly. Each recipe shells out to the provider’s own CLI, so install the tools for the targets you use and authenticate them as you normally would.

Target (type)	Tools on PATH
gcp-cloud-run, gcp-cloud-run-job, gcp-artifact-registry-image, gcp-mig-container	docker, gcloud
gcp-cloud-run-from-image	gcloud
azure-container-apps	docker, az
aws-lambda	sam (deploy), aws (pilum status / pilum logs)
cloudflare-pages	node with npm, pnpm or yarn (wrangler runs via npx)
npm	node and your package manager (npm, pnpm, yarn or bun)
homebrew	go, git, tar, shasum

Plus whatever your build.cmd calls (go, cargo, mvn, …).

Note

Recipes that build container images need a running Docker daemon. Before any step runs, Pilum checks that Docker is reachable and fails fast if it isn’t. Dry runs skip this check. With Docker Desktop, Pilum also sizes parallel image builds from the Docker VM’s CPU and memory, not the host’s.

build.docker_cache also needs docker buildx with a builder that can export a registry cache, such as the docker-container driver. Without one, Pilum warns and builds without the cache.

The Homebrew recipe does not need the GitHub CLI: it clones and pushes the tap with git, using the token named in homebrew.token_env.

Upgrading

Upgrade with brew upgrade pilum, or go install github.com/sid-technologies/pilum@latest. Most releases need no changes to pilum.yaml. These do.

To 0.9

• Environment variables need the PILUM_ prefix. Only PILUM_TAG, PILUM_ENV, PILUM_TIMEOUT and so on set flag defaults. Plain TAG, ENV, DEBUG or TIMEOUT are ignored, so a CI job’s own variables no longer change what Pilum does. If you set the tag with TAG=..., switch to PILUM_TAG or pass --tag. See Flag Defaults and Environment Variables.
• type: is required when a provider has several recipes. A service with provider: gcp and no type used to fall back to gcp-artifact-registry-image and never deploy. It now fails pilum check and every pipeline command with provider 'gcp' has several recipes; set type: to one of .... Add type: gcp-cloud-run (or the recipe you meant). A misspelled type is now an error too, and job.type is never read. provider: aws, azure, cloudflare, npm and homebrew still work without type.
• Check pilum dry-run before the first deploy. Some configs that were silently ignored now take effect:
  • cloud_run.cpu_throttling: false now sends --no-cpu-throttling, so CPU is always allocated, which costs more. Remove the key if you didn’t mean it.
  • List-form env_vars and secrets, and numeric values such as PORT: 8080, are now read. Before, they were dropped, and a list-form secrets: made Cloud Run deploys clear the service’s secrets.
  • Azure Container Apps now receives env_vars, and rejects secrets.
  • default_retries in recipes is now honored when you don’t pass --retries.
• Docker images are built for linux/amd64 unless build.platform says otherwise. Images built on an Apple Silicon Mac used to be arm64. Set build.platform: linux/arm64 for ARM targets.
• npm publish no longer writes .npmrc. Earlier releases left the registry token in the package’s .npmrc; delete it by hand if it’s there.

To 0.10

• -T/--timeout overrides recipe step timeouts. Before, a recipe step’s timeout: always won, so -T only reached steps without one. Now an explicit -T (or PILUM_TIMEOUT, or timeout: in .pilum.yml) applies to every step. Without it, nothing changes. If you pass a small -T today, raise it or drop it: -T 30 now cuts 300-second build steps, and the MIG wait for stable step, to 30 seconds. See Timeouts and retries.

Telemetry

The first time you run Pilum in a terminal, it asks once whether to share anonymous build telemetry. Pressing Enter means no, and it never asks in CI. The GitHub Action turns it on by default. See Telemetry for exactly what’s sent and how to change your answer.

Shell Completion

pilum completion generates completion scripts for bash, zsh, fish and PowerShell.

# bash (current session)
source <(pilum completion bash)

# zsh
pilum completion zsh > "${fpath[1]}/_pilum"

# fish
pilum completion fish | source

# PowerShell
pilum completion powershell | Out-String | Invoke-Expression

To load completions in every session, add the line to your shell’s startup file (~/.bashrc, ~/.zshrc, ~/.config/fish/config.fish, or your PowerShell profile).

Next Steps

• Quick Start — Run pilum init and deploy your first service
• Service Configuration — Learn about pilum.yaml
• CLI Reference — All commands and flags