### Install and Upload using Codecov CLI (Method 2)

Source: https://github.com/codecov/codecov-cli/blob/main/README.md

Install the Codecov CLI using pip and then use the upload-process command, which is a wrapper for the individual upload steps.

```bash
pip install codecov-cli
codecovcli upload-process
```

--------------------------------

### Codecov CLI create-commit command examples

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/api-reference/commands.md

Examples demonstrating how to use the 'create-commit' command with minimal configuration, manual specification of parameters, and including parent commit information.

```bash
# Minimal usage with auto-detection
codecovcli create-commit

```

```bash
# Manual specification
codecovcli create-commit \
  --commit-sha abc123def456... \
  --branch main \
  --slug codecov/codecov-cli \
  --token $CODECOV_TOKEN \
  --git-service github

```

```bash
# With parent commit
codecovcli create-commit \
  --commit-sha abc123def456... \
  --parent-sha 789def123abc... \
  --pr 42

```

--------------------------------

### Install and Upload using Codecov CLI (Method 1)

Source: https://github.com/codecov/codecov-cli/blob/main/README.md

Install the Codecov CLI using pip and then use the create-commit, create-report, and do-upload commands to process and upload coverage.

```bash
pip install codecov-cli
codecovcli create-commit
codecovcli create-report
codecovcli do-upload
```

--------------------------------

### Codecov YAML Configuration Example

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/README.md

Example of a codecov.yml file showing how to set the default upload token and enable manual notification triggers.

```yaml
codecov:
  token: your_token         # Default token for commands
  notify:
    manual_trigger: true    # Require explicit notification
```

--------------------------------

### Example codecov.yml Configuration

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/configuration.md

An example of a complete codecov.yml file demonstrating how to set the upload token, require certain conditions for changes, and enable manual notification triggers.

```yaml
codecov:
  token: your_token_here
  require:
    changes: true
    patch: true
    project: true
  notify:
    manual_trigger: true
    
cli:
  # CLI-specific settings
```

--------------------------------

### Install Python Dependencies

Source: https://github.com/codecov/codecov-cli/blob/main/README.md

Installs project dependencies using pip and sets up the project in editable mode.

```bash
pip install -r requirements.txt
python -m pip install --editable .
```

--------------------------------

### Get Fallback Value Example

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/api-reference/ci-adapters.md

Demonstrates how to retrieve fallback values like branch or build code using the get_fallback_value method from a CI adapter. Ensure you have obtained a CI adapter instance first.

```python
from codecov_cli.helpers.ci_adapters import get_ci_adapter
from codecov_cli.fallbacks import FallbackFieldEnum

adapter = get_ci_adapter(None)
if adapter:
    branch = adapter.get_fallback_value(FallbackFieldEnum.branch)
    build_code = adapter.get_fallback_value(FallbackFieldEnum.build_code)
```

--------------------------------

### Codecov CLI Example Usage

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/api-reference/main.md

Demonstrates various ways to invoke the Codecov CLI with different global options. These examples show how to enable auto-detection, specify configuration files, target enterprise instances, and disable telemetry.

```bash
# Run with auto-detection from GitHub Actions
codecovcli --auto-load-params-from github-actions create-commit

# Run with custom codecov.yml and verbose logging
codecovcli --codecov-yml-path ./my-codecov.yml -v do-upload

# Run against enterprise instance
codecovcli --enterprise-url https://codecov.example.com do-upload

# Disable telemetry
codecovcli --disable-telem upload-process
```

--------------------------------

### Codecov CLI empty-upload Command Usage

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/api-reference/commands.md

Demonstrates basic and advanced usage of the empty-upload command. Use the first example for automatic detection of changed files. The second example shows how to force passing checks regardless of file changes. The third example illustrates explicit parameter usage for commit SHA, slug, and token.

```bash
codecovcli empty-upload
```

```bash
codecovcli empty-upload --force
```

```bash
codecovcli empty-upload \
  --commit-sha abc123def456... \
  --slug codecov/codecov-cli \
  --token $CODECOV_TOKEN
```

--------------------------------

### Example CIAdapterBase detect() Implementation

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/api-reference/ci-adapters.md

This snippet shows a basic implementation of the `detect` method for a CI adapter. It checks for the presence of the GITHUB_ACTIONS environment variable to determine if the current environment is GitHub Actions.

```python
def detect(self) -> bool:
    return "GITHUB_ACTIONS" in os.environ
```

--------------------------------

### Codecov CLI pr-base-picking Example Usage

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/api-reference/commands.md

Demonstrates minimal and explicit ways to use the `pr-base-picking` command. Ensure you provide the necessary parameters like `--base-sha` for accurate association.

