Installing and Using CircleCI CLI

1. Installing CLI

Platform	Installation Method	Command	Notes
macOS	Homebrew	`brew install circleci`	Available via Homebrew tap
Linux (x86_64)	Direct Download	`curl -fLSs https://circleci.com/download/cli \| sudo bash`	Installs to `/usr/local/bin/circleci`
Windows (WSL)	Chocolatey	`choco install circleci`	Requires Chocolatey package manager
Manual Binary	Direct Download	`curl -fLSs https://circleci.com/download/cli/linux/amd64 > circleci chmod +x circleci`	Download and place in PATH

Example: Verify Installation

circleci version

Note: Ensure the CLI version is compatible with your CircleCI server version.

2. Setting Up CLI Authentication

Step	Description	Action
1. Install CLI	Install the CircleCI CLI using the package manager or installer.	`curl -fLSs https://circleci-cli-release.s3.amazonaws.com/install.sh \| bash`
2. Authenticate	Authenticate with your CircleCI account using the CLI.	`circleci setup`
3. Configure Token	Set up a personal API token for authentication.	`circleci context create my-context`

Example: Authenticating with CircleCI CLI

circleci setup
# Follow the prompts to authenticate with your CircleCI account.

Note: Ensure your API token has the necessary permissions to access the projects you intend to use with the CLI.

3. Validating Config Files

Example: Basic config validation

circleci config validate

Option	Values	Description
--config	`config.yml`	Path to the config file to validate
--local	`false`	Validate local config without sending to CircleCI

Note: The CLI will check for syntax errors and required fields in your config file.

Warning: Validation does not check for runtime errors or job dependencies.

4. Processing Config Locally

Command	Description	Options	Example
circleci config process	Validate and process a CircleCI configuration file	`--config` (optional), `--job` (optional)	`circleci config process .circleci/config.yml`

Note: The circleci config process command does not execute the job, it only validates and processes the configuration file.

5. Running Jobs Locally

Command	Description	Options	Example
circleci local execute	Executes a job locally using the CircleCI configuration	`-c` config file path `-j` job name `-o` output directory	`circleci local execute -j build-job -o /tmp/output`

Example: Running a local job with custom config

circleci local execute -c .circleci/config.yml -j test-job

Note: The local execution requires the circleci CLI to be installed and configured with a valid token.

Warning: Local execution does not support all features of the CircleCI platform, such as certain environment variables or resource classes.

6. Testing Config Changes

Example: Validate config locally

circleci config validate

Command	Description	Notes
circleci config validate	Validates the configuration file	Checks for syntax errors and required fields
circleci config pack	Packs the configuration into a single file	Useful for debugging and sharing config

Note: The circleci config validate command checks your .circleci/config.yml file for correctness and will report any issues found.

Example: Pack config for debugging

circleci config pack > packed-config.yml

7. Packing Orbs

Orbs are reusable configuration templates in CircleCI that can be shared across projects. Packing an orb involves packaging the configuration and metadata into a distributable format.

Step	Description	Action
1. Prepare Configuration	Ensure your orb configuration is valid and includes all necessary metadata.	`version: 2.1 description: "A sample orb for demonstration" orbs: my-orb: version: "1.0.0"`
2. Create Orb Directory	Organize your orb files in a dedicated directory structure.	`mkdir -p my-orb/src touch my-orb/src/config.yml`
3. Define Metadata	Include metadata in your orb configuration file.	`version: 2.1 description: "Sample orb for testing" displayName: "My Sample Orb"`
4. Pack the Orb	Use the CircleCI CLI to pack your orb into a distributable format.	`circleci orb pack my-orb/src/config.yml > packed-orb.yml`

Example: Packing an Orb

# Create a directory for the orb
mkdir -p my-orb/src

# Define the orb configuration in config.yml
cat << EOF > my-orb/src/config.yml
version: 2.1
description: "A sample orb for demonstration"
displayName: "Sample Orb"

executors:
  default:
    docker:
      - image: circleci/python:3.9

commands:
  run-tests:
    parameters:
      command:
        type: string
        default: "python -m pytest"
    executor: default
    steps:
      - run: "<<parameters.command>>"

jobs:
  test-job:
    executor: default
    steps:
      - run-tests:
          command: "python -m pytest tests/"
EOF

# Pack the orb using CircleCI CLI
circleci orb pack my-orb/src/config.yml > packed-orb.yml

Note: Ensure that all paths and file names are correctly specified when packing an orb. The packed output can be used to publish or test the orb in a CircleCI project.

8. Publishing Orbs

Orbs are reusable configurations that can be shared across projects in CircleCI. Publishing an orb allows you to distribute your configuration templates to other users.

Step	Description	Action
1. Prepare Orb	Ensure your orb is properly structured with a `config.yml` file and any necessary resources.	Validate orb structure locally using `circleci orb validate`.
2. Create Orb in CircleCI	Use the CircleCI web UI or CLI to create a new orb within your organization.	Run `circleci orb create <org>/<orb-name>`.
3. Publish Orb	Push your orb to the CircleCI registry.	Run `circleci orb publish <orb-path>`.

Example: Publishing an Orb

circleci orb create my-org/my-orb
circleci orb publish my-org/my-orb@1.0.0

Note: Orbs must be versioned using semantic versioning (e.g., v1.0.0). The version must be incremented for each new publish.

Warning: Once an orb is published, its content cannot be changed. To update functionality, you must publish a new version.

9. Listing Available Orbs

Command	Description	Notes
circleci orb list	List all available orbs in the CircleCI registry	Shows name, version, and description of each orb
circleci orb list <namespace>	List orbs within a specific namespace	Useful for filtering orbs by organization or user
circleci orb search <query>	Search for orbs matching a query term	Helps find orbs by keyword or feature

Example: Listing all orbs

circleci orb list
# Output:
# circleci/python 2.0.0
# circleci/node 2.0.1
# circleci/ruby 1.0.0

Example: Listing orbs in a namespace

circleci orb list circleci
# Output:
# circleci/python 2.0.0
# circleci/node 2.0.1

Example: Searching for orbs

circleci orb search python
# Output:
# circleci/python 2.0.0
# circleci/python-3 1.0.0

10. Updating CLI Version

Method	Description	Notes
circleci update	Updates the CircleCI CLI to the latest version	Requires admin privileges on some systems
circleci update --version <version>	Installs a specific version of the CircleCI CLI	Useful for testing or maintaining consistency across environments

Example: Update to latest version

circleci update

Example: Install specific version

circleci update --version 0.1.5678