@pipeline-builder/pipeline-manager

📖 View documentation

CLI for Pipeline Builder: install the platform itself with provision, then bootstrap, synth, deploy, and manage CDK pipelines + plugins against it.

Install

npm install -g @pipeline-builder/pipeline-manager

Requires Node.js 24.14.0+.

Quick start

# Authenticate against your Pipeline Builder platform
pipeline-manager login --url https://platform.example.com

# Bootstrap a new project in the current directory
pipeline-manager bootstrap

# Synthesize the CDK app into a CloudFormation template
pipeline-manager synth

# Deploy the pipeline to AWS
pipeline-manager deploy

Install the platform (provision)

provision is the recommended way to stand up the platform itself (not a pipeline) — on Docker Compose, Minikube, EC2, or EKS (Auto Mode). It runs prerequisite checks, assembles the exact bin/setup.sh command (secrets masked, missing inputs reported — never guessed), shows the plan, and deploys it end-to-end, gated by confirmation prompts (--yes for CI; --json prints the plan and runs nothing).

# Deploy local — shows the plan, then confirms (confirm → deploy → /health + /ready → init-platform):
pipeline-manager provision --target docker

# Inspect the plan as JSON, run nothing:
pipeline-manager provision --target docker --json

# Deploy to EKS Auto Mode (add --yes for non-interactive CI):
pipeline-manager provision --target eks \
  --domain pipeline.example.com --hosted-zone-id Z123 --ghcr-token ghp_xxx --email

# Tear it down (AWS targets prompt you to TYPE the cluster/target id to confirm):
pipeline-manager provision --target eks --teardown

# Bootstrap a fresh machine — sparse-clones ONLY the deploy folders this target
# + options need (here: deploy/bin + deploy/local/docker), then deploys + registers:
pipeline-manager provision --target docker --repo --yes \
  --admin-email [email protected] --admin-password 's3cret'

# Add post-install loads (each also adds its folder to the sparse clone):
pipeline-manager provision --target docker --repo --with-all --with-smoke-test

