# Pact Broker Client

A client for the [Pact Broker](https://docs.pact.io/pact_broker/) and [PactFlow](https://pactflow.io/?utm_source=ossdocs&utm_campaign=pact_broker_client_readme). Publishes and retrieves pacts, pacticipants, pacticipant versions, environments, deployments and releases. Supports publishing provider contracts for PactFlow. The functionality is available via a CLI, or via Ruby Rake tasks. You can also use the [Pact CLI Docker image](https://hub.docker.com/r/pactfoundation/pact-cli).

![Build status](https://github.com/pact-foundation/pact_broker-client/workflows/Test/badge.svg)

[![Gem Version](https://badge.fury.io/rb/pact_broker-client.svg)](http://badge.fury.io/rb/pact_broker-client)

![Trigger update to docs.pact.io](https://github.com/pact-foundation/pact_broker-client/workflows/Trigger%20update%20to%20docs.pact.io/badge.svg)

## Installation

### Docker

The Pact Broker CLI is packaged with the other Ruby command line tools in the [pactfoundation/pact-cli](https://hub.docker.com/r/pactfoundation/pact-cli) Docker image.

```
docker pull pactfoundation/pact-cli:latest
```

### Standalone executable

Download the latest [pact-ruby-standalone][pact-ruby-standalone] package. You do not need Ruby to run the CLI, as the Ruby runtime is packaged with the executable using Travelling Ruby.

### Ruby

Add `gem 'pact_broker-client'` to your Gemfile and run `bundle install`, or install the gem directly by running `gem install pact_broker-client`.

## Connecting to a Pact Broker with a self signed certificate

To connect to a Pact Broker that uses custom SSL cerificates, set the environment variable `$SSL_CERT_FILE` or `$SSL_CERT_DIR` to a path that contains the appropriate certificate. Read more at https://docs.pact.io/pact_broker/advanced_topics/using-tls#for-non-jvm

## Usage - CLI

All commands prefixed with `pact-broker` can be used with the OSS Pact Broker and PactFlow. Commands prefixed with `pactflow` can only be used with PactFlow.

The Pact Broker base URL can be specified either using the environment variable `$PACT_BROKER_BASE_URL` or the `-b` or `--broker-base-url` parameters.

Pact Broker authentication can be performed either using basic auth or a bearer token.

Basic auth parameters can be specified using the `$PACT_BROKER_USERNAME` and `$PACT_BROKER_PASSWORD` environment variables, or the `-u` or `--broker-username` and `-p` or `--broker-password` parameters.

Authentication using a bearer token can be specified using the environment variable `$PACT_BROKER_TOKEN` or the `-k` or `--broker-token` parameters. This bearer token authentication is used by [PactFlow](https://pactflow.io) and is not available in the [OSS Pact Broker](https://docs.pact.io/pact_broker/), which only supports basic auth.

### Handling unknown options

By default, the underlying library used for the Pact Broker CLI (Thor) does not raise an error in every situation where there is an unknown option used.
This can allow invalid commands to be executed that do not perform as expected.

From version 1.73.0, warnings will be printed for unknown options, and if the environment variable `PACT_BROKER_ERROR_ON_UNKNOWN_OPTION=true` is set, an error will be raised when an unknown option is used.

In the next major version, an error will be raised by default.

<!-- start-autogenerated-docs -->

### Pacts

#### publish

```
Usage:
  pact-broker publish PACT_DIRS_OR_FILES ... -b, --broker-base-url=BROKER_BASE_URL

Options:
  -a, [--consumer-app-version=CONSUMER_APP_VERSION]
              # The consumer application version
  -h, [--branch=BRANCH]
              # Repository branch of the consumer version
  -r, [--auto-detect-version-properties], [--no-auto-detect-version-properties]
              # Automatically detect the repository commit, branch and build
                URL from known CI environment variables or git CLI. Supports
                Buildkite, Circle CI, Travis CI, GitHub Actions, Jenkins,
                Hudson, AppVeyor, GitLab, CodeShip, Bitbucket and Azure DevOps.
              # Default: false
  -t, [--tag=TAG]
              # Tag name for consumer version. Can be specified multiple
                times.
  -g, [--tag-with-git-branch], [--no-tag-with-git-branch]
              # Tag consumer version with the name of the current git branch.
                Supports Buildkite, Circle CI, Travis CI, GitHub Actions,
                Jenkins, Hudson, AppVeyor, GitLab, CodeShip, Bitbucket and
                Azure DevOps.
              # Default: false
      [--build-url=BUILD_URL]
              # The build URL that created the pact
      [--merge], [--no-merge]
              # If a pact already exists for this consumer version and
                provider, merge the contents. Useful when running Pact tests
                concurrently on different build nodes.
              # Default: false
  -o, [--output=OUTPUT]
              # json or text
              # Default: text
  -b, --broker-base-url=BROKER_BASE_URL
              # The base URL of the Pact Broker
  -u, [--broker-username=BROKER_USERNAME]
              # Pact Broker basic auth username
  -p, [--broker-password=BROKER_PASSWORD]
              # Pact Broker basic auth password
  -k, [--broker-token=BROKER_TOKEN]
              # Pact Broker bearer token
  -v, [--verbose], [--no-verbose]
              # Verbose output.
              # Default: false
```

Publish pacts to a Pact Broker.

#### list-latest-pact-versions

```
Usage:
  pact-broker list-latest-pact-versions -b, --broker-base-url=BROKER_BASE_URL

Options:
  -b, --broker-base-url=BROKER_BASE_URL
              # The base URL of the Pact Broker
  -u, [--broker-username=BROKER_USERNAME]
              # Pact Broker basic auth username
  -p, [--broker-password=BROKER_PASSWORD]
              # Pact Broker basic auth password
  -k, [--broker-token=BROKER_TOKEN]
              # Pact Broker bearer token
  -v, [--verbose], [--no-verbose]
              # Verbose output.
              # Default: false
  -o, [--output=OUTPUT]
              # json or table
              # Default: table
```

List the latest pact for each integration

### Environments

#### create-environment

```
Usage:
  pact-broker create-environment --name=NAME -b, --broker-base-url=BROKER_BASE_URL

Options:
      --name=NAME
              # The uniquely identifying name of the environment as used in
                deployment code
      [--display-name=DISPLAY_NAME]
              # The display name of the environment
      [--production], [--no-production]
              # Whether or not this environment is a production environment.
                This is currently informational only.
              # Default: false
      [--contact-name=CONTACT_NAME]
              # The name of the team/person responsible for this environment
      [--contact-email-address=CONTACT_EMAIL_ADDRESS]
              # The email address of the team/person responsible for this
                environment
  -o, [--output=OUTPUT]
              # json or text
              # Default: text
  -b, --broker-base-url=BROKER_BASE_URL
              # The base URL of the Pact Broker
  -u, [--broker-username=BROKER_USERNAME]
              # Pact Broker basic auth username
  -p, [--broker-password=BROKER_PASSWORD]
              # Pact Broker basic auth password
  -k, [--broker-token=BROKER_TOKEN]
              # Pact Broker bearer token
  -v, [--verbose], [--no-verbose]
              # Verbose output.
              # Default: false
```

Create an environment resource in the Pact Broker to represent a real world deployment or release environment.

#### update-environment

```
Usage:
  pact-broker update-environment --uuid=UUID -b, --broker-base-url=BROKER_BASE_URL

Options:
      --uuid=UUID
              # The UUID of the environment to update
      [--name=NAME]
              # The uniquely identifying name of the environment as used in
                deployment code
      [--display-name=DISPLAY_NAME]
              # The display name of the environment
      [--production], [--no-production]
              # Whether or not this environment is a production environment.
                This is currently informational only.
              # Default: false
      [--contact-name=CONTACT_NAME]
              # The name of the team/person responsible for this environment
      [--contact-email-address=CONTACT_EMAIL_ADDRESS]
              # The email address of the team/person responsible for this
                environment
  -o, [--output=OUTPUT]
              # json or text
              # Default: text
  -b, --broker-base-url=BROKER_BASE_URL
              # The base URL of the Pact Broker
  -u, [--broker-username=BROKER_USERNAME]
              # Pact Broker basic auth username
  -p, [--broker-password=BROKER_PASSWORD]
              # Pact Broker basic auth password
  -k, [--broker-token=BROKER_TOKEN]
              # Pact Broker bearer token
  -v, [--verbose], [--no-verbose]
              # Verbose output.
              # Default: false
```

Update an environment resource in the Pact Broker.

#### describe-environment

```
Usage:
  pact-broker describe-environment --uuid=UUID -b, --broker-base-url=BROKER_BASE_URL

Options:
      --uuid=UUID
              # The UUID of the environment to describe
  -o, [--output=OUTPUT]
              # json or text
              # Default: text
  -b, --broker-base-url=BROKER_BASE_URL
              # The base URL of the Pact Broker
  -u, [--broker-username=BROKER_USERNAME]
              # Pact Broker basic auth username
  -p, [--broker-password=BROKER_PASSWORD]
              # Pact Broker basic auth password
  -k, [--broker-token=BROKER_TOKEN]
              # Pact Broker bearer token
  -v, [--verbose], [--no-verbose]
              # Verbose output.
              # Default: false
```

Describe an environment

#### delete-environment

```
Usage:
  pact-broker delete-environment --uuid=UUID -b, --broker-base-url=BROKER_BASE_URL

Options:
      --uuid=UUID
              # The UUID of the environment to delete
  -o, [--output=OUTPUT]
              # json or text
              # Default: text
  -b, --broker-base-url=BROKER_BASE_URL
              # The base URL of the Pact Broker
  -u, [--broker-username=BROKER_USERNAME]
              # Pact Broker basic auth username
  -p, [--broker-password=BROKER_PASSWORD]
              # Pact Broker basic auth password
  -k, [--broker-token=BROKER_TOKEN]
              # Pact Broker bearer token
  -v, [--verbose], [--no-verbose]
              # Verbose output.
              # Default: false
```

Delete an environment

#### list-environments

```
Usage:
  pact-broker list-environments -b, --broker-base-url=BROKER_BASE_URL

Options:
  -o, [--output=OUTPUT]
              # json or text
              # Default: text
  -b, --broker-base-url=BROKER_BASE_URL
              # The base URL of the Pact Broker
  -u, [--broker-username=BROKER_USERNAME]
              # Pact Broker basic auth username
  -p, [--broker-password=BROKER_PASSWORD]
              # Pact Broker basic auth password
  -k, [--broker-token=BROKER_TOKEN]
              # Pact Broker bearer token
  -v, [--verbose], [--no-verbose]
              # Verbose output.
              # Default: false
```

List environments

### Deployments

#### record-deployment

```
Usage:
  pact-broker record-deployment --environment=ENVIRONMENT -a, --pacticipant=PACTICIPANT -b, --broker-base-url=BROKER_BASE_URL -e, --version=VERSION

Options:
  -a, --pacticipant=PACTICIPANT
              # The name of the pacticipant that was deployed.
  -e, --version=VERSION
              # The pacticipant version number that was deployed.
      --environment=ENVIRONMENT
              # The name of the environment that the pacticipant version was
                deployed to.
      [--application-instance=APPLICATION_INSTANCE]
              # Optional. The application instance to which the deployment has
                occurred - a logical identifer required to differentiate
                deployments when there are multiple instances of the same
                application in an environment. This field was called 'target'
                in a beta release.
      [--target=TARGET]
              # Renamed to application_instance
  -o, [--output=OUTPUT]
              # json or text
              # Default: text
  -b, --broker-base-url=BROKER_BASE_URL
              # The base URL of the Pact Broker
  -u, [--broker-username=BROKER_USERNAME]
              # Pact Broker basic auth username
  -p, [--broker-password=BROKER_PASSWORD]
              # Pact Broker basic auth password
  -k, [--broker-token=BROKER_TOKEN]
              # Pact Broker bearer token
  -v, [--verbose], [--no-verbose]
              # Verbose output.
              # Default: false
```

Record deployment of a pacticipant version to an environment. See https://docs.pact.io/record-deployment for more information.

#### record-undeployment

```
Usage:
  pact-broker record-undeployment --environment=ENVIRONMENT -a, --pacticipant=PACTICIPANT -b, --broker-base-url=BROKER_BASE_URL

Options:
  -a, --pacticipant=PACTICIPANT
              # The name of the pacticipant that was undeployed.
      --environment=ENVIRONMENT
              # The name of the environment that the pacticipant version was
                undeployed from.
      [--application-instance=APPLICATION_INSTANCE]
              # Optional. The application instance from which the application
                is being undeployed - a logical identifer required to
                differentiate deployments when there are multiple instances of
                the same application in an environment. This field was called
                'target' in a beta release.
      [--target=TARGET]
              # Optional. The target that the application is being undeployed
                from - a logical identifer required to differentiate
                deployments when there are multiple instances of the same
                application in an environment.
  -o, [--output=OUTPUT]
              # json or text
              # Default: text
  -b, --broker-base-url=BROKER_BASE_URL
              # The base URL of the Pact Broker
  -u, [--broker-username=BROKER_USERNAME]
              # Pact Broker basic auth username
  -p, [--broker-password=BROKER_PASSWORD]
              # Pact Broker basic auth password
  -k, [--broker-token=BROKER_TOKEN]
              # Pact Broker bearer token
  -v, [--verbose], [--no-verbose]
              # Verbose output.
              # Default: false
```

Description:
  Note that use of this command is only required if you are permanently removing an application instance from an environment. It is not required if you are
  deploying over a previous version, as record-deployment will automatically mark the previously deployed version as undeployed for you. See
  https://docs.pact.io/record-undeployment for more information.

### Releases

#### record-release

```
Usage:
  pact-broker record-release --environment=ENVIRONMENT -a, --pacticipant=PACTICIPANT -b, --broker-base-url=BROKER_BASE_URL -e, --version=VERSION

Options:
  -a, --pacticipant=PACTICIPANT
              # The name of the pacticipant that was released.
  -e, --version=VERSION
              # The pacticipant version number that was released.
      --environment=ENVIRONMENT
              # The name of the environment that the pacticipant version was
                released to.
  -o, [--output=OUTPUT]
              # json or text
              # Default: text
  -b, --broker-base-url=BROKER_BASE_URL
              # The base URL of the Pact Broker
  -u, [--broker-username=BROKER_USERNAME]
              # Pact Broker basic auth username
  -p, [--broker-password=BROKER_PASSWORD]
              # Pact Broker basic auth password
  -k, [--broker-token=BROKER_TOKEN]
              # Pact Broker bearer token
  -v, [--verbose], [--no-verbose]
              # Verbose output.
              # Default: false
```

Record release of a pacticipant version to an environment. See See https://docs.pact.io/record-release for more information.

#### record-support-ended

```
Usage:
  pact-broker record-support-ended --environment=ENVIRONMENT -a, --pacticipant=PACTICIPANT -b, --broker-base-url=BROKER_BASE_URL -e, --version=VERSION

Options:
  -a, --pacticipant=PACTICIPANT
              # The name of the pacticipant.
  -e, --version=VERSION
              # The pacticipant version number for which support is ended.
      --environment=ENVIRONMENT
              # The name of the environment in which the support is ended.
  -o, [--output=OUTPUT]
              # json or text
              # Default: text
  -b, --broker-base-url=BROKER_BASE_URL
              # The base URL of the Pact Broker
  -u, [--broker-username=BROKER_USERNAME]
              # Pact Broker basic auth username
  -p, [--broker-password=BROKER_PASSWORD]
              # Pact Broker basic auth password
  -k, [--broker-token=BROKER_TOKEN]
              # Pact Broker bearer token
  -v, [--verbose], [--no-verbose]
              # Verbose output.
              # Default: false
```

Record the end of support for a pacticipant version in an environment. See https://docs.pact.io/record-support-ended for more information.

### Matrix

#### can-i-deploy

```
Usage:
  pact-broker can-i-deploy -a, --pacticipant=PACTICIPANT -b, --broker-base-url=BROKER_BASE_URL

Options:
  -a, --pacticipant=PACTICIPANT
              # The pacticipant name. Use once for each pacticipant being
                checked.
  -e, [--version=VERSION]
              # The pacticipant version. Must be entered after the
                --pacticipant that it relates to.
      [--ignore=PACTICIPANT]
              # The pacticipant name to ignore. Use once for each pacticipant
                being ignored. A specific version can be ignored by also
                specifying a --version after the pacticipant name option. The
                environment variable PACT_BROKER_CAN_I_DEPLOY_IGNORE may also
                be used to specify a pacticipant name to ignore, with commas to
                separate multiple pacticipant names if necessary.
  -l, [--latest=[TAG]]
              # Use the latest pacticipant version. Optionally specify a TAG
                to use the latest version with the specified tag.
      [--branch=BRANCH]
              # The branch of the version for which you want to check the
                verification results.
      [--main-branch], [--no-main-branch]
              # Use the latest version of the configured main branch of the
                pacticipant as the version for which you want to check the
                verification results
              # Default: false
      [--to-environment=ENVIRONMENT]
              # The environment into which the pacticipant(s) are to be
                deployed
      [--to=TAG]
              # The tag that represents the branch or environment of the
                integrated applications for which you want to check the
                verification result status.
  -o, [--output=OUTPUT]
              # json or table
              # Default: table
      [--retry-while-unknown=TIMES]
              # The number of times to retry while there is an unknown
                verification result (ie. the provider verification is likely
                still running)
              # Default: 0
      [--retry-interval=SECONDS]
              # The time between retries in seconds. Use in conjuction with
                --retry-while-unknown
              # Default: 10
      [--dry-run], [--no-dry-run]
              # When dry-run is enabled, always exit process with a success
                code. Can also be enabled by setting the environment variable
                PACT_BROKER_CAN_I_DEPLOY_DRY_RUN=true. This mode is useful when
                setting up your CI/CD pipeline for the first time, or in a
                'break glass' situation where you need to knowingly deploy what
                Pact considers a breaking change. For the second scenario, it
                is recommended to use the environment variable and just set it
                for the build required to deploy that particular version, so
                you don't accidentally leave the dry run mode enabled.
              # Default: false
  -b, --broker-base-url=BROKER_BASE_URL
              # The base URL of the Pact Broker
  -u, [--broker-username=BROKER_USERNAME]
              # Pact Broker basic auth username
  -p, [--broker-password=BROKER_PASSWORD]
              # Pact Broker basic auth password
  -k, [--broker-token=BROKER_TOKEN]
              # Pact Broker bearer token
  -v, [--verbose], [--no-verbose]
              # Verbose output.
              # Default: false
```

Description:
  Returns exit code 0 or 1, indicating whether or not the specified application (pacticipant) has a successful verification result with each of the application
  versions that are already deployed to a particular environment. Prints out the relevant pact/verification details, indicating any missing or failed
  verification results.

  The can-i-deploy tool was originally written to support specifying versions and dependencies using tags. This usage has now been superseded by first class
  support for environments, deployments and releases. For documentation on how to use can-i-deploy with tags, please see
  https://docs.pact.io/pact_broker/client_cli/can_i_deploy_usage_with_tags/

  Before `can-i-deploy` can be used, the relevant environment resources must first be created in the Pact Broker using the `create-environment` command. The
  "test" and "production" environments will have been seeded for you. You can check the existing environments by running `pact-broker list-environments`. See
  https://docs.pact.io/pact_broker/client_cli/readme#environments for more information.

  $ pact-broker create-environment --name "uat" --display-name "UAT" --no-production

  After an application is deployed or released, its deployment must be recorded using the `record-deployment` or `record-release` commands. See
  https://docs.pact.io/pact_broker/recording_deployments_and_releases/ for more information.

  $ pact-broker record-deployment --pacticipant Foo --version 173153ae0 --environment uat

  Before an application is deployed or released to an environment, the can-i-deploy command must be run to check that the application version is safe to deploy
  with the versions of each integrated application that are already in that environment.

  $ pact-broker can-i-deploy --pacticipant PACTICIPANT --version VERSION --to-environment ENVIRONMENT

  Example: can I deploy version 173153ae0 of application Foo to the test environment?

  $ pact-broker can-i-deploy --pacticipant Foo --version 173153ae0 --to-environment test

  Can-i-deploy can also be used to check if arbitrary versions have a successful verification. When asking "Can I deploy this application version with the
  latest version from the main branch of another application" it functions as a "can I merge" check.

  $ pact-broker can-i-deploy --pacticipant Foo 173153ae0 \ --pacticipant Bar --latest main

##### Polling

If the verification process takes a long time and there are results missing when the can-i-deploy command runs in your CI/CD pipeline, you can configure the
command to poll and wait for the missing results to arrive. The arguments to specify are `--retry-while-unknown TIMES` and `--retry-interval SECONDS`, set to
appropriate values for your pipeline.

#### can-i-merge

```
Usage:
  pact-broker can-i-merge -a, --pacticipant=PACTICIPANT -b, --broker-base-url=BROKER_BASE_URL

Options:
  -a, --pacticipant=PACTICIPANT
              # The pacticipant name. Use once for each pacticipant being
                checked.
  -e, [--version=VERSION]
              # The pacticipant version. Must be entered after the
                --pacticipant that it relates to.
  -o, [--output=OUTPUT]
              # json or table
              # Default: table
      [--retry-while-unknown=TIMES]
              # The number of times to retry while there is an unknown
                verification result (ie. the provider verification is likely
                still running)
              # Default: 0
      [--retry-interval=SECONDS]
              # The time between retries in seconds. Use in conjuction with
                --retry-while-unknown
              # Default: 10
      [--dry-run], [--no-dry-run]
              # When dry-run is enabled, always exit process with a success
                code. Can also be enabled by setting the environment variable
                PACT_BROKER_CAN_I_MERGE_DRY_RUN=true. This mode is useful when
                setting up your CI/CD pipeline for the first time, or in a
                'break glass' situation where you need to knowingly deploy what
                Pact considers a breaking change. For the second scenario, it
                is recommended to use the environment variable and just set it
                for the build required to deploy that particular version, so
                you don't accidentally leave the dry run mode enabled.
              # Default: false
  -b, --broker-base-url=BROKER_BASE_URL
              # The base URL of the Pact Broker
  -u, [--broker-username=BROKER_USERNAME]
              # Pact Broker basic auth username
  -p, [--broker-password=BROKER_PASSWORD]
              # Pact Broker basic auth password
  -k, [--broker-token=BROKER_TOKEN]
              # Pact Broker bearer token
  -v, [--verbose], [--no-verbose]
              # Verbose output.
              # Default: false
```

Description:
  Checks if the specified pacticipant version is compatible with the configured main branch of each of the pacticipants with which it is integrated.

### Pacticipants

#### create-or-update-pacticipant

```
Usage:
  pact-broker create-or-update-pacticipant --name=NAME -b, --broker-base-url=BROKER_BASE_URL

Options:
      --name=NAME
              # Pacticipant name
      [--display-name=DISPLAY_NAME]
              # Display name
      [--main-branch=MAIN_BRANCH]
              # The main development branch of the pacticipant repository
      [--repository-url=REPOSITORY_URL]
              # The repository URL of the pacticipant
  -o, [--output=OUTPUT]
              # json or text
              # Default: text
  -b, --broker-base-url=BROKER_BASE_URL
              # The base URL of the Pact Broker
  -u, [--broker-username=BROKER_USERNAME]
              # Pact Broker basic auth username
  -p, [--broker-password=BROKER_PASSWORD]
              # Pact Broker basic auth password
  -k, [--broker-token=BROKER_TOKEN]
              # Pact Broker bearer token
  -v, [--verbose], [--no-verbose]
              # Verbose output.
              # Default: false
```

Create or update pacticipant by name

#### describe-pacticipant

```
Usage:
  pact-broker describe-pacticipant --name=NAME -b, --broker-base-url=BROKER_BASE_URL

Options:
      --name=NAME
              # Pacticipant name
  -o, [--output=OUTPUT]
              # json or text
              # Default: text
  -b, --broker-base-url=BROKER_BASE_URL
              # The base URL of the Pact Broker
  -u, [--broker-username=BROKER_USERNAME]
              # Pact Broker basic auth username
  -p, [--broker-password=BROKER_PASSWORD]
              # Pact Broker basic auth password
  -k, [--broker-token=BROKER_TOKEN]
              # Pact Broker bearer token
  -v, [--verbose], [--no-verbose]
              # Verbose output.
              # Default: false
```

Describe a pacticipant

#### list-pacticipants

```
Usage:
  pact-broker list-pacticipants -b, --broker-base-url=BROKER_BASE_URL

Options:
  -o, [--output=OUTPUT]
              # json or text
              # Default: text
  -b, --broker-base-url=BROKER_BASE_URL
              # The base URL of the Pact Broker
  -u, [--broker-username=BROKER_USERNAME]
              # Pact Broker basic auth username
  -p, [--broker-password=BROKER_PASSWORD]
              # Pact Broker basic auth password
  -k, [--broker-token=BROKER_TOKEN]
              # Pact Broker bearer token
  -v, [--verbose], [--no-verbose]
              # Verbose output.
              # Default: false
```

List pacticipants

### Webhooks

#### create-webhook

```
Usage:
  pact-broker create-webhook URL -X, --request=METHOD -b, --broker-base-url=BROKER_BASE_URL

Options:
  -X, --request=METHOD
              # Webhook HTTP method
  -H, [--header=one two three]
              # Webhook Header
  -d, [--data=DATA]
              # Webhook payload. Provide a JSON string (remember to escape
                characters appropriately for the shell) or a file path prefixed
                with the @ symbol, as per the curl usage for this flag.
  -u, [--user=USER]
              # Webhook basic auth username and password eg. username:password
      [--consumer=CONSUMER]
              # Consumer name
      [--consumer-label=CONSUMER_LABEL]
              # Consumer label, mutually exclusive with consumer name
      [--provider=PROVIDER]
              # Provider name
      [--provider-label=PROVIDER_LABEL]
              # Provider label, mutually exclusive with provider name
      [--description=DESCRIPTION]
              # Webhook description
      [--contract-content-changed], [--no-contract-content-changed]
              # Trigger this webhook when the pact content changes
      [--contract-published], [--no-contract-published]
              # Trigger this webhook when a pact is published
      [--provider-verification-published], [--no-provider-verification-published]
              # Trigger this webhook when a provider verification result is
                published
      [--provider-verification-failed], [--no-provider-verification-failed]
              # Trigger this webhook when a failed provider verification
                result is published
      [--provider-verification-succeeded], [--no-provider-verification-succeeded]
              # Trigger this webhook when a successful provider verification
                result is published
      [--contract-requiring-verification-published], [--no-contract-requiring-verification-published]
              # Trigger this webhook when a contract is published that
                requires verification
      [--team-uuid=UUID]
              # UUID of the PactFlow team to which the webhook should be
                assigned (PactFlow only)
  -b, --broker-base-url=BROKER_BASE_URL
              # The base URL of the Pact Broker
  -u, [--broker-username=BROKER_USERNAME]
              # Pact Broker basic auth username
  -p, [--broker-password=BROKER_PASSWORD]
              # Pact Broker basic auth password
  -k, [--broker-token=BROKER_TOKEN]
              # Pact Broker bearer token
  -v, [--verbose], [--no-verbose]
              # Verbose output.
              # Default: false
```

Description:
  Create a curl command that executes the request that you want your webhook to execute, then replace "curl" with "pact-broker create-webhook" and add the
  consumer, provider, event types and broker details. Note that the URL must be the first parameter when executing create-webhook.

  Note that the -u option from the curl command clashes with the -u option from the pact-broker CLI. When used in this command, the -u will be used as a curl
  option. Please use the --broker-username or environment variable for the Pact Broker username.

#### create-or-update-webhook

```
Usage:
  pact-broker create-or-update-webhook URL --uuid=UUID -X, --request=METHOD -b, --broker-base-url=BROKER_BASE_URL

Options:
  -X, --request=METHOD
              # Webhook HTTP method
  -H, [--header=one two three]
              # Webhook Header
  -d, [--data=DATA]
              # Webhook payload. Provide a JSON string (remember to escape
                characters appropriately for the shell) or a file path prefixed
                with the @ symbol, as per the curl usage for this flag.
  -u, [--user=USER]
              # Webhook basic auth username and password eg. username:password
      [--consumer=CONSUMER]
              # Consumer name
      [--consumer-label=CONSUMER_LABEL]
              # Consumer label, mutually exclusive with consumer name
      [--provider=PROVIDER]
              # Provider name
      [--provider-label=PROVIDER_LABEL]
              # Provider label, mutually exclusive with provider name
      [--description=DESCRIPTION]
              # Webhook description
      [--contract-content-changed], [--no-contract-content-changed]
              # Trigger this webhook when the pact content changes
      [--contract-published], [--no-contract-published]
              # Trigger this webhook when a pact is published
      [--provider-verification-published], [--no-provider-verification-published]
              # Trigger this webhook when a provider verification result is
                published
      [--provider-verification-failed], [--no-provider-verification-failed]
              # Trigger this webhook when a failed provider verification
                result is published
      [--provider-verification-succeeded], [--no-provider-verification-succeeded]
              # Trigger this webhook when a successful provider verification
                result is published
      [--contract-requiring-verification-published], [--no-contract-requiring-verification-published]
              # Trigger this webhook when a contract is published that
                requires verification
      [--team-uuid=UUID]
              # UUID of the PactFlow team to which the webhook should be
                assigned (PactFlow only)
  -b, --broker-base-url=BROKER_BASE_URL
              # The base URL of the Pact Broker
  -u, [--broker-username=BROKER_USERNAME]
              # Pact Broker basic auth username
  -p, [--broker-password=BROKER_PASSWORD]
              # Pact Broker basic auth password
  -k, [--broker-token=BROKER_TOKEN]
              # Pact Broker bearer token
  -v, [--verbose], [--no-verbose]
              # Verbose output.
              # Default: false
      --uuid=UUID
              # Specify the uuid for the webhook
```

Description:
  Create a curl command that executes the request that you want your webhook to execute, then replace "curl" with "pact-broker create-or-update-webhook" and
  add the consumer, provider, event types and broker details. Note that the URL must be the first parameter when executing create-or-update-webhook and a uuid
  must also be provided. You can generate a valid UUID by using the `generate-uuid` command.

  Note that the -u option from the curl command clashes with the -u option from the pact-broker CLI. When used in this command, the -u will be used as a curl
  option. Please use the --broker-username or environment variable for the Pact Broker username.

#### test-webhook

```
Usage:
  pact-broker test-webhook --uuid=UUID -b, --broker-base-url=BROKER_BASE_URL

Options:
      --uuid=UUID
              # Specify the uuid for the webhook
  -b, --broker-base-url=BROKER_BASE_URL
              # The base URL of the Pact Broker
  -u, [--broker-username=BROKER_USERNAME]
              # Pact Broker basic auth username
  -p, [--broker-password=BROKER_PASSWORD]
              # Pact Broker basic auth password
  -k, [--broker-token=BROKER_TOKEN]
              # Pact Broker bearer token
  -v, [--verbose], [--no-verbose]
              # Verbose output.
              # Default: false
```

Test the execution of a webhook

### Branches

#### delete-branch

```
Usage:
  pact-broker delete-branch --branch=BRANCH -a, --pacticipant=PACTICIPANT -b, --broker-base-url=BROKER_BASE_URL

Options:
  -a, --pacticipant=PACTICIPANT
              # The name of the pacticipant that the branch belongs to.
      --branch=BRANCH
              # The pacticipant branch name.
      [--error-when-not-found], [--no-error-when-not-found]
              # Raise an error if the branch that is to be deleted is not
                found.
              # Default: true
  -b, --broker-base-url=BROKER_BASE_URL
              # The base URL of the Pact Broker
  -u, [--broker-username=BROKER_USERNAME]
              # Pact Broker basic auth username
  -p, [--broker-password=BROKER_PASSWORD]
              # Pact Broker basic auth password
  -k, [--broker-token=BROKER_TOKEN]
              # Pact Broker bearer token
  -v, [--verbose], [--no-verbose]
              # Verbose output.
              # Default: false
```

Deletes a pacticipant branch. Does not delete the versions or pacts/verifications associated with the branch, but does make the pacts inaccessible for verification via consumer versions selectors or WIP pacts.

### Tags

#### create-version-tag

```
Usage:
  pact-broker create-version-tag -a, --pacticipant=PACTICIPANT -b, --broker-base-url=BROKER_BASE_URL -e, --version=VERSION

Options:
  -a, --pacticipant=PACTICIPANT
              # The pacticipant name
  -e, --version=VERSION
              # The pacticipant version
  -t, [--tag=TAG]
              # Tag name for pacticipant version. Can be specified multiple
                times.
      [--auto-create-version], [--no-auto-create-version]
              # Automatically create the pacticipant version if it does not
                exist.
              # Default: false
  -g, [--tag-with-git-branch], [--no-tag-with-git-branch]
              # Tag pacticipant version with the name of the current git
                branch.
              # Default: false
  -b, --broker-base-url=BROKER_BASE_URL
              # The base URL of the Pact Broker
  -u, [--broker-username=BROKER_USERNAME]
              # Pact Broker basic auth username
  -p, [--broker-password=BROKER_PASSWORD]
              # Pact Broker basic auth password
  -k, [--broker-token=BROKER_TOKEN]
              # Pact Broker bearer token
  -v, [--verbose], [--no-verbose]
              # Verbose output.
              # Default: false
```

Add a tag to a pacticipant version

### Versions

#### describe-version

```
Usage:
  pact-broker describe-version -a, --pacticipant=PACTICIPANT -b, --broker-base-url=BROKER_BASE_URL

Options:
  -a, --pacticipant=PACTICIPANT
              # The name of the pacticipant that the version belongs to.
  -e, [--version=VERSION]
              # The pacticipant version number.
  -l, [--latest=[TAG]]
              # Describe the latest pacticipant version. Optionally specify a
                TAG to describe the latest version with the specified tag.
  -o, [--output=OUTPUT]
              # json or table or id
              # Default: table
  -b, --broker-base-url=BROKER_BASE_URL
              # The base URL of the Pact Broker
  -u, [--broker-username=BROKER_USERNAME]
              # Pact Broker basic auth username
  -p, [--broker-password=BROKER_PASSWORD]
              # Pact Broker basic auth password
  -k, [--broker-token=BROKER_TOKEN]
              # Pact Broker bearer token
  -v, [--verbose], [--no-verbose]
              # Verbose output.
              # Default: false
```

Describes a pacticipant version. If no version or tag is specified, the latest version is described.

#### create-or-update-version

```
Usage:
  pact-broker create-or-update-version -a, --pacticipant=PACTICIPANT -b, --broker-base-url=BROKER_BASE_URL -e, --version=VERSION

Options:
  -a, --pacticipant=PACTICIPANT
              # The pacticipant name
  -e, --version=VERSION
              # The pacticipant version number
      [--branch=BRANCH]
              # The repository branch name
  -t, [--tag=TAG]
              # Tag name for pacticipant version. Can be specified multiple
                times.
  -b, --broker-base-url=BROKER_BASE_URL
              # The base URL of the Pact Broker
  -u, [--broker-username=BROKER_USERNAME]
              # Pact Broker basic auth username
  -p, [--broker-password=BROKER_PASSWORD]
              # Pact Broker basic auth password
  -k, [--broker-token=BROKER_TOKEN]
              # Pact Broker bearer token
  -v, [--verbose], [--no-verbose]
              # Verbose output.
              # Default: false
  -o, [--output=OUTPUT]
              # json or text
              # Default: text
```

Create or update pacticipant version by version number

### Miscellaneous

#### generate-uuid

```
Usage:
  pact-broker generate-uuid

Options:
```

Generate a UUID for use when calling create-or-update-webhook

### Provider contracts (PactFlow only)

#### publish-provider-contract

```
Usage:
  pactflow publish-provider-contract CONTRACT_FILE ... --provider=PROVIDER -a, --provider-app-version=PROVIDER_APP_VERSION -b, --broker-base-url=BROKER_BASE_URL

Options:
      --provider=PROVIDER
              # The provider name
  -a, --provider-app-version=PROVIDER_APP_VERSION
              # The provider application version
  -h, [--branch=BRANCH]
              # Repository branch of the provider version
  -t, [--tag=TAG]
              # Tag name for provider version. Can be specified multiple
                times.
      [--specification=SPECIFICATION]
              # The contract specification
              # Default: oas
      [--content-type=CONTENT_TYPE]
              # The content type. eg. application/yml
      [--verification-success], [--no-verification-success]
              # Whether or not the self verification passed successfully.
      [--verification-exit-code=N]
              # The exit code of the verification process. Can be used instead
                of --verification-success|--no-verification-success for a
                simpler build script.
      [--verification-results=VERIFICATION_RESULTS]
              # The path to the file containing the output from the
                verification process
      [--verification-results-content-type=VERIFICATION_RESULTS_CONTENT_TYPE]
              # The content type of the verification output eg. text/plain,
                application/yaml
      [--verification-results-format=VERIFICATION_RESULTS_FORMAT]
              # The format of the verification output eg. junit, text
      [--verifier=VERIFIER]
              # The tool used to verify the provider contract
      [--verifier-version=VERIFIER_VERSION]
              # The version of the tool used to verify the provider contract
      [--build-url=BUILD_URL]
              # The build URL that created the provider contract
  -o, [--output=OUTPUT]
              # json or text
              # Default: text
  -b, --broker-base-url=BROKER_BASE_URL
              # The base URL of the Pact Broker
  -u, [--broker-username=BROKER_USERNAME]
              # Pact Broker basic auth username
  -p, [--broker-password=BROKER_PASSWORD]
              # Pact Broker basic auth password
  -k, [--broker-token=BROKER_TOKEN]
              # Pact Broker bearer token
  -v, [--verbose], [--no-verbose]
              # Verbose output.
              # Default: false
```

Publish provider contract to PactFlow

<!-- end-autogenerated-docs -->

## Usage - Ruby

### Consumer

```ruby
# In Gemfile

gem "pact_broker-client"
```

```ruby
# In Rakefile

require 'pact_broker/client/tasks'

PactBroker::Client::PublicationTask.new do | task |
  require 'my_consumer/version'
  task.consumer_version = ENV["GIT_COMMIT"]
  task.pattern = 'custom/path/to/pacts/*.json' # optional, default value is 'spec/pacts/*.json'
  task.pact_broker_base_url = "http://pact-broker"
  task.branch = ENV["GIT_BRANCH"] # Optional but STRONGLY RECOMMENDED.
  task.tag_with_git_branch = true|false # Superseeded by the `branch` property
  task.tags = ["dev"] # optional
  task.build_url = ENV["CI_BUILD_URL"]
  task.pact_broker_basic_auth =  { username: 'basic_auth_user', password: 'basic_auth_pass'} # optional
  task.pact_broker_token = "1234abcd" # Bearer token
  task.write_method = :merge # optional, this will merge the published pact into an existing pact rather than overwriting it if one exists. Not recommended, as it makes a mulch of the workflow on the broker.
end
```

```bash
# In CI script

bundle exec rake pact:publish
```

[pact-ruby-standalone]: https://github.com/pact-foundation/pact-ruby-standalone/releases
[docker]: https://hub.docker.com/r/pactfoundation/pact-cli