Codecov CLI

Installation

Using Pip

To use codecov-cli in your local machine, or your CI workflows, you need to install it:

pip install codecov-cli

The above command will download the latest version of Codecov-cli. If you wish to use a specific version, releases can be viewed here.

Your default will need to be Python3 in order to make this work.

Note: If you're installing in a pytest environment, you may need to call pytest rehash before the CLI will work.

As a Binary

If you would like to use the CLI in an environment that does not have access to Python / PIP, you can install the CLI as a compiled binary. Linux and macOS releases can be found here, along with SHASUMs and signatures for each released version. Binary releases are also available via Github releases on this repository.

You can retrieve the Binary for Linux directly from your command line as follows:

curl -Os https://cli.codecov.io/latest/linux/codecov
sudo chmod +x codecov
./codecov --help

Integrity Checking the Binary

The binary can be integrity checked using a SHASUM256 and SHASUM256.sig file. The process for macos and Linux is identical. Linux is as follows:

curl https://keybase.io/codecovsecurity/pgp_keys.asc | gpg --no-default-keyring --keyring trustedkeys.gpg --import # One-time step  
curl -Os https://cli.codecov.io/latest/linux/codecov
curl -Os https://cli.codecov.io/latest/linux/codecov.SHA256SUM
curl -Os https://cli.codecov.io/latest/linux/codecov.SHA256SUM.sig

gpgv codecov.SHA256SUM.sig codecov.SHA256SUM

shasum -a 256 -c codecov.SHA256SUM

For macos you will want to use the macos distributions of the binary (e.g., <https://cli.codecov.io/latest/macos/codecov>)

📘

--help

If the installation is successful, running codecovcli --help will output the available commands along with the different general options that can be used with them

Usage

Usage: codecov-cli [OPTIONS] COMMAND [ARGS]...

Codecov-cli supports user input. These inputs, along with their descriptions and usage contexts, are listed in the table below:

How to Upload to Codecov

If desired, the CLI can be used as a replacement for our NodeJS Binary Uploader. To use the CLI to upload from your CI workflow, you need to add these commands:

curl -Os https://cli.codecov.io/latest/linux/codecov
sudo chmod +x codecov

./codecov --verbose upload-process --fail-on-error -t ${{ secrets.CODECOV_TOKEN }} -n 'job-name'-${{ github.run_id }} -F <flag name> -f <covarage report file name>

Alternativily, you can setup the CLI via the `pip install command

pip install codecov-cli
codecovcli upload-process

Note that this command will automatically search your environment for a $CODECOV_TOKEN environment variable and use it if found. If you do not have a repository upload token, or global upload token, stored as an environment variable, you will need to pass it into each command manually, like so: -t {$CODECOV_TOKEN}.

You can customize each of these commands with additional options that are detailed on our CLI options doc.

📘

Switching to the CLI from a different upload method?

You will need to take out your old uploader step and replace it with the above commands to upload to Codecov using the CLI.

How to Get an Upload Token

The following tokens are suitable for uploading:

• The Repository Upload Token: Found on the settings page of your repository, also viewable on the /new page when setting up a repository on Codecov for the first time.
• The Global Upload Token: Found on your organization settings page (e.g., https://app.codecov.io/account///org-upload-token).
  • From the repo list of an org (codecov.io/XX/orgName) you can navigate to your token via settings > global upload token.

Refresher on defining environmental variables: For GitHub, For Bitbucket, For Gitlab.

How to use Local Upload

The CLI also supports "dry run" local uploading. This is useful if you prefer to see Codecov status checks and coverage reporting locally, in your terminal, as opposed to opening a PR and waiting for your full CI to run. Local uploads do not interfere with regular uploads made from your CI for any given commit / Pull Request.

Local Upload is accomplished as follows:

pip install codecov-cli  
codecovcli create-commit  
codecovcli create-report --code <CODE>  
codecovcli do-upload --report-code <CODE>  
codecovcli create-report-results --code <CODE>  
codecovcli get-report-results --code <CODE>

<CODE> is used in local uploading to isolate local reports from regular or cloud reports uploaded to codecov so they don't get merged. It's basically a name you give to your report e.g. local-report.

Codecov will calculate the coverage results, and return them in your terminal, telling you whether your PR will fail or pass the coverage check.

Note: In order for Local Upload to work, it must be used against a commit on the origin repository. Local Upload does not work for arbitrary diffs or uncommitted changes on your local machine.