Skip to content

About

🌀 CLI client / command line tool for CircleCI

Topics

Resources

Code of conduct

Contributing

Stars

93 stars

Watchers

2 watching

Forks

Repository files navigation

circleci-cli

All Contributors Gem Version codecov Libraries.io dependency status for GitHub repo GitHub

circleci-cli is a CLI tool for Circle CI.

sample.gif

Installation

$ gem install circleci-cli

set the CIRCLE_CI_TOKEN environment variable. (optional)

export CIRCLE_CI_TOKEN=your-circle-ci-token

Quick start

In a local checkout of a GitHub project that builds on CircleCI, switch to the branch you want to inspect and run:

circleci-cli builds

Enter your CircleCI API token when prompted if CIRCLE_CI_TOKEN is unset. The command identifies the project from the GitHub origin remote and shows a table of recent builds on the current branch, including their build numbers and statuses.

Usage

Commands:
  circleci-cli browse               # Open CircleCI website
  circleci-cli build                # Show the build result
  circleci-cli builds               # List builds
  circleci-cli cancel               # Cancel a build
  circleci-cli help [COMMAND]       # Describe available commands or one specific command
  circleci-cli projects             # List projects
  circleci-cli retry                # Retry a build
  circleci-cli run RUN_ID           # Show all workflows and jobs in a run
  circleci-cli version              # Show gem version
  circleci-cli watch                # Watch builds in real time

Options:
  -p user_name/project              # Specify repository
                                    # Default to the Git remote of current directory

  -b branch                         # Specify branch name
                                    # Default to the current Git branch

  -a, --all, --no-all               # Ignore the branch option and stop being filtered by the branch
                                    # Default to false

  -n build_number                   # Specify build number.
  -l last                           # Get or retry last failed build.
  -v verbose                        # Show all the logs if applied to watch command.

  --pretty=true/false, --no-pretty  # Make outputs pretty or not
                                    # Default to true

Examples

Show every job in a run

With CIRCLE_CI_TOKEN set, list your recent runs with the CircleCI API and copy the id next to the run number you want:

curl -fsS -G 'https://circleci.com/api/v3/runs' \
  -H "Authorization: Bearer ${CIRCLE_CI_TOKEN}" \
  --data-urlencode 'filter[user_id]=me' | jq -r '.data[] | [.attributes.number, .id] | @tsv'
circleci-cli run 123e4567-e89b-12d3-a456-426614174000

On projects supported by build, use the displayed job number to inspect its steps, for example circleci-cli build -p user/project -n 42.

Watch your project

$ circleci-cli watch

Watch your project and show all of the build log

$ circleci-cli watch -v

Show last failed build

$ circleci-cli build --last

Retry last failed build

$ circleci-cli retry --last

Open CircleCI webpage for current project

$ circleci-cli browse

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/circleci-tools/circleci-cli. See the contributing guide for development setup and checks.

License

The gem is available as open source under the terms of the MIT License.

Contributors ✨

Thanks goes to these wonderful people (emoji key):


Yuji Ueki

💻

Matt Brictson

💻 ⚠️

Fletcher Fowler

🐛 🤔 💻

Marco Costa

🤔 💻

This project follows the all-contributors specification. Contributions of any kind welcome!

Author

@unhappychoice

About

🌀 CLI client / command line tool for CircleCI

Topics

Resources

Code of conduct

Contributing

Stars

93 stars

Watchers

2 watching

Forks

Releases

Packages

Used by

Contributors

Languages