```bash
# Minimal
codecovcli pr-base-picking

# Explicit
codecovcli pr-base-picking \
  --base-sha abc123def456... \
  --pr 42 \
  --slug codecov/codecov-cli \
  --token $CODECOV_TOKEN
```

--------------------------------

### Upload Completion Logic Example

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/api-reference/services.md

Demonstrates how to call the upload_completion_logic function to trigger post-upload notifications. Ensure the necessary parameters like commit SHA, slug, and token are provided.

```python
from codecov_cli.services.upload_completion import upload_completion_logic

result = upload_completion_logic(
    commit_sha="abc123...",
    slug="codecov/codecov-cli",
    token="token_xyz",
    git_service="github",
)
```

--------------------------------

### Create Report Logic Example

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/api-reference/services.md

Demonstrates how to use the `create_report_logic` function to create an empty report in Codecov. Ensure all required parameters are provided.

```python
from codecov_cli.services.report import create_report_logic

result = create_report_logic(
    commit_sha="abc123def456...",
    code="default",
    slug="codecov/codecov-cli",
    service="github",
    token="token_xyz",
    enterprise_url="https://api.codecov.io",
    pull_request_number=42,
)
```

--------------------------------

### Install CodecovCLI using PIP

Source: https://github.com/codecov/codecov-cli/blob/main/README.md

Install the latest version of Codecov-cli using pip. If using pyenv, you may need to run 'pyenv rehash'.

```bash
pip install codecov-cli
```

--------------------------------

### Get List of Available CI Providers

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/api-reference/ci-adapters.md

Retrieves a list of all available CI provider adapters and prints their service names.

```python
from codecov_cli.helpers.ci_adapters import get_ci_providers_list

providers = get_ci_providers_list()
for provider in providers:
    print(provider.get_service_name())
```

--------------------------------

### Branch Resolution Fallback Chain Example

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/api-reference/ci-adapters.md

Illustrates the order in which the CLI resolves parameters like the branch, checking command-line flags, CI adapters, Git system, environment variables, and finally default values.

```python
# User provides via flag
branch = "--branch main"  # ← Uses this

# Or CI provides
branch = os.environ.get("GITHUB_REF")  # ← Uses this

# Or git provides
branch = versioning_system.get_fallback_value(FallbackFieldEnum.branch)  # ← Uses this

# Falls back to None if not found
```

--------------------------------

### Basic Codecov CLI Upload

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/api-reference/commands.md

Use this command for a basic upload with automatic detection of coverage files. Ensure the Codecov CLI is installed and configured.

```bash
codecovcli do-upload
```

--------------------------------

### Add Prefix to Network File Paths

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/configuration.md

Add a prefix to network file paths, for example, 'app/'.

```bash
--network-prefix TEXT
```

--------------------------------

### HTTP Mocking with Responses Library

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/architecture.md

Use the 'responses' library to mock HTTP requests and responses within tests. This example shows mocking a POST request.

```python
import responses

@responses.activate
def test_upload():
    responses.add(responses.POST, url, json={"url": "..."}, status=200)
    result = send_post_request(url)
    # Assertions
```

--------------------------------

### Update Git Submodules

Source: https://github.com/codecov/codecov-cli/blob/main/README.md

Run this command to pull necessary git submodules before installing dependencies.

```bash
git submodule update --init
```

--------------------------------

### Get Authorization Header or Raise Exception

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/api-reference/helpers.md

Builds an HTTP Authorization header from a token, raising a ClickException if the token is missing. This is useful for commands that strictly require an authentication token.

```python
from codecov_cli.helpers.request import get_token_header_or_fail

try:
    headers = get_token_header_or_fail(token)
except click.ClickException as e:
    print(f"Error: {e.message}")
```

--------------------------------

### Filter Network Files by Path Prefix

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/configuration.md

Filter network files based on a path prefix, for example, 'src/'.

```bash
--network-filter TEXT
```

--------------------------------

### Codecov CLI Version Information

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/api-reference/main.md

Retrieves the CLI version from the installed package metadata. This is the version displayed when running `codecovcli --version`.

```python
from codecov_cli import __version__
# __version__ is automatically loaded from pyproject.toml version field
# Current version: 11.2.8
```

--------------------------------

### Minimal Manual Configuration

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/configuration.md

Use this configuration when manually providing all necessary parameters like commit SHA, slug, token, and Git service.

```bash
codecovcli create-commit \
  --commit-sha abc123def456... \
  --slug owner/repo \
  --token $CODECOV_TOKEN \
  --git-service github
```

--------------------------------

### Send GET Request with Retries

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/api-reference/helpers.md

