Package: codecov-cli
CodecovCLICodecovCLI 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 codecovCLI. It saves commits, creates reports, uploads coverage and has many more features.CodecovCLIInstallingUsing PIPAs a BinaryIntegrity Checking the BinaryHow to Upload to CodecovHow to Get an Upload TokenUsageCodecov-cli Commandscreate-commitcreate-reportdo-uploadcreate-report-resultsget-report-resultspr-base-pickingsend-notificationsempty-uploadHow to Use Local UploadWork in Progress FeaturesPlugin SystemStatic AnalysisContributionsRequirementsGuidelinesDependenciesReleasesInstallingUsing PIPTo use codecov-cli in your local machine, or your CI workflows, you need to install it:pip install codecov-cliThe above command will download the latest version of Codecov-cli. If you wish to use a specific version, releases can be viewedhere.Note: If you're installing in apyenvenvironment, you may need to callpyenv rehashbefore the CLI will work.As a BinaryIf 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 foundhere, along with SHASUMs and signatures for each released version. Binary releases are also available viaGithub releaseson 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 --helpIntegrity Checking the BinaryThe 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.SHA256SUMFor macos you will want to use the macos distributions of the binary (e.g.,https://cli.codecov.io/latest/macos/codecov)How to Upload to CodecovIf desired, the CLI can be used as a replacement for ourNodeJS 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-uploadORpip install codecov-cli
codecovcli upload-processcodecovcli upload-process is a wrapper for create-commit, create-report and do-upload.You can customize the commands with the options aligned with each command.Note that these commands will automatically search your environment for a$CODECOV_TOKENenvironment 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 intoeach command manually, like so:-t {$CODECOV_TOKEN}.How to Get an Upload TokenThe following tokens are suitable for uploading:TheRepository Upload Token: Found on the settings page of your repository, also viewable on the/newpage when setting up a repository on Codecov for the first time.TheGlobal Upload Token: Found on your organization settings page (e.g.,https://app.codecov.io/account/<scm>/<org>/org-upload-token).UsageIf the installation is successful, runningcodecovcli --helpwill output the available commands along with the different general options that can be used with them.Usage: codecovcli [OPTIONS] COMMAND [ARGS]...Codecov-cli supports user input. These inputs, along with their descriptions and usage contexts, are listed in the table below:InputDescriptionUsage--auto-load-params-fromThe CI/CD platformOptional--codecov-yml-pathThe path for your codecov.ymlOptional--enterprise-urlChange the upload host (Enterprise use)Optional--versionCodecov-cli's versionOptional--verboseor-vRun the cli with verbose loggingOptionalCodecov-cli CommandsCommandDescriptioncreate-commitSaves the commit's metadata in codecov, it's only necessary to run this once per commitcreate-reportCreates an empty report in codecov with initial data e.g. report name, report's commitdo-uploadSearches for and uploads coverage data to codecovcreate-report-resultsUsed for local upload. It tells codecov that you finished local uploading and want it to calculate the results for you to get them locally.get-report-resultsUsed for local upload. It asks codecov to provide you the report results you calculated with the previous command.pr-base-pickingTells codecov that you want to explicitly define a base for your PRupload-processA wrapper for 3 commands. Create-commit, create-report and do-upload. You can use this command to upload to codecov instead of using the previosly mentioned commands.send-notificationA command that tells Codecov that you finished uploading and you want to be sent notifications. To disable automatically sent notifications please consider adding manual_trigger to your codecov.yml, so it will look like codecov: notify: manual_trigger: true.Note: Every command has its own different options that will be mentioned later in this doc. Codecov will try to load these options from your CI environment variables, if not, it will try to load them from git, if not found, you may need to add them manually.create-commitcodecovcli create-commit [Options]OptionDescriptionUsage-C, --sha, --commit-shaCommit SHA (with 40 chars)Required--parent-shaSHA (with 40 chars) of what should be the parent of this commitOptional-P, --pr, --pull-request-numberSpecify the pull request number manually. Used to override pre-existing CI environment variablesOptional-B, --branchBranch to which this commit belongs toOptional-r, --slugowner/repo slug used instead of the private repo token in Self-hostedRequired-t, --tokenCodecov upload tokenRequired--git-serviceGit Provider. Options: github, gitlab, bitbucket, github_enterprise, gitlab_enterprise, bitbucket_serverRequired-h, --helpShows usage, and command optionscreate-reportcodecovcli create-report [OPTIONS]OptionDescriptionUsage-C, --sha, --commit-shaCommit SHA (with 40 chars)Required-r, --slugowner/repo slug used instead of the private repo token in Self-hostedRequired-t, --tokenCodecov upload tokenRequired--git-serviceGit Provider. Options: github, gitlab, bitbucket, github_enterprise, gitlab_enterprise, bitbucket_serverRequired--codeThe code of the report. This 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.Optional-h, --helpShows usage, and command optionsdo-uploadcodecovcli do-upload [OPTIONS]OptionDescriptionUsage-C, --sha, --commit-shaCommit SHA (with 40 chars)Required--report-codeThe code of the report defined when creating the report. If unsure, leave defaultOptional--network-root-folderRoot folder from which to consider paths on the network section  default: (Current working directory)Optional-s, --dir, --coverage-files-search-root-folderFolder where to search for coverage files default: (Current Working Directory)Optional--exclude, --coverage-files-search-exclude-folderFolders to exclude from searchOptional-f, --file, --coverage-files-search-direct-fileExplicit files to uploadOptional--disable-searchDisable search for coverage files. This is helpful when specifying what files you want to upload with the --file option.Optional-b, --build, --build-codeSpecify the build number manuallyOptional--build-urlThe URL of the build where this is runningOptional--job-codeThe job code for the CI runOptional-t, --tokenCodecov upload tokenRequired-n, --nameCustom defined name of the upload. Visible in Codecov UIOptional-B, --branchBranch to which this commit belongs toOptional-r, --slugowner/repo slugRequired-P, --pr, --pull-request-numberSpecify the pull request number manually. Used to override pre-existing CI environment variablesOptional-e, --env, --env-varSpecify environment variables to be included with this build.Optional-F, --flagFlag the upload to group coverage metrics. Multiple flags allowed.Optional--pluginplugins to run. Options: xcode, gcov, pycoverage. The default behavior runs them all.Optional-Z, --fail-on-errorExit with non-zero code in case of error uploading.Optional-d, --dry-runDon't upload files to CodecovOptional--legacy, --use-legacy-uploaderUse the legacy upload endpointOptional--git-serviceGit Provider. Options: github, gitlab, bitbucket, github_enterprise, gitlab_enterprise, bitbucket_serverRequired-h, --helpShows usage, and command optionscreate-report-resultscodecovcli create-report-results [OPTIONS]OptionDescriptionUsage--commit-shaCommit SHA (with 40 chars)Required--codeThe code of the report. If unsure, leave defaultRequired--slugowner/repo slugRequired--git-serviceGit provider. Options: github, gitlab, bitbucket, github_enterprise, gitlab_enterprise, bitbucket_serverOptional-t, --tokenCodecov upload tokenRequired-h, --helpShows usage, and command optionsget-report-resultscodecovcli get-report-results [OPTIONS]OptionDescriptionUsage--commit-shaCommit SHA (with 40 chars)Required--codeThe code of the report. If unsure, leave defaultRequired--slugowner/repo slugRequired--git-serviceGit provider. Options: github, gitlab, bitbucket, github_enterprise, gitlab_enterprise, bitbucket_serverOptional-t, --tokenCodecov upload tokenRequired-h, --helpShows usage, and command optionspr-base-pickingcodecovcli pr-base-picking [OPTIONS]OptionDescriptionUsage--base-shaBase commit SHA (with 40 chars)Required--prPull Request id to associate commit withRequired--slugowner/repo slugRequired-t, --tokenCodecov upload tokenRequired--serviceGit provider. Options: github, gitlab, bitbucket, github_enterprise, gitlab_enterprise, bitbucket_serverOptional-h, --helpShows usage, and command optionssend-notificationscodecovcli send-notifications [OPTIONS]OptionDescriptionUsage-C, --sha, --commit-sha TEXTCommit SHA (with 40 chars)Required-r, --slug TEXTowner/repo slug used instead of the private repo token in Self-hostedRequired-t, --token TEXTCodecov upload tokenRequired--git-serviceGit provider. Options: github, gitlab, bitbucket, github_enterprise, gitlab_enterprise, bitbucket_serverOptional-h,--helpShow this message and exit.empty-uploadUsed if the changes made don't need testing, but PRs require a passing codecov status to be merged.
This command will scan the files in the commit and send passing status checks configured if all the changed files
are ignored by codecov (including README and configuration files)Usage: codecovcli empty-upload [OPTIONS]Options:
-C, --sha, --commit-sha TEXT    Commit SHA (with 40 chars)  [required]
-Z, --fail-on-error             Exit with non-zero code in case of error
--git-service [github|gitlab|bitbucket|github_enterprise|gitlab_enterprise|bitbucket_server]
-t, --token TEXT                Codecov upload token
-r, --slug TEXT                 owner/repo slug used instead of the private
repo token in Self-hosted
-h, --help                      Show this message and exit.How to Use Local UploadThe 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>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.Work in Progress FeaturesThe following features are somewhat implemented in code, but are not yet meant for use. These features will be documented once they are fully implemented in the CLI.Plugin SystemTo provide extensibility to some of its commands, the CLI makes use of a plugin system. For most cases, the default commands are sufficient. But in some cases, having some custom logic specific to your use case can be beneficial. Note that full documentation of the plugin system is pending, as the feature is still heavily a work in progress.Static AnalysisThe CLI can perform basic static analysis on Python code today. This static analysis is meant to power more future looking Codecov features and, as such, is not required or in active use today. As more functionality dependent on static analysis becomes available for use, we will document static analysis in detail here.ContributionsThis repository, like all of Codecov's repositories, strives to follow our generalContributing guidlines. If you're considering making a contribution to this repository, we encourage review of our Contributing guidelines first.RequirementsMost of this package is a very conventional Python package. The main difference is the static the CLI's analysis module uses both git submodules and C codeBefore installing, one should pull the submodules with:git submodule update --initThen, install dependencies withpip install -r requirements.txt 
python setup.py developThe C code shouldn't require any additional setup to get running, but depending on your environment, you may be prompted to install compilers and supporting tools. If errors are generated during installation, it is likely due to missing dependencies / tools required of the C code. In many cases, resulting error messages should be clear enough to determine what is missing and how to install it, but common errors will be collected here as they are encountered.GuidelinesThere are a few guidelines when developing in this system. Some notable folders:commands- It's the folder that interacts with the caller. This is where the commands themselves should reside. These commands are not meant to do heavy lifting. They only do wiring, which is mostly parsing the input parameters.services- It's where the heavy logic resides. It's mostly organized by which command needs them. Commands should generally be thin wrappers around these services.helpers- This is meant for logic that is useful across different commands. For example, logging helpers, or the logic that searches folders.DependenciesIf external dependencies need to be added, it's important to check whether those dependencies have wheels available on PyPI with theanyoruniversal2platform tags. If those dependencies don't have those wheels available, then they will need to built during the CI, so they will have to be added to the list of
dependencies in the--no-binaryflag when building the requirements for the macos release inbuild_assets.yml.ReleasesThe standard way to making a new release is the following:Open a PR that increases the version number in setup.py. As a rule of thumb, just add one to the micro/patch version (e.g., v0.1.6 -> v0.1.7).Get the up-to-date master branch locally and run thetag.releasecommand from the Makefile.$ make tag.release version=v<VERSION_NUM>The version tag must match the regex defined on the Makefile (tag_regex := ^v([0-9]{1,}\.){2}[0-9]{1,}([-_]\w+)?$).Note:Releases withtestword in them are created asdraft.Releases withbetaword in them are created aspre-release.