CLI Commands

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

Commands

pilum init

Generate a new pilum.yaml interactively.

pilum init

Walks you through:

1. Selecting a provider
2. Selecting a service type
3. Filling in required fields
4. Configuring optional fields
5. Choosing a build language

Flags:

Flag	Description
--provider, -p	Pre-select provider
--service, -s	Pre-select service type

---

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 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 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 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

---

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 deploy

Full deployment pipeline.

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.

---

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]

---

pilum delete-builds

Clean dist/ directories.

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

---

Global Flags

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
--recipe-path		./recepies	Path to recipe files
--max-workers		0	Parallel workers (0 = auto)
--only-tags			Run only steps with these tags
--exclude-tags			Skip steps with these tags

---

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

Examples

# Initialize a new service
pilum init

# Validate all configurations
pilum check

# 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

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

# Deploy to production (only deploy steps)
pilum deploy --only-tags=deploy --tag=v1.0.0

# Clean up build artifacts
pilum clean

# List services
pilum ls

---

Exit Codes

Code	Meaning
0	Success
1	General error
2	Configuration error
3	Validation error

Next Steps

• Quick Start — Deploy your first service
• Troubleshooting — Common issues