This function sends GET requests and includes retry logic for robustness against transient network failures. It allows for specifying headers and query parameters.

```python
from codecov_cli.helpers.request import send_get_request

result = send_get_request(
    url="https://api.codecov.io/upload/github/owner/repo/commits/abc123",
    headers={"Authorization": "token xyz"},
)
```

--------------------------------

### Example 400 Bad Request Response

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/errors.md

This JSON structure represents an example of a 400 Bad Request error response from the Codecov API, typically indicating invalid parameters in the request.

```json
{
  "error": {
    "code": "HTTP Error 400",
    "description": "Invalid commit SHA format",
    "params": {}
  }
}
```

--------------------------------

### cli

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/api-reference/main.md

The root Click group that initializes global options and context for all commands. It handles configuration loading, CI detection, and sets up the necessary context for subcommands.

```APIDOC
## cli

### Description
Root Click group that initializes global options and context for all commands.

### Method
N/A (CLI command)

### Endpoint
N/A (CLI command)

### Parameters
#### Global Options
- **auto_load_params_from** (Optional[str]) - No - None - Auto-detect CI provider (one of supported CI names)
- **codecov_yml_path** (pathlib.Path) - No - None - Path to codecov.yml configuration file
- **enterprise_url** (str) - No - None - Enterprise Codecov URL (overrides default)
- **verbose** (bool) - No - False - Enable verbose debug logging
- **disable_telem** (bool) - No - False - Disable telemetry data sending to Codecov

### Subcommands
- `do-upload` / `upload`: Upload coverage files to Codecov
- `create-commit`: Create commit metadata in Codecov
- `create-report`: Create empty report in Codecov
- `pr-base-picking` / `base-picking`: Explicitly define PR base commit
- `empty-upload`: Upload when no coverage changes apply
- `upload-coverage`: Upload coverage data
- `upload-process`: Combined create-commit, create-report, do-upload
- `send-notifications`: Trigger upload completion notifications
- `process-test-results`: Process test result files
- `label-analysis` (deprecated): Analyze test labels
- `static-analysis` (deprecated): Static analysis
- `create-report-results` (deprecated): Create report results
- `get-report-results` (deprecated): Get report results

### Example Usage:
```bash
# Run with auto-detection from GitHub Actions
codecovcli --auto-load-params-from github-actions create-commit

# Run with custom codecov.yml and verbose logging
codecovcli --codecov-yml-path ./my-codecov.yml -v do-upload

# Run against enterprise instance
codecovcli --enterprise-url https://codecov.example.com do-upload

# Disable telemetry
codecovcli --disable-telem upload-process
```
```

--------------------------------

### run

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/api-reference/main.md

The entry point function for the CLI application. It invokes the main 'cli' group with an initial context.

```APIDOC
## run

### Description
Entry point function for the CLI application. Invokes the main `cli` group with an empty context object dictionary that will be populated by the `cli()` function.

### Method
N/A (Python function)

### Endpoint
N/A (Python function)

### Called by:
Console script entry point defined in pyproject.toml:
- `codecov`
- `codecovcli`
- `codecov-cli`

### Example Usage:
```python
from codecov_cli.main import run

# In another Python module
if __name__ == "__main__":
    run()
```
```

--------------------------------

### Execute Upload Logic

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/api-reference/services.md

This snippet demonstrates how to call the main upload logic function. Ensure you have the necessary configurations and dependencies like VersioningSystemInterface and CIAdapterBase.

```python
from codecov_cli.services.upload import do_upload_logic

result = do_upload_logic(
    cli_config={},
    versioning_system=vcs,
    ci_adapter=ci,
    commit_sha="abc123...",
    slug="codecov/codecov-cli",
    token="token_xyz",
    report_type=ReportType.COVERAGE,
    files_search_root_folder=Path("."),
)
```

--------------------------------

### Plugin System Execution

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/architecture.md

Dynamically selects and runs preparation plugins based on CLI configuration and specified plugin names. Used for pre-processing coverage data.

```python
plugins = select_preparation_plugins(cli_config, plugin_names, plugin_config)
for plugin in plugins:
    plugin.run_preparation()  # Pre-processes coverage data
```

--------------------------------

### CIAdapterBase Methods

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/api-reference/ci-adapters.md

This section details the methods available in the abstract base class `CIAdapterBase` that concrete CI adapters must implement. These methods are used to detect the CI environment and extract relevant information such as branch, commit SHA, and build details.

