@govuk-pay/cli

pay-cli

GOV.UK Pay Command Line Interface

Installation and migration guide

If you have used the Ruby CLI in the past, there are some additional steps required:

• Remove references to pay from your .bashrc (or other autostart shell script, .bash_profile, .zshrc, .zprofile, etc).
• Check which pay, if it points to ~/.rbenv/shims/pay or similar, remove that script. Ideally, it should return pay not found.
• Restart your shell to clear functions and environment variables leftover.

To install the Node.js CLI:

• Run npm install -g @govuk-pay/cli. If npm was installed through Homebrew, you shouldn't need to use sudo to install packages.
• Run pay to see if you are running the new version (new features such as pay tunnel should be available), if not check which pay in case you are using an older version.

There is nothing more to do, you're done! To update, simply run pay update or run npm install -g @govuk-pay/cli again, there are version check notifications if you are behind a version.

Usage

This is published to NPM, you can install it globally using npm install -g @govuk-pay/cli, once it's installed you can run it using pay [arguments] or payx [arguments]. If you'd rather not install it globally you can run it using npx @govuk-pay/cli.

We're in the process of porting the existing Ruby CLI into typescript, we've tried to make that process transparent to the users of the CLI. None of the commands now rely on the ruby implementation, but you can (for now) still execute the ruby versions by using pay legacy. You'll need rbenv installed with bundler installed into it. When handing over to ruby we use zshby default, if you want a different shell orrbenv` you can set the following environment variables:

• PAY_CLI_RBENV_COMMAND - defaults to rbenv
• PAY_CLI_SHELL_COMMAND - defaults to zsh

To see the commands run pay without any arguments.

If you find that the ported typescript version isn't behaving as expected and you want to use the ruby version you can use the command legacy, for example:

• pay browse manual - uses the typescript port to open the team manual
• pay legacy browse manual - uses the original ruby version to open the team manual

Please add an issue any time you need to fall back on legacy behaviour so we can improve the typescript implementation.

Shell auto completion

If you want to enable tab completion of commands and parameters then you can run

pay completion

This will generate a script (for bash or zsh only) which you can put at the end of your .bashrc or .zshrc that will cause your shell to provide auto completions.

Config files

Config files needed by the pay cli will go in `$HOME/.pay-cli"

Pay Local Config Files

You can override environment variables set in the .env files in the pay local services local config directory for specific containers by placing files in $HOME/.pay-cli/local/environment-overrides/<app_name>.env.

For example to override an environment variable for connector which was set in connector.env you could create the file $HOME/.pay-cli/local/environment-overrides/connector.env

Note: This will only override variables set in the .env files, it will not override any variables which get declared in an environment configuration option in the generated docker-compose files. These are generated from the docker-compose.erb template.

You can configure custom clusters by creating a file at $HOME/.pay-cli/local/custom-clusters.yaml following the schema:

clusters:
  - name: my-cool-cluster
    apps:
      - connector
      - selfservice
      - frontend
      - adminusers
      - toolbox
  - name: another-cool-cluster
    apps:
      - connector
      - selfservice
      - frontend

Custom clusters also support pre-defined options, which can be configured by setting options on the cluster config, e.g.

clusters:
  - name: my-cool-cluster
    apps:
      - connector
      - selfservice
      - frontend
    options:
      mountLocalNodeApps: true
      local:
        - selfservice

These will be passed in automatically on running pay local up --cluster my-cool-cluster

Vulnerability Disclosure

GOV.UK Pay aims to stay secure for everyone. If you are a security researcher and have discovered a security vulnerability in this code, we appreciate your help in disclosing it to us in a responsible manner. Please refer to our vulnerability disclosure policy and our security.txt file for details.