Create a command line tool to interact with CircleCI REST API



There is already a REST API, but it would be really useful to also have a command line tool (circle?) in the same vein as Heroku’s, Amazon’s, and Google’s command line tools. This way, things like configuration and builds can be more easily scripted, and it’s also much easier to work with a command line tool when working interactively.

For instance, I wrote a command called circle that interacts with the REST API just for this purpose. So when I want to see information about myself, I can just type:

circle me

… and it hits the /me endpoint (the API token is stored in a configuration file read by the command). Easy!


Love this idea! Do you happen to have a public repo I can take a look at for your command?


I just found out there’s another tool already out there publicly!

The only issue is that it’s one-for-one with the API (so it’s restricted to things like setting only a single environment variable at a time for a project), and it’s in Bash only (so could be different on Mac vs Linux, and won’t work on Windows pre-native-bash). I’ll see if I can rewrite mine in Python to be platform-agnostic, and maybe work in some extras like that multiple environment variable settings I mentioned and stuff that the API doesn’t yet support :slight_smile:

Gonna have to give me a couple days…


I am not sure that a full blown client is really necessary. Using something like hammock you can most probably get away of having to maintain an additional library:

Check for example here:


@drazisil Well, I said I would create one if I thought it was worth it, so I did:

I didn’t find one that was cross-platform, and I also couldn’t find one that did anything the API couldn’t do (such as set multiple environment variables at once, or format/organize the JSON responses into something nicely readable). This one is written in Python, and available through pip, so it should be an easy install and setup (it will set itself up on first run).

Let me know what you think :slight_smile:



Looks awesome!

Haven’t given it a try yet, but just looking though the Readme it seems pretty cool.

Here are a couple requests I have saved, if you want to try adding functionality to it, based on what users here have expressed interest in:

Sorry for the wall of text, I can certainly move to issues on GH if you prefer.

I can also try my hand at pull requests for some of these, but I’ve only used python for a couple small projects, so between everything else on my plate and how weak my knowledge in it is I don’t know if I can can find room for it in my head space at this time.

Again, pretty awesome, thanks for creating and more so for sharing!


These look like reasonable requests. I especially like the idea of filtering! I’ll give it a shot.


I can do almost all of those pretty easily via While TheRealJoeLinux is right the core commands are a 1:1 to the API, there is a concept of convenience commands. These commands compose two or more core commands to do interesting things like you mentioned above. I’ll get these added soon. Also, it is pure bash on purpose, to keep it lightweight, minimal, and works with any system with bash 3.2 or above. It works on Linux and Mac just the same and it is tested to do as such each push.


Here is an example of how easy it is to do some of those. The idea of viewing only certain project builds by their status? Simple (assumes you are in a CircleCI/GitHub project directory):

circleci builds --filter '.[] | select(.status=="success")'

Want to do that, but only view their build numbers?

circleci builds --filter '.[] | select(.status=="success") | .build_num'


I completely forgot your tool existed, I’ll take a look in a bit.

Question I have, while I know “real” programmers don’t use windows, how does your tool work under that OS?

(before people get offended, I use windows :slight_smile:


I think the latest version of Windows has a native Bash CLI? Might be interesting to see how that tool runs there.


No worries at all. No qualms here with Windows or whatever tool engineers choose to use, but ATM I don’t do any specific testing for Windows. I lack a Windows box to see if the script works correctly with the new (I believe) Linux shell support. Have ideas on how I could test that? I am game if we can find a way to do it.


@TheRealJoeLinux, @rockymadden

I completely didn’t know about the bash in Windows 10, I’m installing it now and will give it a shot.


The only thing I can think of is maybe the make install step might give you issues if the OS detection isn’t “right”. Assuming it works right and detects as Linux, to test it, it should be as simple as:

  • Installing jq (, the one non-standard dependency. Maybe via apt-get install jq with the Win 10 bash?
  • git clone
  • cd circleci-cli
  • make install
  • build/bin/circleci init
  • build/bin/circleci me

If the test works, I can document installation from source with tweaks to put it on your path and such (and I should for Linux too).


It looks like the bash isn’t released to the public yet, and I’m trying to remember how to enable my Windows Insider builds.

That said, I think I would prefer something I can place in my dependencies, rather then a git clone and make. I personally try to keep everything in project and make my circle.yml file as small as possible, since it’s not easy to test to locally as far as I’m aware.


I gotcha, no worries. git and make aren’t needed in reality, just one possible workflow. All that truly needs to be done is somehow get (e.g. wget, curl) locally and update the two variables at the top with full paths (e.g. sed). This could probably be done via a one-liner with pipes. Boom:

curl | sed -e "s|bindir=|bindir=$(pwd)|g" | sed -e "s|etcdir=|etcdir=$(pwd)|g" > circleci


As I mentioned in, I’d really like this to work out of the box, nearly zero config. I know we are developers, but it’s my belief that users (even developers) want things that just work with as little config or tweaking as possible.

I mean, things like Conditional expressions [[ ... ]] && work if used with yamal block literals "|" work great for people used to bash scripting, but they make my brain hurt. :smiley:


I’m pretty good with validations and stuff, so I’ve been working on two things locally: filtering and non-interactively reading tokens/usernames.


Not saying that bash isn’t more flexible, as not every project will be python (and those that aren’t won’t want to install it just for this tool), but tossing a tool into my dev dependencies is preferable to wget’ing something and then having to configure it.

@TheRealJoeLinux I’m planning on working on some of my requests as well, just so you don’t think I threw a list at you. Just personal life and prepping for a mini vacation are fun.

@rockymadden as soon as Windows gets around to getting me the build that has bash I will certainly try out circleci-cli and report back if/how it works :slight_smile:


No worries about “throwing a list at me.” That’s exactly why I open sourced it. I’m considering posting some of my other tools that I normally use as well, since I’ve written a bunch for personal use.

Also, CircleCI always has pip available, so it’s really easy to just add pip install circlecli in the circle.yml dependencies. I specifically chose Python because it’s installed by default on Linux and OSX (but I wrote it to also work on Windows).

Are you actually testing this on Windows? Because I haven’t gotten around to it.