```APIDOC
## CIAdapterBase

### Abstract Methods (Must be Implemented)

#### detect

**Returns:** bool

**Description:** Detects if this CI provider is currently being used. This method is called by `get_ci_adapter()` to identify the active CI provider.

#### _get_branch

**Returns:** string

**Description:** Extracts the branch name from the CI environment variables.

**Example:** "main", "develop", "feature/my-feature"

#### _get_commit_sha

**Returns:** string

**Description:** Extracts the commit SHA from the CI environment variables.

**Example:** "abc123def456..." (40 hex characters)

#### _get_slug

**Returns:** string

**Description:** Extracts the repository slug (owner/repo) from the CI environment variables.

**Example:** "codecov/codecov-cli"

#### _get_service

**Returns:** string

**Description:** Gets the CI service name for Codecov UI display.

**Common Values:** "github-actions", "gitlab-ci", "circleci", etc.

#### _get_build_url

**Returns:** string

**Description:** Extracts the CI build or job URL.

**Example:** "https://github.com/codecov/codecov-cli/actions/runs/123456"

#### _get_build_code

**Returns:** string

**Description:** Extracts the build or job number.

**Example:** "123", "run-456"

#### _get_job_code

**Returns:** string

**Description:** Extracts the specific job identifier within a build.

**Example:** "job-1", "step-5"

#### _get_pull_request_number

**Returns:** string

**Description:** Extracts the PR/MR number if applicable.

**Example:** "42", "123" (or None if not in a PR)

#### get_service_name

**Returns:** string

**Description:** Provides a user-friendly CI service name, typically used for parameters like `--auto-load-params-from`.

**Example:** "github-actions", "gitlab-ci", "circleci"
```

--------------------------------

### Get Authorization Header

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/api-reference/helpers.md

Constructs an HTTP Authorization header from a provided token. Returns None if the token is not provided.

```python
from codecov_cli.helpers.request import get_token_header

headers = get_token_header("token_xyz123")
# Returns {"Authorization": "token token_xyz123"}

headers = get_token_header(None)
# Returns None
```

--------------------------------

### Enable Verbose Debug Logging

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/configuration.md

Activate verbose logging to get detailed debug information during CLI execution.

```bash
-v, --verbose
```

--------------------------------

### Download and Execute Codecov CLI Binary (Linux)

Source: https://github.com/codecov/codecov-cli/blob/main/README.md

Download the latest Linux binary for Codecov CLI, make it executable, and run the help command.

```bash
curl -Os https://cli.codecov.io/latest/linux/codecov
sudo chmod +x codecov
./codecov --help
```

--------------------------------

### send_get_request

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/api-reference/helpers.md

Sends a GET request with retry logic. It handles connection errors, timeouts, and 5xx status codes with exponential backoff.

```APIDOC
## send_get_request

### Description
Sends a GET request with retry logic. Handles connection errors, timeouts, and 5xx status codes with exponential backoff.

### Method
GET

### Endpoint
[Full URL to GET]

### Parameters
#### Path Parameters
None

#### Query Parameters
- **params** (dict) - Optional - Query parameters

#### Request Body
None

### Request Example
```python
from codecov_cli.helpers.request import send_get_request

result = send_get_request(
    url="https://api.codecov.io/upload/github/owner/repo/commits/abc123",
    headers={"Authorization": "token xyz"},
)
```

### Response
#### Success Response (200)
- **RequestResult** (object) - Contains status, error, warnings, text

#### Response Example
```json
{
  "status": "success",
  "error": null,
  "warnings": [],
  "text": "Response text"
}
```
```

--------------------------------

### Show Help and Exit

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/configuration.md

Display the help message for the Codecov CLI and then exit.

```bash
-h, --help
```

--------------------------------

### Specify Build URL

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/configuration.md

Provide the URL to the build in the CI system. The CLI can fall back to the CI adapter.

```bash
--build-url TEXT
```

--------------------------------

### Upload Process with Explicit Parameters

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/api-reference/commands.md

Run the upload process with specific parameters for commit SHA, repository slug, and Git service. This provides fine-grained control over the operation.

```bash
codecovcli upload-process \
  --commit-sha abc123def456... \
  --slug codecov/codecov-cli \
  --token $CODECOV_TOKEN \
  --git-service github
```

--------------------------------

### Codecov CLI Usage Help

Source: https://github.com/codecov/codecov-cli/blob/main/README.md

Display the main help message for the Codecov CLI, showing available commands and general options.

```bash
Usage: codecovcli [OPTIONS] COMMAND [ARGS]...
```

--------------------------------

### Uploading with Environment Variables

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/api-reference/commands.md

Include specific environment variables with your upload using the --env option. This can be used for tracking build or deployment information.

```bash
codecovcli do-upload \
  --env VAR1 VAR2 VAR3
```

--------------------------------

