The 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://uploader.codecov.io/latest/linux/codecov
curl -Os https://uploader.codecov.io/latest/linux/codecov.SHA256SUM
curl -Os https://uploader.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://uploader.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:

pip install codecov-cli
codecovcli create-commit
codecovcli create-report
codecovcli do-upload

Note that these commands 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.

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).

Global Upload Token

A global upload token can be used to upload coverage reports for any repository in an organization. A global upload token can be generated on the Organization Settings page in the Codecov UI. The token is used as follows:

curl -Os https://uploader.codecov.io/v0.1.0_4653/linux/codecov

chmod +x codecov
./codecov -t <organization_upload_token> -r <org_name>/<repo_name>

## Real example
## ./codecov -t ${CODECOV_TOKEN} -r codecov/example_python

The global upload token can be stored in a CODECOV_TOKEN environment variable and used identically to the repository upload token for any repository in the token's organization. However, the use of the -r parameter to identify the organization and repo is required.

🚧

Treat your Global Upload Token as a sensitive credential!

The global upload token is quite powerful, allowing for the successful upload to any repository in the organization for which the token was generated. You should treat this credential as sensitive, and use the appropriate secret management strategies (e.g, Vault, GitHub Secrets, or some other credential storage) as defined by your own internal policies to store it.

You should never commit this credential to source control.

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.