CLI Options
All of the ways you can customize your Codecov experience via CLI
Once your CLI Installation is successful, there are additional commands and customizations possible.
Usage
Running
codecovcli --helpwill output the available commands along with the different general options that can be used with them.
Usage: codecovcli [OPTIONS] COMMAND [ARGS]...
User Inputs
Codecov-cli supports inputs. 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 |
Codecov-cli Commands
| Command | Description |
|---|---|
create-commit | Saves the commit's metadata in codecov, it's only necessary to run this once per commit |
create-report | Creates an empty report in codecov with initial data e.g. report name, report's commit |
do-upload | Searches for and uploads coverage data to codecov |
create-report-results | Used 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-results | Used for local upload. It asks codecov to provide you the report results you calculated with the previous command. |
pr-base-picking | Tells codecov that you want to explicitly define a base for your PR |
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-commit
codecovcli create-commit [Options]
| Option | Description | Usage |
|---|---|---|
| -C, --sha, --commit-sha | Commit SHA (with 40 chars) | Required |
| --parent-sha | SHA (with 40 chars) of what should be the parent of this commit | Optional |
| -P, --pr, --pull-request-number | Specify the pull request number manually. Used to override pre-existing CI environment variables | Optional |
| -B, --branch | Branch to which this commit belongs to | Optional |
| -r, --slug | owner/repo slug used instead of the private repo token in Self-hosted | Required |
| -t, --token | Codecov upload token | Required |
| --git-service | Git Provider. Options: github, gitlab, bitbucket, github_enterprise, gitlab_enterprise, bitbucket_server | Required |
| --help | Shows usage, and command options |
create-report
codecovcli create-report [OPTIONS]
| Option | Description | Usage |
|---|---|---|
| -C, --sha, --commit-sha | Commit SHA (with 40 chars) | Required |
| -r, --slug | owner/repo slug used instead of the private repo token in Self-hosted | Required |
| -t, --token | Codecov upload token | Required |
| --git-service | Git Provider. Options: github, gitlab, bitbucket, github_enterprise, gitlab_enterprise, bitbucket_server | Required |
| --code | The 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 |
| --help | Shows usage, and command options |
do-upload
codecovcli do-upload [OPTIONS]
| Option | Description | Usage |
|---|---|---|
| -C, --sha, --commit-sha | Commit SHA (with 40 chars) | Required |
| --report-code | The code of the report defined when creating the report. If unsure, leave default | Optional |
| --network-root-folder | Root folder from which to consider paths on the network section default: (Current working directory) | Optional |
| -s, --dir, --coverage-files-search-root-folder | Folder where to search for coverage files default: (Current Working Directory) | Optional |
| --exclude, --coverage-files-search-exclude-folder | Folders to exclude from search | Optional |
| -f, --file, --coverage-files-search-direct-file | Explicit files to upload | Optional |
| -b, --build, --build-code | Specify the build number manually | Optional |
| --build-url | The URL of the build where this is running | Optional |
| --job-code | The job code for the CI run | Optional |
| -t, --token | Codecov upload token | Required |
| -n, --name | Custom defined name of the upload. Visible in Codecov UI | Optional |
| -B, --branch | Branch to which this commit belongs to | Optional |
| -r, --slug | owner/repo slug | Required |
| -P, --pr, --pull-request-number | Specify the pull request number manually. Used to override pre-existing CI environment variables | Optional |
| -e, --env, --env-var | Specify environment variables to be included with this build. | Optional |
| -F, --flag | Flag the upload to group coverage metrics. Multiple flags allowed. | Optional |
| --plugin | plugins to run. Options: xcode, gcov, pycoverage. The default behavior runs them all. noop disables all | Optional |
| -Z, --fail-on-error | Exit with non-zero code in case of error uploading. | Optional |
| -d, --dry-run | Don't upload files to Codecov | Optional |
| --legacy, --use-legacy-uploader | Use the legacy upload endpoint | Optional |
| --git-service | Git Provider. Options: github, gitlab, bitbucket, github_enterprise, gitlab_enterprise, bitbucket_server | Required |
| --disable-file-fixes | Disable file fixes to ignore common lines from coverage (e.g. blank lines or empty brackets) | Optional |
| --help | Shows usage, and command options |
create-report-results
codecovcli create-report-results [OPTIONS]
| Option | Description | Usage |
|---|---|---|
| --commit-sha | Commit SHA (with 40 chars) | Required |
| --code | The code of the report. If unsure, leave default | Required |
| --slug | owner/repo slug | Required |
| --git-service | Git provider. Options: github, gitlab, bitbucket, github_enterprise, gitlab_enterprise, bitbucket_server | Optional |
| -t, --token | Codecov upload token | Required |
| --help | Shows usage, and command options |
get-report-results
codecovcli get-report-results [OPTIONS]
| Option | Description | Usage |
|---|---|---|
| --commit-sha | Commit SHA (with 40 chars) | Required |
| --code | The code of the report. If unsure, leave default | Required |
| --slug | owner/repo slug | Required |
| --git-service | Git provider. Options: github, gitlab, bitbucket, github_enterprise, gitlab_enterprise, bitbucket_server | Optional |
| -t, --token | Codecov upload token | Required |
| --help | Shows usage, and command options |
pr-base-picking
codecovcli pr-base-picking [OPTIONS]
| Option | Description | Usage |
|---|---|---|
| --base-sha | Base commit SHA (with 40 chars) | Required |
| --pr | Pull Request id to associate commit with | Required |
| --slug | owner/repo slug | Required |
| -t, --token | Codecov upload token | Required |
| --service | Git provider. Options: github, gitlab, bitbucket, github_enterprise, gitlab_enterprise, bitbucket_server | Optional |
| --help | Shows usage, and command options |
send-notifications
codecovcli send-notifications
Codecov doesn't intrinsically know when you have finished making uploads for a commit, this allows you to tell us. When this is enabled we'll send one PR comment and you'll be notified just one time that we've posted a comment (if you have notifications for PR comments turned on in your code host of choice).
This particular command also needs a corresponding Codecov yaml setting:
codecov:
notify:
manual trigger: true
empty-upload
Used 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]
| Option | Description | Usage |
|---|---|---|
| -C, --sha, --commit-sha | Base commit SHA (with 40 chars) | Required |
| -t, --token | Codecov upload token | Required |
| -r, --slug | owner/repo slug (used instead of the private repo token in Self-hosted) | Optional |
| --git-service | Git provider. Options: github, gitlab, bitbucket, github_enterprise, gitlab_enterprise, bitbucket_server | Optional |
| -Z, --fail-on-error | Exit with non-zero code in case of error | Optional |
| --help | Show this message and exit. | Optional |
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>
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 2 months ago