Understanding how your coverage evolves with each code change is crucial, and we believe that having data readily available in your terminal was the perfect solution. We created Codecov’s command line interface (CLI) so you can configure code coverage – and more, right in the command line.
Now you can save time by not having to wait for your entire CI pipeline to run or comb through browser tabs to learn about gaps in test coverage. Plus, you can use the Codecov CLI to upload coverage reports to Codecov and access the latest Codecov features like Local Upload, Global Upload Token, and PR Base Picking.
Local Upload
Have you ever wanted to see if your Codecov status checks pass or fail before opening a pull/merge request? With Local Upload you can quickly see if your code changes will pass or fail Codecov’s check locally, in your terminal on every commit. Now instead of waiting an unreasonable amount of time for your entire CI pipeline to run and constantly refreshing your browser, you can ensure you meet your team’s standards prior to pushing anything.
Global Upload Token
Historically, you needed a unique upload token to configure a repo with Codecov. This worked fine if you had just a handful of repos to configure. But as your team grows and your code base evolves, you shouldn’t have to repeat yourself – we too subscribe to the DRY philosophy. So to minimize repetition and make it easier to get multiple repos configured, you can generate a Global Upload Token from your Codecov Settings page, and use it instead of a repository token when uploading using the CLI. This token is scoped to an organization and it can be used in lieu of the repository upload token for all repositories within that organization.
Using the Global Upload Token is easy, simply use it in place of the normal Repository Upload Token in the CLIs upload command:
codecovcli do-upload -t ${YOUR_GLOBAL_UPLOAD_TOKEN}
PR Base Picking
In the realm of code review, the choice of commit for comparison is crucial. By default, comparisons are made between the head and base of a branch, but this approach may not accurately reflect coverage changes when merging to the main/master branch in high-velocity development organizations.
The Codecov CLI enables the PR Base Picking feature which allows developers to select the base commit and offers advantages like improved coverage accuracy and flexibility. With this feature, code reviews become more representative, ensuring reliable insights into changes and enabling better collaboration among development teams.
How to Install the CLI
Note: full documentation for how to install and use the CLI can be found within its open source GitHub repository
To get started using the CLI, install it by using `pip` or as a binary.
Using PIP
pip install codecov-cli
The above command will download the latest version of the CLI. If you wish to use a specific version, releases can be viewed here. You can add this as a step in your CI, or add the dependency to a requirements.txt file.
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.
Using the Codecov CLI
You can use the CLI to upload coverage reports to Codecov using the 3 commands, create-commit, create-report, and do-upload.
As an example, if you are using GitHub actions, you can add a step after coverage collection that looks like this.
name: Upload coverage reports to Codecov
run: |
codecovcli create-commit
codecovcli create-report
codecovcli do-upload
env:
CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}The CODECOV_TOKEN can be found in the settings tab of your repository on Codecov.
Frequently Asked Questions
Why did we build the Codecov CLI?
It goes without saying, developers spend a lot of time in the command line. So we built a tool to meet you where you work. Additionally, the building of the CLI gave us an opportunity to overhaul our uploader and lay the foundation for new capabilities beyond test coverage. In addition to the features listed in this post, the CLI also includes:
- A full rewrite — both client and server-side – of our upload functionality that is generally more performant and stable than our previous implementation.
- More methods of distribution, both as a compiled binary and via PIP
- A meaningful reduction in binary size when compared to the NodeJS Uploader,
- A work-in-progress extensible plugin system that makes it easier for users to modify the CLI to suit their needs.
- A static analysis process, powered by the excellent tree-sitter library, will pave the way for future Codecov features and improvements.
Are there plans to deprecate the NodeJS Uploader?
Not immediately. The NodeJS uploader will continue to be supported and will continue to function for those users who have included it in their CI pipelines. We will continue to push fixes to the uploader as needed. We will, however, focus new development efforts on the CLI and its built-in upload functionality. Please note: Any new capabilities and features will not be backward compatible and only be available with the new uploader.
What about the GitHub Action, CircleCI Orb, and BitRise Step?
The CLI will be integrated into our GitHub Action, CircleCI Orb, and BitRise Step primarily to facilitate uploading in much the same way the Uploader is integrated into these tools today. While work to integrate the CLI is currently underway, we’re undertaking this change in such a way that the CI/CD workflows of customers currently using these tools aren’t disrupted.
The Codecov CLI is your trusty companion to save time by configuring code coverage, uploading reports, and accessing advanced features directly from the command line.
Get started today with the new Codecov CLI, drop us a line and let us know what you think. And if you’re new to Codecov you can try it for free today or request a demo to get started.
