Run a pipeline and keep the result

Build or install contd

When building from source, use Go 1.25.5 or newer.

go build -o contd ./cmd/contd
./contd help

The examples use ./contd. Replace it with contd when it is on PATH.

Write a pipeline

contd looks for .contd.yml, contd.yml, .contd.yaml, or contd.yaml.

jobs:
  fetch:
    image: alpine:3.20
    repo: https://github.com/octocat/Hello-World.git
    working_dir: /contd/Hello-World
    script:
      - test -s README.md
      - mkdir -p /out
      - |
        {
          echo "# Source report"
          echo
          echo "Repository: octocat/Hello-World"
          echo "README bytes: $(wc -c < README.md)"
        } > /out/report.md
    artifacts:
      - path: /out/report.md
        visibility: internal

  verify:
    image: alpine:3.20
    needs:
      - job: fetch
        artifacts: true
    script:
      - test -s /out/report.md
      - grep -q "Repository: octocat/Hello-World" /out/report.md
      - cp /out/report.md /out/final-report.md
    artifacts:
      - path: /out/final-report.md
        visibility: exported

The first job uses a shallow Git checkout. The second job receives the first job's declared artifact at /out/report.md.

Validate before running

./contd validate

Validation parses YAML, resolves stages, checks job fields, rejects unknown dependencies, and rejects dependency cycles. It does not contact Docker or the AI provider.

Run with the daemon

./contd daemon start
./contd run --follow --logs

Start the daemon once. The daemon-backed run command validates the configuration and queues a request. Without --follow, it prints the IDs and exits while the daemon continues. With --follow, it waits for lifecycle events.

./contd run --foreground --verbose

Foreground mode skips the daemon and keeps execution attached to the client terminal.

Read the result

./contd runs
./contd status <run-id>
./contd logs <run-id>
./contd artifacts <run-id>
./contd inspect <run-id>

Results remain available after containers are removed. Add --json for machine-readable output. Use artifacts --all to include internal artifacts.

./contd artifacts download --output result.tar <run-id> <artifact-id>

Run a selected part

./contd run --job verify --follow
./contd run --from fetch --follow

--job runs the target and its prerequisites. --from runs the target, its downstream dependents, and the prerequisites needed to reach them.