### Tag Release

Source: https://github.com/codecov/codecov-cli/blob/main/README.md

Run this command from the Makefile to tag a new release. Ensure the version number matches the specified regex.

```bash
$ make tag.release version=v<VERSION_NUM>
```

--------------------------------

### Advanced File Processing

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/configuration.md

Customize file processing with options like specifying directories, exclusions, custom files, plugins, and disabling file fixes. This configuration is useful for complex coverage reporting setups.

```yaml
cli:
  # Plugin configuration can go here
```

```bash
codecovcli do-upload \
  --dir ./coverage \
  --exclude ./coverage/excluded \
  --file ./custom-coverage.xml \
  --plugin gcov pycoverage \
  --gcov-executable /usr/bin/gcov-11 \
  --flag unit --flag integration \
  --disable-file-fixes
```

--------------------------------

### Use Legacy Uploader Endpoint

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/configuration.md

Enable the use of the legacy upload endpoint for compatibility.

```bash
--legacy, --use-legacy-uploader
```

--------------------------------

### Show Version and Exit

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/configuration.md

Display the current version of the Codecov CLI and then exit.

```bash
--version
```

--------------------------------

### Specify Coverage Format Plugins

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/configuration.md

Select coverage format plugins to run. Defaults to xcode, gcov, pycoverage. Available options are xcode, gcov, pycoverage.

```bash
--plugin TEXT
```

--------------------------------

### Enterprise Instance Configuration

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/configuration.md

Configure the CLI to communicate with a self-hosted Codecov enterprise instance by specifying the `--enterprise-url`.

```bash
codecovcli --enterprise-url https://codecov.example.com do-upload \
  --token $CODECOV_TOKEN \
  --slug owner/repo
```

--------------------------------

### Check Environment Parameters

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/errors.md

List detected parameters by combining auto-loading with verbose output and filtering for debug information. This helps in verifying environment variable configurations.

```bash
# List detected values
codecovcli --auto-load-params-from github-actions -v create-commit 2>&1 | grep -i "debug"
```

--------------------------------

### CI Auto-Detection (GitHub Actions)

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/configuration.md

Leverage CI environment variables for token and auto-detection of other parameters. Alternatively, explicitly specify the CI adapter.

```bash
# Token from environment, all else auto-detected
CODECOV_TOKEN=xyz codecovcli do-upload
```

```bash
# Or with explicit flag
codecovcli --auto-load-params-from github-actions do-upload
```

--------------------------------

### PreparationPluginInterface Definition

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/types.md

Abstract base class for plugins that perform preparation tasks, such as converting coverage data formats. Implementations are responsible for the 'run_preparation' method.

```python
class PreparationPluginInterface(object):
    def run_preparation(self) -> None:
        pass
```

--------------------------------

### Create Custom CI Adapter

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/api-reference/ci-adapters.md

Defines a custom CI adapter by inheriting from `CIAdapterBase` and implementing detection and data retrieval methods for a new CI platform.

```python
from codecov_cli.helpers.ci_adapters.base import CIAdapterBase

class MyCustomCIAdapter(CIAdapterBase):
    def detect(self) -> bool:
        return "MY_CI_ENV" in os.environ
    
    def get_service_name(self) -> str:
        return "my-custom-ci"
    
    def _get_branch(self) -> str:
        return os.environ.get("MY_CI_BRANCH")
    
    def _get_commit_sha(self) -> str:
        return os.environ.get("MY_CI_COMMIT")
    
    def _get_slug(self) -> str:
        return os.environ.get("MY_CI_REPO_SLUG")
    
    def _get_service(self) -> str:
        return "my-custom-ci"
    
    def _get_build_url(self) -> str:
        return os.environ.get("MY_CI_BUILD_URL")
    
    def _get_build_code(self) -> str:
        return os.environ.get("MY_CI_BUILD_ID")
    
    def _get_job_code(self) -> str:
        return os.environ.get("MY_CI_JOB_ID")
    
    def _get_pull_request_number(self) -> str:
        return os.environ.get("MY_CI_PR_NUMBER")
```

--------------------------------

### Command Level Error Handling Strategy

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/architecture.md

Demonstrates a 'fail fast' strategy for critical operations at the command level, where exceptions like ClickException are raised immediately upon failure.

```python
# Pattern: Fail fast on critical operations
create_commit_logic(...)  # May raise ClickException
create_report_logic(...)  # May raise ClickException
do_upload_logic(...)      # May raise ClickException
```

--------------------------------

### Specify Git Service Provider

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/configuration.md

Define the Git service provider. Options include github, gitlab, bitbucket, github_enterprise, gitlab_enterprise, and bitbucket_server. The CLI can fall back to the CI adapter or git remote URL.

