---
title: "CircleCI environment CLI usage guide"
description: "Using the CircleCI environment CLI in your CI/CD pipeline"
doc_version: "unversioned"
last_updated: "2026-09-22"
---

> For the complete documentation index, see [llms.txt](https://circleci.com/docs/llms.txt)

# CircleCI environment CLI usage guide

This page provides reference documentation for the CircleCI environment CLI, which is the CLI available in your CircleCI pipelines.

## Introduction

This reference guide covers some basic information about the CircleCI task-agent CLI, including:

*   Complete command reference - available commands and subcommands.
    
*   Flag documentation - Comprehensive flag options with descriptions.
    
*   Usage examples - Practical examples showing real-world usage patterns.
    
*   Command descriptions - Clear explanations of what each command does.
    

## CLI differentiation

The environment CLI is different from the [CircleCI Local CLI](https://circleci.com/docs/guides/toolkit/circleci-cli/) tool that you may already know. Understanding the difference between these two CLI interfaces is essential for effective usage during your build processes.

The CircleCI environment CLI

A specialized command-line interface. The environment CLI retrieves and configures a task before managing the execution of the job within a chosen compute environment. The environment CLI is available for use in your CI/CD pipelines.

The Local CLI

The development tool used on a local machine. It handles day-to-day development tasks, testing, and local workflow management.

These tools share some similarities. However, they serve different purposes and operate in different contexts with different capabilities and permissions.

## Root command

The CLI tool available in CircleCI pipelines. The root command is `circleci`.

## Subcommands

### Environment variables

Use `env` to manage environment variables.

#### Substitution

`subst` is a subcommand for `env`. Use `circleci env subst` to substitute environment variables in a string.

**Example usage:**

Consider this scenario: In your repository there exists a file called `template.json`, with values replaced by environment variable strings, as follows:

```json
{
  "foo": "$FOO",
  "provider": "${PROVIDER}"
}
```

The config example below shows the corresponding environment variables defined directly within a step in the config.

```yaml
version: 2.1
jobs:
  process-template:
    docker:
      - image: cimg/base:current
    steps:
      - checkout
      - run:
          name: Process template file
          environment:
            FOO: bar
            PROVIDER: circleci
          command: |
            ## circleci env subst [flags]
            circleci env subst < template.json > deploy.json
            cat deploy.json
workflows:
  env-subst-workflow:
    jobs:
      - process-template
```

In this example:

*   The `<` symbol redirects the contents of the `template.json` file as input to the `circleci env subst` command.
    
*   The `>` symbol redirects the output of the `env subst` command to the `deploy.json` file.
    

Alternatively, you can pass input to the `circleci env subst` command as an argument: `circleci env subst "hello \$WORLD"`.

Output:

```json
{
  "foo": "bar",
  "provider": "circleci"
}
```

For more information on using the `env` command, see the [Introduction to Environment Variables](https://circleci.com/docs/guides/security/env-vars/#environment-variable-substitution) page.

### Run

Invokes a task-agent subcommand by name.

#### OpenID Connect tokens

A subcommand of `run`. The `circleci run oidc` command runs authentication using OIDC.

For more information, including an example, see the [OpenID Connect Tokens With Custom Claims](https://circleci.com/docs/guides/permissions-authentication/oidc-tokens-with-custom-claims/) page.

#### Release

A subcommand of `run`. The `circleci run release` commands allow you to manage your deployments.

#### Plan

A subcommand of `release`. The `circleci run release plan` command is used to plan and identify a new deployment that will be referenced in the CircleCI UI. When a release is planned, you can then update its status later in your pipeline to track progress of a deployment.

A _planned_ deployment is displayed in the Deploys UI with `pending` status.

**Flags**

| Flag | Description |
| --- | --- |
| `deploy-name` | An arbitrary positional argument that is used to identify the deployment. Keep this unique within the workflow. |
| `environment-name` | Sets the target environment. If the specified environment does not exist, it will be created. If you do not specify an environment, CircleCI will create one named default. |
| `component-name` | Sets the name that will be displayed in the UI. If you do not already have a component in your project a new one will be created with the name of the project. This will be set as the component that is being deployed. |
| `target-version` | Must match the version being deployed. |
| `namespace` | Optional flag to use a namespace value other than default. |

**Example usage:**

```yaml
jobs:
  deploy-my-service:
    docker:
      - image: cimg/base:current
    steps:
      - run:
          command: |
            ## example usage of run release plan
            circleci run release plan <deploy-name> --environment-name=<some-environment-name> --component-name=<some-component-name> --target-version=<some-version-name> --namespace=<some-namespace>
```

For more information on using the `circleci run release plan` command, see the [Configure Deploy Markers](https://circleci.com/docs/guides/deploy/configure-deploy-markers/) page.

#### Update

The `circleci run release update` command is only for use with deploy markers. If you are using the CircleCI [Release Agent Overview](https://circleci.com/docs/guides/deploy/release-agent-overview/) for Kubernetes deployments, do NOT use the `update` commands. The release agent automatically handles status updates for you.

A subcommand of `release`. Use the `circleci run release update` command to update the status of the deployment.

**Flags**

| Flag | Description |
| --- | --- |
| `status` | Update the deploy status (values can be `RUNNING`, `SUCCESS`, `FAILED`, or `CANCELED`). |
| `failure-reason` | Optional text describing why the deploy failed. Use with `--status=FAILED`. |
| `keep-target-version-live` | Keep the target version marked live when the deploy reports `FAILED` or `CANCELED`. By default, CircleCI restores the last successful version as live. See [Live Version on Failed or Canceled Deploys](https://circleci.com/docs/guides/deploy/configure-deploy-markers/#live-version-on-failed-or-canceled-deploys). |

**Example usage:**

```yaml
jobs:
  deploy-my-service:
    docker:
      - image: cimg/base:current
    steps:
      - run:
          command: |
            ## example usage of run release update
            circleci run release update <deploy-name> --status=running
```

For more information on using the `circleci run release update` command, see the [Configure Deploy Markers](https://circleci.com/docs/guides/deploy/configure-deploy-markers/) page.

#### Log

A subcommand of `release`. The `circleci run release log` command allows you to log your deployments without status updates.

**Flags**

| Flag | Description |
| --- | --- |
| `environment-name` | Sets the target environment. If the specified environment does not exist, it will be created. If you do not specify an environment, CircleCI will create one named default. |
| `component-name` | Sets the name to display in the UI. If you do not already have a component in your project a new one will be created with the name of the project. This will be set as the component that is being deployed. |
| `target-version` | Must match the version you are deploying. |
| `namespace` | Optional flag to use a namespace value other than default. |

**Example usage:**

```yaml
jobs:
  deploy-my-service:
    docker:
      - image: cimg/base:current
    steps:
      - run:
          command: |
            ## example usage of run release log
            circleci run release log --environment-name=<some-environment-name> --component-name=<some-component-name> --target-version=<some-version-name>
```

For more information on using the `circleci run release log` command, see the [Configure Deploy Markers](https://circleci.com/docs/guides/deploy/configure-deploy-markers/) page.

### Task

Manage tasks. You can also use the alias `step` instead of `task`.

#### Halt

Halt is the only available subcommand of `task`. This command stops the current task and treats it as successful.

**Example usage:**

Equivalent commands to halt the current task and treat it as successful

```yaml
## These commands would be equivalent:
circleci task halt
circleci step halt
```

### Tests

Collect and split tests so they can run in parallel. For full details of splitting and running tests using the environment CLI, see the [Use the CircleCI Environment CLI to Split Tests](https://circleci.com/docs/guides/optimize/use-the-circleci-cli-to-split-tests/) page.

#### Split

A subcommand of `tests`. Use `circleci tests split` to split grouped tests into independent buckets so they can run in parallel.

**Flags**

| Flag | Description |
| --- | --- |
| `index` | Index of node. |
| `total` | Number of nodes. |
| `split-by` | How to weight the split, allowed values are `name`, `filesize`, and `timings`. |
| `timings-type` | Lookup historical timing data by: `classname`, `filename`, `testname` or `autodetect` (automatically choose `classname` or `filename`) (default `autodetect`). |
| `show-counts` | Print test file or test class counts to stderr (default `false`). |
| `time-default` | Override default time value of test timing data when timing is not found (default 0s). |
| `timings-file` | JSON file containing historical timing data. |

**Example usage:**

```yaml
version: 2.1

jobs:
  my-job:
    docker:
      - image: cimg/base:current
    steps:
      - run:
          command: |
            ## example usage of split
            circleci tests split [flags] [FILENAME]
```

#### Glob

A subcommand of `tests`. Use `circleci tests glob` to print files matching the glob pattern.

**Flags**

The available flag for the `glob` subcommand is a pattern, and supports the following symbols:

| Symbol | Description |
| --- | --- |
| `*` | Matches any sequence of non-path-separators. |
| `**` | Matches any sequence of characters, including path separators. |
| `?` | Matches any single non-path-separator character. |
| `[…​]` | Matches any character in the set. May use '-' for a range. |
| `{…​}` | Matches a sequence of characters, if any of the alternatives in braces matches. |

**Example usage:**

```yaml
version: 2.1

jobs:
  my-job:
    docker:
      - image: cimg/base:current
    steps:
      - run:
          command: |
            ## example usage of glob
            circleci tests glob [flags] PATTERN
```

#### Run

A subcommand of `tests`. The `circleci tests run` command splits and runs tests.

**Flags**

| Flag | Description |
| --- | --- |
| `command` | Script to run for a list of tests. |
| `index` | Index of node. |
| `total` | Number of nodes. |
| `split-by` | How to weight the split, allowed values are `name`, `filesize`, and `timings`. |
| `timings-type` | Lookup historical timing data by: `classname`, `filename`, `testname` or `autodetect` (automatically choose `classname` or `filename`) (default `autodetect`). |
| `show-counts` | Print test file or test class counts to stderr (default `false`). |

**Example usage:**

```yaml
version: 2.1

jobs:
  my-job:
    docker:
      - image: cimg/base:current
    steps:
      - run:
          command: |
            ## example usage of run
            circleci tests run [flags]
```

**More information on using the `tests` command**:

*   [Guide to Test Splitting and Parallelism](https://circleci.com/docs/guides/optimize/parallelism-faster-jobs/#how-test-splitting-works)
    
*   [Use the CircleCI CLI to Split Tests](https://circleci.com/docs/guides/optimize/use-the-circleci-cli-to-split-tests/)
    

### Version

Output version information.

**Flags**

*   `--short` flag: print only the version string.
    

**Example usage:**

```yaml
version: 2.1

jobs:
  my-job:
    docker:
      - image: cimg/base:current
    steps:
      - run:
          command: |
            circleci --version [flag]
```

## Global flags

| Flag | Description |
| --- | --- |
| `--verbose` | Enable verbose logging output. |
| `--help` | Show help for a command. |

**Example usage for `--verbose`:**

```yaml
version: 2.1

jobs:
  my-job:
    docker:
      - image: cimg/base:current
    steps:
      - run:
          command: |
            circleci run [command] --verbose
```

**Example usage for `--help`:**

```yaml
version: 2.1

jobs:
  my-job:
    docker:
      - image: cimg/base:current
    steps:
      - run:
          command: |
            circleci run [command] --help
```