Tools: GC CLI

GoCardless CLI

Build, test, and manage your GC integration from your terminal.

gc is the official GoCardless command-line interface (CLI).

The GC CLI is a developer tool to help you build, test and manage your integration with GC directly from your terminal.

It’s simple to install, works on macOS, Windows, and Linux, and offers a range of functionality to enhance your developer experience. You can use the GC CLI to:

  • Create, retrieve, update, or delete any of your GC resources in test mode (e.g. create a payment)

  • Stream real-time API requests and events (webhooks) happening in your account

  • Trigger events to test your webhooks integration

Installation

To install the GC CLI with homebrew run:

brew install gocardless/taps/cli

After installing you should have a gc binary available now.

To install the GC CLI on macOS without homebrew:

  1. Download the latest macOS tar.gz file from here

  2. Unzip the file tar -xvf gc-cli_<version>_macOS_<arch>.tar.gz (<version> and <arch> will depend on which file you download).

  3. Move ./gc to a location where you can execute it globally (typically /usr/local/bin)

To install the GC CLI on Windows:

  1. Download the latest Windows zip file from here

  2. Unzip the file: tar -xvf gc-cli_<version>_Windows_<arch>.tar.gz (<version> and <arch> will depend on which file you download).

To install the GC CLI on Windows:

  1. Download the latest Windows zip file from here

  2. Unzip the file: tar -xvf gc-cli_<version>_Windows_<arch>.tar.gz (<version> and <arch> will depend on which file you download).

  3. Move ./gc to an execution location.

The GC CLI is also available as a Docker image. To install the latest version: run:

docker run -rm -it gocardless/gc-cli:latest

You can execute commands by passing them as arguments to it.

Login to your GC Account

After you have the GC CLI installed, run gc login in the command line to grant the CLI access to your merchant account. This will open your browser to an authorisation page to login and authorise the merchant.

$ gc login Open browser to authenticate: https://connect-sandbox.gocardless.com/oauth/authorize?

If you are testing a partner integration and want to authenticate with an existing App, use the –app flag and specify your app’s ID:

$ gc login --app AP0001 You appear to be authorizing a new App. Ensure you have one of the apps OAuth redirect url set to http://localhost:8080/callback ? Enter your app's Client ID: **** ? Enter your app's Client Secret: ****** Open browser to authenticate: https://connect-sandbox.gocardless.com/oauth/authorize?client_id=ABcd

Run your first command

Now that gc is authorised to work with your merchant, try some test commands:

You can fetch a list of resources using the list command. For example, to fetch the list of mandates on the connected merchant's account:

$ gc list mandates

This should return a response similar to:

{ "mandates": [ { "created_at": "2022-02-15T15:31:56.532Z", "id": "MD000JB824KAF6", "links": { "creditor": "CR00006TSFRA16", "customer": "CU000JW1H9DV8J", "customer_bank_account": "BA000JB1YRVSNF" }, "metadata": {}, "next_possible_charge_date": null, "payments_require_approval": false, "reference": "SOMEORGANISA-9M9NT", "scheme": "faster_payments", "status": "consumed" } ], "meta": { "cursors": { "after": null, "before": null }, "limit": 50 } }

View the list command reference for a list of resources you can fetch. Also, you can view a list of all commands using the gc help command.

Next Steps

Need help?