```bash
--git-service TEXT
```

--------------------------------

### Register Custom CI Adapter

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/api-reference/ci-adapters.md

Registers a newly created custom CI adapter by adding an instance of it to the list of providers in the `__init__.py` file.

```python
from codecov_cli.helpers.ci_adapters.my_custom import MyCustomCIAdapter

def get_ci_providers_list():
    return [
        # ... existing providers ...
        MyCustomCIAdapter(),
    ]
```

--------------------------------

### Auto-detect CI Provider and Upload

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/README.md

Use this command to automatically detect the CI provider and upload coverage data. Refer to the CI adapters documentation for supported providers.

```bash
codecovcli --auto-load-params-from PROVIDER do-upload
```

--------------------------------

### Process Upload with Codecov CLI

Source: https://github.com/codecov/codecov-cli/blob/main/README.md

A convenient wrapper command that executes `create-commit`, `create-report`, and `do-upload` sequentially. Use this to simplify the upload process to Codecov.

```bash
codecovcli upload-process --commit-sha <commit-sha> --slug <owner/repo> --token <token> --git-service <git-provider>
```

--------------------------------

### Codecov CLI Upload with Explicit Parameters

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/README.md

Provide specific details for the upload, such as commit SHA, repository slug, token, and Git service.

```bash
codecovcli do-upload \
  --commit-sha abc123... \
  --slug owner/repo \
  --token $CODECOV_TOKEN \
  --git-service github
```

--------------------------------

### create-report

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/api-reference/commands.md

Creates an empty report in Codecov with initial metadata before uploading coverage data. This command is useful for setting up a report entry in Codecov prior to sending coverage files.

```APIDOC
## create-report

### Description
Creates an empty report in Codecov with initial metadata before uploading coverage data.

### Method
CLI Command

### Endpoint
N/A (CLI Command)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### CLI Arguments
- **commit_sha** (str) - Required - Commit SHA (40 character hex)
- **code** (str) - Optional - Report code/identifier for this report. Defaults to "default".
- **slug** (str) - Required - Repository slug (owner/repo)
- **git_service** (str) - Required - Git service provider name
- **token** (str) - Required - Codecov upload token
- **fail_on_error** (bool) - Optional - Exit with non-zero code on error. Defaults to False.
- **pull_request_number** (int) - Optional - PR/MR number if applicable. Defaults to None.

### Request Example
```bash
codecovcli create-report \
  --commit-sha abc123def456... \
  --slug codecov/codecov-cli \
  --git-service github \
  --token $CODECOV_TOKEN

# With PR association
codecovcli create-report \
  --commit-sha abc123def456... \
  --pr 42 \
  --slug codecov/codecov-cli \
  --git-service github \
  --token $CODECOV_TOKEN
```

### Response
#### Success Response
None (sends result via logging)

#### Response Example
None

### Errors:
- HTTP 400+: Invalid commit or repository
- Missing required parameters: Click validation error
```

--------------------------------

### Send Upload Data with UploadSender

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/api-reference/services.md

Demonstrates how to instantiate UploadSender and use the send_upload_data method to send collected upload data to Codecov. Requires necessary parameters like upload data, commit SHA, token, slug, and report code.

```python
from codecov_cli.services.upload.upload_sender import UploadSender

sender = UploadSender()
result = sender.send_upload_data(
    upload_data=upload_collection_result,
    commit_sha="abc123...",
    token="token_xyz",
    slug="codecov/codecov-cli",
    report_code="default",
    report_type=ReportType.COVERAGE,
)
```

--------------------------------

### Complete Upload Process with Codecov CLI

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/api-reference/commands.md

Execute the full upload process, including commit creation, report generation, and uploading, in a single command. This simplifies the CI/CD pipeline.

```bash
codecovcli upload-process
```

--------------------------------

### Manually Provide Upload Token

Source: https://github.com/codecov/codecov-cli/blob/main/README.md

When not using environment variables, pass the upload token manually to each command using the -t option.

```bash
codecovcli upload-process -t {$CODECOV_TOKEN}
```

--------------------------------

### Specify Codecov YAML Path

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/configuration.md

Provide the path to the codecov.yml configuration file.

```bash
--codecov-yml-path PATH
```

--------------------------------

### Perform a Dry Run Upload

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/errors.md

Utilize the --dry-run flag to simulate an upload without actually sending any data. This allows you to preview what would be uploaded.

```bash
codecovcli do-upload --dry-run
# Shows what would be uploaded without sending data
```

--------------------------------

### Initialize UploadCollector

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/api-reference/services.md

