Codecov CLI

11.2.8 · active · verified Tue Apr 14

Codecov CLI (Command Line Interface) is a Python-based tool designed to allow users to interact with Codecov directly from their terminal or CI platform. It enables features like saving commit metadata, creating coverage reports, uploading coverage data, and more. The current version is 11.2.8, and it maintains an active development and release cadence, though its underlying codebase has migrated to a sub-project within `getsentry/prevent-cli`.

Warnings

gotcha The `codecov-cli` codebase has migrated from `codecov/codecov-cli` to a sub-project within `getsentry/prevent-cli`. This means that changelogs and GitHub releases for the original `codecov-cli` repository may not be up-to-date with PyPI releases, making it challenging to track changes.
Fix: Refer to the `getsentry/prevent-cli` repository for the most current information regarding `codecov-cli` changes and releases.
deprecated Commands related to 'local upload' have been deprecated as of version 10.4.0. Users should transition to alternative workflows for local coverage checks.
Fix: Consult the latest Codecov documentation for recommended practices for local coverage analysis and interaction.
gotcha For most use cases, particularly with private repositories, `codecov-cli` requires an upload token (`CODECOV_TOKEN`) for authentication. Tokenless uploads are primarily limited to forks creating pull requests on public repositories.
Fix: Obtain a Codecov upload token from your repository settings on Codecov.io and set it as the `CODECOV_TOKEN` environment variable or pass it directly via the `-t` or `--token` CLI argument.
breaking Older versions of Codecov CI integration tools (e.g., GitHub Action, CircleCI Orb, Bitrise Step) that did not internally use `codecov-cli` are no longer supported. Users leveraging these integrations must update to version 4.0.0 or later of their respective CI uploader to benefit from `codecov-cli`'s features and continued support.
Fix: Update your CI/CD workflow configurations to use version 4.0.0 or newer of the Codecov GitHub Action, CircleCI Orb, or Bitrise Step.
gotcha The Codecov CLI expects to be executed within a checked-out Git repository and requires `git` to be installed on the machine where it runs to correctly infer repository metadata.
Fix: Ensure your CI environment or local machine has Git installed and that `codecovcli` is run from the root of your Git repository.

Install

pip install codecov-cli Install latest version

Quickstart

This quickstart demonstrates how to run the `codecovcli upload-process` command using Python's `subprocess` module. It emphasizes the critical role of the `CODECOV_TOKEN` environment variable for authentication and shows how to specify a coverage report file. Ensure you have a `coverage.xml` (or similar) file generated by your test runner.

import os
import subprocess

# Ensure you have a CODECOV_TOKEN set as an environment variable or replace 'os.environ.get(...)'
# with your actual token for testing purposes.
# For CI/CD, it's highly recommended to use environment variables.
codecov_token = os.environ.get('CODECOV_TOKEN', 'your_codecov_upload_token_here')

if not codecov_token or codecov_token == 'your_codecov_upload_token_here':
    print("Warning: CODECOV_TOKEN not set or using placeholder. Uploads may fail.")

# Example: Running a simplified upload process (requires a coverage report file, e.g., coverage.xml)
# In a real scenario, you would generate a coverage report first (e.g., with pytest-cov).
# For this example, we assume 'coverage.xml' exists in the current directory.
# To make this runnable, let's create a dummy coverage.xml if it doesn't exist.
if not os.path.exists('coverage.xml'):
    with open('coverage.xml', 'w') as f:
        f.write('<coverage><packages><package name="my_module"><file name="my_module.py"></file></package></packages></coverage>')
    print("Created dummy coverage.xml for quickstart.")

command = [
    'codecovcli',
    'upload-process',
    '--token',
    codecov_token,
    '-f', 'coverage.xml' # Specify a coverage report file
]

try:
    print(f"Running command: {' '.join(command)}")
    result = subprocess.run(command, check=True, capture_output=True, text=True)
    print("Codecov CLI output:")
    print(result.stdout)
    if result.stderr:
        print("Codecov CLI errors:")
        print(result.stderr)
    print("Codecov CLI command executed successfully.")
except subprocess.CalledProcessError as e:
    print(f"Error running Codecov CLI: {e}")
    print(f"Stdout: {e.stdout}")
    print(f"Stderr: {e.stderr}")
    print("Please ensure 'codecov-cli' is installed and CODECOV_TOKEN is correctly configured.")
except FileNotFoundError:
    print("Error: 'codecovcli' command not found. Is codecov-cli installed and in your PATH?")

view raw JSON →