@concourse-sdk/cli

@concourse-sdk/cli

Config-as-code for Concourse topology. Declare projects, topics, and schema versions as version-controlled YAML + JSON Schema, then diff and apply them across environments (dev → test → prod).

Install

npm i -g @concourse-sdk/cli

Auth

Set a Concourse base URL and an admin machine token. Scopes: read for export/diff, plus config:write for apply.

export CONCOURSE_URL=https://bus.prod.example.com
export CONCOURSE_ADMIN_TOKEN=cadm_…

Both are overridable per-invocation with --url and --token.

Commands

concourse export [--out <dir>]        # write live topology to <dir> (default: .)
concourse diff <config.yaml>          # print pending changes; exit 2 if any (CI gate)
concourse apply <config.yaml> [--yes] # converge the bus to the config
concourse codegen [--out <file>]      # emit TS payload types for the live topology

• codegen fetches the live topology (scope read) and writes one .ts file: a namespace per topic-version (payload type = <Topic>V<n>.Payload) plus a TopicPayloads map keyed projectId → topic → version. Commit the generated file and type your handlers against it so a schema change breaks the build (tsc) instead of failing at runtime.

• apply is additive-convergent: it creates projects/topics, appends new schema versions, and patches changed topic/project settings. It never deletes. Resources present on the bus but absent from the file are reported as drift and left untouched.

• Schema versions are immutable: a changed schema for a version that already exists live is a hard error, not an update. New versions go through the server's compatibility gate and may be rejected (the breaking changes are printed).

• diff exit codes (for CI): 0 no changes, 2 changes pending, 1 error. A PR pipeline runs concourse diff and fails the check on exit 2.

• apply without --yes on a non-interactive shell refuses to run (so a forgotten flag fails fast in CI instead of hanging on a prompt).

File layout

config.yaml
schemas/<topic>/v<n>.json

# config.yaml
projects:
  - id: proj_orders # written on export; apply matches by name
    name: Orders
    description: Order lifecycle events
    topics:
      - name: order.created
        compatMode: full
        maxAttempts: 5
        hotWindowMs: 60000
        archiveDays: 30
        versions:
          - version: 1
            schema: ./schemas/order.created/v1.json