Instantiates the UploadCollector service with necessary dependencies and configuration. Ensure all required interfaces and configuration parameters are provided.

```python
from codecov_cli.services.upload.upload_collector import UploadCollector

collector = UploadCollector(
    preparation_plugins=plugins,
    network_finder=network_finder,
    file_finder=file_finder,
    plugin_config={"project_root": Path(".")},
)
```

--------------------------------

### Specify Build/Job Number

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/configuration.md

Set the build or job number for the upload. The CLI can fall back to the CI adapter.

```bash
-b TEXT, --build TEXT, --build-code TEXT
```

--------------------------------

### Codecov CLI Upload with File Specification and Exclusions

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/README.md

Specify multiple coverage report files to upload and define directories to exclude from the upload process.

```bash
codecovcli do-upload \
  -f coverage.xml \
  -f test-results.json \
  --exclude ./node_modules
```

--------------------------------

### Specify gcov Executable Path

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/configuration.md

Provide the path to the gcov executable. Defaults to 'gcov'.

```bash
--gcov-executable TEXT
```

--------------------------------

### File Discovery Optimization

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/architecture.md

Optimizes file discovery by skipping large directories like 'node_modules' and '.git' and using efficient filename filtering with a regex pattern. This function utilizes os.walk() with early directory pruning.

```python
search_files(
    folder,
    folders_to_ignore=["node_modules", ".git", ...],  # Skip large dirs
    filename_include_regex=coverage_pattern,          # Efficient filtering
)
```

--------------------------------

### Manually Select CI Adapter

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/api-reference/ci-adapters.md

Selects a specific CI provider adapter or auto-detects if no provider is specified. It checks if the adapter is detected and retrieves fallback values like the branch.

```python
from codecov_cli.helpers.ci_adapters import get_ci_adapter

# Auto-detect
adapter = get_ci_adapter(None)

# Explicit provider
adapter = get_ci_adapter("github-actions")

if adapter and adapter.detect():
    branch = adapter.get_fallback_value(FallbackFieldEnum.branch)
```

--------------------------------

### Specify Job Code

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/configuration.md

Provide a job identifier. The CLI can fall back to the CI adapter.

```bash
--job-code TEXT
```

--------------------------------

### Create Report Command

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/api-reference/commands.md

Use this command to create an empty report on Codecov. Ensure you provide the commit SHA, repository slug, Git service, and your Codecov upload token. The token can be set as an environment variable.

```bash
codecovcli create-report \
  --commit-sha abc123def456... \
  --slug codecov/codecov-cli \
  --git-service github \
  --token $CODECOV_TOKEN
```

```bash
codecovcli create-report \
  --commit-sha abc123def456... \
  --pr 42 \
  --slug codecov/codecov-cli \
  --git-service github \
  --token $CODECOV_TOKEN
```

--------------------------------

### Include Environment Variables

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/configuration.md

Specify environment variable names to include with the upload. Their values will be read from the environment. This option can be used multiple times.

```bash
-e TEXT, --env TEXT, --env-var TEXT
```

--------------------------------

### Minimal Codecov CLI Upload

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/README.md

Use this command for a basic upload. It automatically detects commit, branch, and token from the CI environment.

```bash
codecovcli do-upload
# Auto-detects commit, branch, token from CI environment
```

--------------------------------

### Branch Parameter Resolution Logic

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/architecture.md

Illustrates the order of precedence for resolving the branch parameter when the 'codecovcli do-upload' command is executed. It shows how flags, CI environment variables, and git versioning are checked.

```bash
User runs: codecovcli do-upload -B main
           
           
User runs: codecovcli do-upload
           
           
           
           
           
           
User runs: codecovcli do-upload (in non-CI environment)
           
           
           
           
User runs: codecovcli do-upload (no .git, no CI)
           
           
           
```

--------------------------------

### Auto-detect CI Provider Option

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/configuration.md

Use this option to automatically detect the CI provider. Supported options include github, gitlab, and bitbucket.

```bash
--auto-load-params-from TEXT
```

--------------------------------

### Specify Root Folder for Coverage File Search

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/configuration.md

Set the root folder where the CLI should search for coverage files. Defaults to the current directory.

```bash
-s PATH, --dir PATH, --coverage-files-search-root-folder PATH
```

--------------------------------

### Specify Xcode Project Path for Swift Coverage

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/configuration.md

Set the path to the Xcode project file for generating Swift coverage reports.

```bash
--swift-project TEXT
```

--------------------------------

### Create Commit Metadata with Codecov CLI

Source: https://github.com/codecov/codecov-cli/blob/main/README.md

