Overview

Jobs that install the CircleCI CLI via the circleci/circleci-cli orb may unexpectedly get the newest CLI (including CLI 1.0.x), even when a specific older version is requested. After CircleCI CLI 1.0 began rolling out as “latest” (around early August 2026), pipelines that call circleci config process (or similar helpers) without a CircleCI API token can start failing with authentication errors—often with no related config change on your side.

This article explains:

What errors look like
Why a pinned CLI version may be ignored
When the behavior started
Workarounds to restore a known-good CLI, or to use CLI 1.0 with auth

Orb registry: circleci/circleci-cli install command

Related GitHub issue (version parameter ignored): CircleCI-Public/circleci-cli-orb#13

Symptoms

You may see one or more of the following:

Install step logs a selected version, then installs a different (newer) version

Example pattern:

Selected version of CircleCI CLI is v0.1.xxxxx
A different version of the CircleCI CLI is installed (Build Agent version: ...); updating it
==> Installing CircleCI CLI v1.0.xxxxx
CircleCI CLI version circleci 1.0.xxxxx ... has been installed

Config checks fail only on CLI 1.0.x with a token error

Typical message:
```
error: No CircleCI API token found.Suggestions:
  • Run: circleci auth login
  • Or set the CIRCLE_TOKEN environment variable
```
A common pattern in scripts or tests is that circleci config validate succeeds, then circleci config process fails with the token error above.
Jobs that previously used an older CLI via circleci-cli/install (with or without an explicit version) start failing after “latest” resolves to CLI 1.0.x.

When this started

Orb version parameter ignored on older orb releases: On circleci/[email protected] and earlier, the install command did not pass the requested version into the upstream install script when updating/replacing an existing circleci binary. That bug was reported in and fixed in orb 0.1.10. Orb 0.1.11 keeps that fix (install script URL updated to main).
CLI 1.0 as “latest”: Stable CircleCI CLI 1.0.x releases began appearing as the GitHub “latest” install target around 5 August 2026. Pipelines that effectively install latest (including those on orb 0.1.9 with an ignored pin) can suddenly pick up 1.0.x.
Auth requirement for some CLI commands: On CLI 1.0.x, commands such as circleci config process expect a CircleCI API token (CIRCLE_TOKEN / CLI auth). Older 0.1.x CLIs commonly used in CI did not require a token for the same local config-processing flow.

Why it happens

Two separate behaviors often stack:

The circleci/circleci-cli orb’s version parameter was a no-op before 0.1.10

On 0.1.9 and earlier, the job can print “Selected version of CircleCI CLI is …”, then still run the public install script without setting VERSION, so the script installs whatever is currently latest.

On CircleCI jobs, command -v circleci often finds the build agent’s circleci binary first (version string like “Build Agent version: …”). The orb treats that as “wrong CLI version,” removes it, and reinstalls—again without honoring the pin on those older orb versions.
CLI 1.0.x changes auth expectations for config processing

Once 1.0.x is installed, scripts that call circleci config process (directly or via a test helper) can fail with “No CircleCI API token found,” even when circleci config validate still passes.

Workarounds

Option A — Pin an older CLI with a fixed orb (most common for “stay on 0.1.x”)

Use circleci/[email protected] or later (for example @0.1.11). Do not rely on @0.1.9 if you need the version parameter to work.
Pass a full release tag to version (include the leading v), as listed under CircleCI CLI GitHub tags/releases.

orbs:
  circleci-cli: circleci/[email protected]:
  example:
    docker:
      - image: cimg/base:current
    steps:
      - circleci-cli/install:
          version: v0.1.38646
      - run: circleci version

Confirm in the “Install CircleCI CLI” step that the installed version matches the requested tag (not a 1.0.x build).

Important: Updating only the version: lines under circleci-cli/install is not enough if the orb itself is still @0.1.9. Bump the orb import as well.

Option B — Stay on latest CLI 1.0.x and supply a token

If you want the newest CLI, provide credentials wherever circleci config process (or other authenticated CLI commands) runs:

Set a project or context environment variable such as CIRCLE_TOKEN to a valid personal API token, or
Run circleci setup / circleci auth login in the job before those commands (as appropriate for your environment).

Restrict token scope and storage to what your security policy allows (prefer a context limited to the jobs that need it).

Option C — Install without the orb

You can call the upstream install script yourself and set VERSION explicitly (no leading v in the environment value):

curl -fLSs https://raw.githubusercontent.com/CircleCI-Public/circleci-cli/main/install.sh \
  | sudo env VERSION=0.1.38646 bash
circleci version

Adjust VERSION to the build you need. Prefer env VERSION=... so the variable is not dropped by sudo.

How to verify

In job logs, the install step should show the selected version and a matching installed version.
circleci version (or circleci --skip-update-check version) reports the expected 0.1.x or 1.0.x build.
If using Option B, circleci config process succeeds with the token present.

circleci-cli orb ignores CLI version pin / CLI 1.0 config process requires a token