CLI Commands

Pilum provides a comprehensive set of commands for building and deploying services.

Pipeline Commands

pilum deploy

Full deployment pipeline: build, push, and deploy.

pilum deploy --tag=v1.0.0
pilum deploy my-service --tag=v1.0.0
pilum up --tag=v1.0.0  # alias

Runs all steps: build → push → deploy. Acquires a deployment lock to prevent concurrent runs.

pilum build

Build services without pushing or deploying.

pilum build --tag=v1.0.0
pilum build my-service --tag=v1.0.0
pilum b --tag=v1.0.0  # alias
pilum make --tag=v1.0.0  # alias

Runs only build-tagged steps.

pilum publish

Build and push images (no deploy).

pilum publish --tag=v1.0.0
pilum publish my-service --tag=v1.0.0
pilum p --tag=v1.0.0  # alias

Equivalent to pilum build && pilum push.

pilum push

Push images to registry without deploying.

pilum push --tag=v1.0.0
pilum push my-service --tag=v1.0.0
pilum ps --tag=v1.0.0  # alias

Configuration Commands

pilum init

Generate a new pilum.yaml interactively.

pilum init

Walks you through:

Selecting a provider
Selecting a service type
Filling in required fields
Configuring optional fields
Choosing a build language

Supports non-interactive mode for CI/scripting:

pilum init --provider=gcp --service=cloud-run --name=my-api --language=go

Flags:

Flag	Description
`--provider`, `-p`	Pre-select provider
`--service`, `-s`	Pre-select service type
`--name`, `-n`	Service name
`--language`, `-l`	Build language

pilum check

Validate service configurations against recipes.

pilum check
pilum check my-service
pilum validate  # alias

Output:

✓ api-gateway: validated against gcp-cloud-run
✓ worker-service: validated against gcp-cloud-run
✗ payment-api: missing required field 'region'

pilum list

List discovered services.

pilum list
pilum ls  # alias

Output:

Services found:
  api-gateway      gcp     us-central1
  worker-service   gcp     us-central1
  cli-tool         homebrew

pilum recipes

List available recipes or describe a specific one.

pilum recipes           # list all
pilum recipes gcp-cloud-run  # describe specific recipe
pilum providers         # alias

Shows required fields, optional fields, and deployment steps for each recipe.

pilum dry-run

Preview commands without executing.

pilum dry-run --tag=v1.0.0
pilum dry-run my-service --tag=v1.0.0
pilum dr --tag=v1.0.0  # alias

Output:

my-service: build binary
  [go build -ldflags "-s -w" -o ./dist/my-service .]

my-service: build docker image
  [docker build -t us-central1-docker.pkg.dev/project/my-service:v1.0.0 .]

my-service: deploy to cloud run
  [gcloud run deploy my-service --image ... --region us-central1]

Dry-run mode does not acquire deployment locks.

Observability Commands

pilum status

Show status of deployed services.

pilum status
pilum status my-service
pilum st  # alias

pilum logs

Show logs for a deployed service.

pilum logs my-service
pilum logs my-service --follow
pilum log my-service  # alias

pilum history

Show deployment history for the project.

pilum history
pilum history --limit 20
pilum history --service my-api
pilum hist  # alias

Each pipeline run (deploy, build, publish, push) is automatically recorded to .pilum/history.jsonl in your project root. The file uses append-only JSONL format, making it safe to commit — concurrent appends from different team members won’t cause merge conflicts.

Output:

Deployment History

  abc12def  2025-12-07 14:32  deploy  v1.2.3  ✓ 3/3  (4.2s)
  98fe76ba  2025-12-07 12:10  build   latest  ✗ 2/3  (1.8s)

Flags:

Flag	Short	Default	Description
`--limit`	`-n`	`10`	Number of entries to show
`--service`	`-s`		Filter by service name

Supports --json for structured output.

Utility Commands

pilum delete-builds

Clean dist/ directories.

pilum delete-builds
pilum delete-builds my-service
pilum clean  # alias

pilum completion

Generate shell completion scripts.

pilum completion bash
pilum completion zsh
pilum completion fish

Global Flags

Flag	Short	Default	Description
`--verbose`	`-v`	`false`	Stream command output in real-time
`--quiet`	`-q`	`false`	Minimal output (CI-friendly)
`--json`		`false`	Output as JSON for scripting
`--no-gitignore`		`false`	Don’t read `.gitignore` for ignore patterns

Pipeline Flags

These flags are available on all pipeline commands (deploy, build, publish, push).