Use this command to save commit metadata to Codecov. It is essential to run this only once per commit. Required options include commit SHA, owner/repo slug, upload token, and git service provider.

```bash
codecovcli create-commit --commit-sha <commit-sha> --slug <owner/repo> --token <token> --git-service <git-provider>
```

--------------------------------

### Handle No Reports Found

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/errors.md

Configure the CLI to continue without error if no coverage reports are found by using the --handle-no-reports-found flag. This can be useful in certain CI/CD pipeline scenarios.

```bash
codecovcli do-upload --handle-no-reports-found
```

--------------------------------

### Specify Explicit Coverage Files

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/configuration.md

List explicit files to upload. These are added to automatically found files unless --disable-search is used. Can be specified multiple times.

```bash
-f PATH, --file PATH, --coverage-files-search-direct-file PATH
```

--------------------------------

### Verify Repository Slug

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/errors.md

Ensure the repository slug provided with the -r flag is correct, in the format 'owner/repo'. This is crucial for associating coverage with the right project.

```bash
codecovcli do-upload -r owner/repo
```

--------------------------------

### Enable Verbose Logging

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/errors.md

Use the -v flag to enable DEBUG level logs for detailed information during the upload process. This is useful for diagnosing issues.

```bash
codecovcli -v do-upload
# Outputs DEBUG level logs with detailed information
```

--------------------------------

### Adapter Pattern for CI Integration

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/architecture.md

Retrieves and detects the appropriate CI adapter for a given provider. Extracts CI-specific information like the slug using a unified interface.

```python
adapter = get_ci_adapter(provider_name)
if adapter and adapter.detect():
    slug = adapter.get_fallback_value(FallbackFieldEnum.slug)
```

--------------------------------

### Programmatic Usage of Codecov CLI Services

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/README.md

Demonstrates how to use core Codecov CLI services directly for creating commits, reports, and uploads. This is useful for integrating Codecov's functionality into custom workflows or scripts.

```python
from codecov_cli.services.commit import create_commit_logic
from codecov_cli.services.report import create_report_logic
from codecov_cli.services.upload import do_upload_logic

# Use service functions directly
result = create_commit_logic(
    commit_sha="abc123...",
    branch="main",
    slug="owner/repo",
    token="token_xyz",
    service="github",
)
```

--------------------------------

### get_token_header_or_fail

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/api-reference/helpers.md

Builds an authorization header from a provided token, raising a ClickException if the token is None. Used for commands that require a token.

```APIDOC
## get_token_header_or_fail

### Description
Builds an authorization header from a provided token. Raises a ClickException if the token is None. Used for commands that require a token.

### Signature
```python
def get_token_header_or_fail(token: Optional[str]) -> dict
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Example Usage
```python
from codecov_cli.helpers.request import get_token_header_or_fail
import click

try:
    headers = get_token_header_or_fail(token)
except click.ClickException as e:
    print(f"Error: {e.message}")
```

### Raises
- **ClickException** - If the provided token is None.
```

--------------------------------

### Codecov CLI Run Function

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/api-reference/main.md

The entry point function for the CLI application. It invokes the main `cli` group with an initial empty context object.

```python
from codecov_cli.main import run

# In another Python module
if __name__ == "__main__":
    run()
```

--------------------------------

### Create Empty Report with Codecov CLI

Source: https://github.com/codecov/codecov-cli/blob/main/README.md

Generates an empty report in Codecov with initial data such as the report name and commit. This command is used to set up a report before uploading coverage data.

```bash
codecovcli create-report --commit-sha <commit-sha> --slug <owner/repo> --token <token> --git-service <git-provider>
```

--------------------------------

### Upload Logic

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/README.md

Initiates the upload process to Codecov. This function requires commit details, repository slug, and token. Numerous additional parameters exist for file discovery and plugin configuration.

```python
from codecov_cli.services.upload import do_upload_logic

result = do_upload_logic(
    commit_sha="abc123...",
    slug="owner/repo",
    token="token_xyz",
    # ... many more parameters for file discovery, plugins, etc.
)
```

--------------------------------

### Fail on Error

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/configuration.md

Ensure the CLI exits with a non-zero status code if any errors occur during execution.

```bash
-Z, --fail-on-error
```

--------------------------------

### Specify Network Root Folder

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/configuration.md

Set the root folder for network section file paths. Defaults to the current directory.

```bash
--network-root-folder PATH
```

--------------------------------

### Specify Report Type

Source: https://github.com/codecov/codecov-cli/blob/main/_autodocs/configuration.md

Define the type of report to upload. Options are 'coverage' (default) or 'test_results' for JUnit/xUnit XML files.

```bash
--report-type [coverage|test_results]
```