github/copilot-sdk · error · RuntimeError

No CLI version pinned. This is a development install — set…

Error message

No CLI version pinned. This is a development install — set COPILOT_CLI_PATH or install a published wheel.

What it means

download_cli requires a pinned CLI version (CLI_VERSION or the version argument). In development installs where no version is set, the library refuses to guess and raises this error telling you to point COPILOT_CLI_PATH at an existing binary or install a published wheel.

Solutions

Install a published wheel from PyPI instead of the source tree.
Set the COPILOT_CLI_PATH environment variable to an existing Copilot CLI binary.
Pass an explicit version to download_cli(version=...).
Rebuild the package so the version stamping step populates CLI_VERSION.

Example fix

# before
$ python -m copilot   # source install, no pin
# after
$ export COPILOT_CLI_PATH=/usr/local/bin/copilot
# or
$ pip install github-copilot-cli  # published wheel pins CLI_VERSION

Defensive patterns

Strategy: validation

Validate before calling

import copilot._cli_download as d
if not (d.CLI_VERSION or os.environ.get("COPILOT_CLI_PATH")):
    raise SystemExit("dev install: set COPILOT_CLI_PATH or pip install a published wheel")

Try / catch

try:
    cli = download_cli()
except RuntimeError as e:
    if "No CLI version pinned" in str(e):
        cli = os.environ["COPILOT_CLI_PATH"]
    else:
        raise

Prevention

Always install the published wheel in production.
Set COPILOT_CLI_PATH in dev/CI from source installs.
Assert CLI_VERSION is truthy in application startup checks.

When it happens

Trigger: Calling download_cli() or main() with no explicit version argument while CLI_VERSION is empty — which happens when the package is installed from source rather than a published wheel with the version baked in.

Common situations: Installing from a git checkout or editable install where the build step did not stamp CLI_VERSION; running in CI from source; forgetting COPILOT_CLI_PATH in a dev environment.

Understand the failure class

Background: "missing required config value" errors: why libraries refuse to start when a configuration key is empty, unset, or blank — this error's family across 48 libraries.

Related errors

AI-assisted analysis of github/copilot-sdk@cd8cf15dc3 (2026-09-09). Data as JSON: /api/errors/d76e36e5afd89118. Report an issue: GitHub.

Appendix: source

Thrown at python/copilot/_cli_download.py:201


def download_cli(version: str | None = None, *, force: bool = False) -> str:
    """Provision a complete runtime bundle with a ``copilot[.exe]`` alias.

    Args:
        version: CLI version to download. Defaults to the pinned CLI_VERSION.
        force: If True, re-download even if already cached.

    Returns:
        Path to the compatibility entrypoint adjacent to the complete runtime bundle.

    Raises:
        RuntimeError: If the version is not set, download fails, or
                      checksum verification fails.
    """
    ver = version or CLI_VERSION
    if not ver:
        raise RuntimeError(
            "No CLI version pinned. This is a development install — "
            "set COPILOT_CLI_PATH or install a published wheel."
        )

    binary_name = get_cli_binary_name()

    if not force:
        cached = get_cached_cli_path(ver)
        if cached is not None:
            return cached

    wrapper_path = Path(ensure_runtime_wrapper(ver, force=force))
    binary_path = wrapper_path.with_name(binary_name)
    fd, temp_name = tempfile.mkstemp(dir=wrapper_path.parent, prefix=".cli-")
    try:
        with os.fdopen(fd, "wb") as destination:
            destination.write(wrapper_path.read_bytes())
        staged = Path(temp_name)

View on GitHub (pinned to cd8cf15dc3)