Flag	Short	Default	Description
`--tag`	`-t`	`latest`	Version tag for deployment
`--dry-run`	`-D`	`false`	Preview without executing
`--debug`	`-d`	`false`	Enable debug output
`--timeout`	`-T`	`60`	Step timeout in seconds
`--retries`	`-r`	`3`	Retry count on failure
`--max-workers`		`0` (auto)	Maximum parallel workers
`--only-tags`			Only run steps with these tags
`--exclude-tags`			Skip steps with these tags
`--env`	`-e`		Environment to apply (merges overrides)
`--provider`			Filter services by provider
`--only-changed`		`false`	Only deploy services with changes since base branch
`--since`			Git ref to compare against (default: main or master)
`--no-deps`		`false`	Disable dependency ordering (flat parallel)
`--force`	`-f`	`false`	Override deployment lock
`--github-status`		`false`	Post commit status to GitHub
`--recipe-path`			Load recipes from a directory instead of embedded recipes

Step Filtering

Run specific step types

# Only build steps
pilum deploy --only-tags=build --tag=v1.0.0

# Only deploy steps (assumes images exist)
pilum deploy --only-tags=deploy --tag=v1.0.0

# Build and push, skip deploy
pilum deploy --exclude-tags=deploy --tag=v1.0.0

Multiple tags

# Steps tagged with build OR test
pilum deploy --only-tags=build,test --tag=v1.0.0

Service Selection

All services

pilum deploy --tag=v1.0.0

Specific services

pilum deploy api-gateway worker-service --tag=v1.0.0

Filter by provider

pilum deploy --provider=gcp --tag=v1.0.0

Only changed services

pilum deploy --only-changed --tag=v1.0.0
pilum deploy --only-changed --since=v1.0.0 --tag=v1.1.0

Deployment Locks

Pilum prevents concurrent deployments using a lock file at .pilum/deploy.lock. If you run pilum deploy while another deploy is in progress, the second invocation will fail with details about who holds the lock.

# Override an existing lock
pilum deploy --tag=v1.0.0 --force

Locks are automatically cleaned up when the holding process has exited (dead PID detection) or the lock is older than 1 hour (stale timeout). Dry-run mode does not acquire locks.

GitHub Commit Status

Post deployment status to GitHub commits from CI:

pilum deploy --tag=v1.0.0 --github-status

This posts pending before the run, then success or failure after, using the pilum/<command> context (e.g., pilum/deploy).

Required environment variables (set automatically in GitHub Actions):

GITHUB_ACTIONS=true
GITHUB_TOKEN — Token with repo:status permission
GITHUB_SHA — Commit SHA to update
GITHUB_REPOSITORY — Repository in owner/repo format

Environment Overrides

Apply per-environment configuration:

pilum deploy --env=prod --tag=v1.0.0

See Service Configuration for how to define environment overrides in pilum.yaml.

Examples

# Initialize a new service
pilum init

# Validate all configurations
pilum check

# Explore available recipes
pilum recipes
pilum recipes gcp-cloud-run

# Preview deployment
pilum dry-run --tag=v1.0.0

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

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

# Deploy with environment overrides
pilum deploy --env=prod --tag=v1.0.0

# Deploy only changed services
pilum deploy --only-changed --tag=v1.0.0

# Deploy only GCP services
pilum deploy --provider=gcp --tag=v1.0.0

# Build only, with extended timeout
pilum build --tag=v1.0.0 --timeout=300

# Build and push, but don't deploy
pilum publish --tag=v1.0.0

# Run only deploy-tagged steps (assumes images exist)
pilum deploy --only-tags=deploy --tag=v1.0.0

# Override an existing deployment lock
pilum deploy --tag=v1.0.0 --force

# Post GitHub commit status from CI
pilum deploy --tag=v1.0.0 --github-status

# Clean up build artifacts
pilum clean

# List services
pilum ls

# Check status of deployed services
pilum status
pilum status my-api

# Stream logs
pilum logs my-api --follow

# View recent deployment history
pilum history

# View last 20 deploys for a specific service
pilum history --limit 20 --service my-api

# JSON output (for scripting / AI agents)
pilum list --json
pilum recipes gcp-cloud-run --json
pilum status --json

Exit Codes

Code	Meaning
`0`	Success
`1`	General error
`2`	Configuration error
`3`	No services found
`4`	Deployment error
`5`	I/O error
`6`	Invalid arguments
`7`	Lock conflict

Next Steps

Quick Start — Deploy your first service
Troubleshooting — Common issues