Codecov CLI
Codecov CLI is a new way for users to interact with Codecov directly from the user’s terminal or CI platform. Many Codecov features that require the user’s interference can be done via the CLI, it saves commits, creates reports, uploads coverage, and enables access to Codecov's most advanced features.
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, the Codecov CLI expects to be run in the checked out repos, on a machine with git installed.
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. Note, the Codecov CLI expects to be run in the checked out repos, on a machine with git installed.
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:
Input | Description | Usage |
---|---|---|
--auto-load-params-from | The CI/CD Platform | Optional |
--codecov-yml-path | The path for your codecov.yml | Optional |
--enterprise-url | Change the upload host (enterprise use) | Optional |
--version | Codecov-cli's version | Optional |
--verbose or -v | Run the cli with verbose logging | Optional |
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 --disable-search -t ${{ secrets.CODECOV_TOKEN }} -n 'job-name'-${{ github.run_id }} -F <flag name> -f <covarage report file name>
Alternatively, you can setup the CLI via the pip install
command
pip install codecov-cli
codecovcli --verbose upload-process --disable-search -t ${{ secrets.CODECOV_TOKEN }} -n 'job-name'-${{ github.run_id }} -F <flag name> -f <covarage report file name>
The Codecov CLI will need a Codecov upload token to authenticate its requests to Codecov. You can set the token in an environment variable called $CODECOV_TOKEN
or pass it as a command line argument like so: -t ${{ secrets.CODECOV_TOKEN }}
.
Refresher on defining environmental variables: For GitHub, For Bitbucket, For Gitlab.
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 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.
Updated 29 days ago