• Deploy (gated) or teardown. provision shows the plan, then deploys — refusing on failed prerequisites or missing inputs, confirming before it runs (--yes auto-accepts for CI), then verifying health and running init-platform. --json prints the plan and runs nothing (the only non-executing mode). --teardown removes a deployment (local/minikube stop the stack; EC2 deletes its CloudFormation stack and EKS runs bin/shutdown.sh (cluster + EFS + ACM + Route 53), both irreversibly and require typing the stack/cluster id to confirm — --force skips it for CI).
• Prerequisites, handled. The checks mirror each target's setup.sh exactly — local: Docker, Docker Compose, yq, openssl; minikube: Docker, minikube, kubectl, openssl (+ yq with --with-plugins); ec2: AWS CLI + working credentials; eks: AWS CLI + credentials, kubectl, openssl, envsubst (+ yq with --with-plugins); eksctl is auto-installed by setup.sh (latest binary) when not already on PATH. Missing single-binary tools (yq, kubectl, minikube) are offered as an on-demand fetch into ~/.pipeline-manager/tools and put on PATH — no brew/apt, no system change. For local/minikube it also creates the target's .env from .env.example, generating the CHANGE_ME secrets. Tools that aren't relocatable binaries (git, Docker/Compose, AWS CLI, openssl) fall back to the normal install instruction, and if you run from outside a checkout it offers to sparse-clone the deploy folders for you.
• Self-healing. On a failed deploy it matches known CloudFormation issues (cause + fix) and can auto-fix + retry a few — e.g. an existing SES identity → re-run with --skip-ses-identity. Gated and bounded by --retries (the scripts are idempotent, so a re-run resumes).
• AI-optional. Set ANTHROPIC_API_KEY (or AI_PROVIDER + its key) to parse a natural-language --prompt and add free-form failure diagnosis; without a key it falls back to the deterministic issue matcher.
• Bootstrap a fresh machine (--repo). Without a checkout, --repo git-clones the platform repo first, then runs from it. The clone is sparse + partial (--filter=blob:none + cone sparse-checkout, git ≥ 2.27 — else a full-clone fallback): it materializes only the deploy folders the selected target + options need. The common base is just deploy/bin; each target adds its own folder (e.g. deploy/local/docker; minikube is self-contained), and each post-install load adds its folder. Re-syncs are additive — a single --workdir can accumulate multiple targets. Override with --repo <url>, --ref <branch|tag>, --workdir <dir>.
• Run in Docker, zero host installs. Don't want git/yq/AWS CLI on your machine? deploy/bin/provision-docker.sh runs provision inside a throwaway node:24-slim container, installing only the tools the chosen target needs: ec2 → git + AWS CLI (mounts ~/.aws read-only); eks → + openssl + envsubst + eksctl + kubectl (mounts ~/.aws + ~/.kube); local → git + yq + openssl, with Docker + Docker Compose used externally from the host via the mounted socket (Docker Desktop already provides them — they're never installed in the image). Host footprint = just Docker. Args pass straight through: deploy/bin/provision-docker.sh --target eks --repo --domain … --yes. (On macOS the container can't drive Docker Desktop's CLI, so run local on the host instead — the wrapper shines for the AWS targets.)
• Post-install steps. After deploy + health, provision registers the admin (non-interactive with --admin-email/--admin-password) and runs the opt-in loads — passed as flags, or offered interactively after the clone when none are given (each picked load is then fetched via an additive sparse re-sync): --with-plugins (adds deploy/plugins + deploy/codebuild), --with-compliance (deploy/compliance), --with-samples (deploy/samples), or --with-all. Plus --with-smoke-test (read-only API check), --with-events (AWS event ingestion — a two-step bundle: store-token writes a platform JWT to Secrets Manager at pipeline-builder's own pattern pipeline-builder/{orgId}/platform, then setup-events deploys the EventBridge → SQS → Lambda that reads it), and repeatable --post-step "<cmd>". Default is register-only; --init skip skips even that. All steps are idempotent, so re-running with more options just layers them on.

The underlying bin/setup.sh / bin/shutdown.sh scripts (and aws cloudformation delete-stack for ec2) remain the source of truth and can always be run directly. Full guide: AWS deployment → AI-assisted install.

Commands

Platform installation

| Command | Purpose | | --- | --- | | provision | Install (or tear down) the platform on local/Minikube/EC2/EKS: prereq checks + assembles the exact bin/setup.sh command, then deploys it (gated by confirmation; --yes for CI, --json to print the plan and run nothing), verifying health + running post-install steps. --repo bootstraps a fresh machine via a sparse clone of only the needed deploy folders; --with-plugins/--with-compliance/--with-samples/--with-all/--with-smoke-test/--with-events/--post-step add post-install steps; --teardown removes it. On failure it diagnoses + auto-fixes/retries known issues. See Install the platform. |

Project lifecycle

| Command | Purpose | | --- | --- | | bootstrap | Scaffold a new pipeline project with cdk.json and starter config | | synth | Run CDK synth to emit the CloudFormation template for the pipeline | | deploy | Deploy the synthesized pipeline stack to AWS (also registers the pipeline with the platform by its pipelineId) | | register | Re-register a deployed pipeline with the platform and drain pending intents queued by prior failed deploys (recovery path; exits non-zero if any registration still fails) | | status | Report the current deployment and execution status |

Resource management

| Command | Purpose | | --- | --- | | create-pipeline | Register a new pipeline definition with the platform | | list-pipelines / get-pipeline | Inspect pipelines registered to your organization | | list-plugins / get-plugin | Browse the plugin catalog and fetch a single plugin spec | | upload-plugin | Publish a custom plugin spec + Dockerfile to the platform | | validate-templates | Parse and validate {{ ... }} templates in a pipeline or plugin spec (local file, registered pipeline by ID, or registered plugin by name:version) | | org-export | Export an organization's data as JSON for GDPR portability (sysadmins can export any org; org admins their own only) |

Auth & infrastructure

| Command | Purpose | | --- | --- | | login | Authenticate against the platform and persist the access token (supports --refresh <token> and --org <orgId> to switch organizations) | | store-token | Generate a long-lived JWT and store it in AWS Secrets Manager (used by the events Lambda and CodePipeline synth steps) | | setup-events | Deploy the EventBridge → SQS → Lambda stack that streams CodePipeline events into the platform's reporting service |

Operator audits (cron-friendly)

These commands report drift and exit non-zero when findings exist. Designed to run on a schedule.

| Command | Purpose | Exit codes | | --- | --- | --- | | audit-stacks | Diff CloudFormation stacks tagged pipeline-builder against the platform's pipeline_registry. Surfaces orphaned stacks (no DB row) and missing stacks (DB row but no live stack). See docs/aws-deployment.md. | 0 clean / 1 findings / 2 AWS error | | audit-tokens | Scan platform tokens stored in AWS Secrets Manager and flag any expiring within --warn-days (default 7). Run before tokens lapse to avoid silent reporting outages. | 0 clean / 1 at-risk / 2 AWS error |

Misc

| Command | Purpose | | --- | --- | | completions | Print a shell completion script for bash, zsh, or fish. Source it from your shell profile, e.g. eval "$(pipeline-manager completions bash)" in ~/.bashrc (completions are derived from the live command list, so they never drift) | | version | Print CLI version info |

Run pipeline-manager <command> --help for the full flag reference on any command.

Environment variables

| Variable | Required | Purpose | | --- | --- | --- | | PLATFORM_TOKEN | Yes (for API ops) | Auth token for the Pipeline Builder platform | | PLATFORM_BASE_URL | Yes (for API ops) | Base URL of your platform deployment | | AWS_REGION | Yes (for deploy) | Target AWS region for synth / deploy / provision teardown | | ANTHROPIC_API_KEY (or other provider key) | No | Enables provision's natural-language --prompt parsing + failure diagnosis (else it falls back to the deterministic issue matcher) | | AI_PROVIDER / AI_MODEL | No | Provider + model for provision (anthropic | openai | google | xai | bedrock) |

Full reference: Environment Variables.

Documentation

• Getting started
• CDK usage
• Plugin catalog (125 plugins)
• API reference
• AWS deployment

License

Apache-2.0. See LICENSE.