circleci-cli

 

      

A pure bash, feature-rich command line interface for CircleCI.

Sample use cases:

• Programmatically interact with the CircleCI API
• OS X notification integration (i.e. each git push to GitHub notifies you about the eventual CircleCI build success or failure)
  • Add alias: alias gpn='f() { git push && { sleep 10 ; circleci notify; } &; }; f'
  • Push with notifications: gpn
• Perform advanced filtering/querying upon JSON responses to do things that are not possible via the UI
  • View build numbers of successful builds: circleci builds --filter '.[] | select(.status=="success") | .build_num'
• Perform advanced filtering upon JSON responses to do piped operations back into circleci-cli and/or other CLIs (e.g. find failed builds and re-trigger them, find successful builds and feed into a dashboard)

Installation

Via brew:

$ brew tap rockymadden/rockymadden
$ brew install circleci-cli

Via curl:

$ curl -O https://raw.githubusercontent.com/rockymadden/circleci-cli/master/src/circleci
$ chmod 755 circleci

PROTIP: You are responsible for having stedolan/jq and github/hub on your $PATH.

Via make:

$ git clone git@github.com:rockymadden/circleci-cli.git
$ cd circleci-cli
$ make install bindir=/path/to/bin etcdir=/path/to/etc

PROTIP: You are responsible for having stedolan/jq and github/hub on your $PATH.

Configuration

Ensure you have a CircleCI API token and use said token one of the following ways:

Via init:

$ circleci init

Via environment variable:

export CIRCLECI_CLI_TOKEN='token'

Usage

$ circleci --help
Usage:
  circleci artifacts <project> <build>
    [--compact|-c] [--filter|-f <filter>] [--monochrome|-m] [--trace|-x]

  circleci await <project> <build>
    [--compact|-c] [--filter|-f <filter>] [--monochrome|-m] [--resolution|-r <seconds>]
    [--trace|-x]

  circleci browse <project> [build]
    [--trace|-x]

  circleci build <project> <build>
    [--compact|-c] [--filter|-f <filter>] [--monochrome|-m] [--trace|-x]

  circleci builds <project>
    [--compact|-c] [--filter|-f <filter>] [--limit|-l <limit>] [--monochrome|-m]
    [--offset|-o <offset>] [--trace|-x]

  circleci cancel <project> <build>
    [--compact|-c] [--filter|-f <filter>] [--monochrome|-m] [--trace|-x]

  circleci init
    [--compact|-c] [--filter|-f <filter>] [--monochrome|-m] [--token|-t <token>]
    [--trace|-x]

  circleci me
    [--compact|-c] [--filter|-f <filter>] [--monochrome|-m] [--trace|-x]

  circleci notify <project> <build>
    [--resolution|-r <seconds>] [--trace|-x]

  circleci project <project>
    [--compact|-c] [--filter|-f <filter>] [--monochrome|-m] [--trace|-x]

  circleci projects
    [--compact|-c] [--filter|-f <filter>] [--monochrome|-m] [--trace|-x]

  circleci retry <project> <build>
    [--compact|-c] [--filter|-f <filter>] [--monochrome|-m] [--trace|-x]

  circleci trigger <project> <branch>
    [--compact|-c] [--filter|-f <filter>] [--monochrome|-m] [--parameter-key|-K <key>]
    [--parameter-value|-V <value>] [--revision|-R <revision>] [--trace|-x]

Configuration Commands:
  init    Initialize

Core Commands:
  artifacts    List the artifacts produced by a given build for a given project
  build        Details of a given build for a given project
  builds       Details of all builds for a given project
  cancel       Cancel a given build for a given project
  me           Details of the given user
  project      Details of a given project
  projects     List projects of the given user
  retry        Retry a given build for a given project
  trigger      Trigger a new build of a given branch for a given project

Convenience Commands:
  await     Await success or failure of a given build for a given project
  browse    Open CircleCI page of a given project
  notify    Await success or failure of a given build for a given project and create an OS X
            notification with the details

More Information:
  chat    https://rockymadden-slack.herokuapp.com/
  repo    https://github.com/rockymadden/circleci-cli

PROTIPS:

• Project names are represented as a combination of username and project name (e.g. rockymadden/circleci-cli).
• -- can be used as a placeholder for the current project, when inside a GitHub-based git repo.
• Project placeholder is implicitly applied, when not provided and inside a GitHub-based git repo.
• -- can be used as a placeholder for the most recent build.
• Build placeholder is implicitly applied, when not provided.
• -- can be used as a placeholder for the current branch, when inside a git repo.
• Branch placeholder is implicitly applied, when not provided and inside a git repo.
• The --compact option is a wrapper around the jq --compact-output option
• The --filter option is passed directly to jq as a filter
• The --monochrome option a wrapper around the jq --monochrome-output option
• All commands prompt for required arguments which were not provided via options or arguments. This allows for both traditional usage and prompt-based usage.

artifacts:

$ # Implicit project and build:
$ circleci artifacts

$ # Placeheld project and build:
$ circleci artifacts -- --

$ # Placeheld project and explicit build:
$ circleci artifacts -- 1

$ # Explicit project and build:
$ circleci artifacts rockymadden/circleci-cli 1

await:

$ # Implicit project and build:
$ circleci await

$ # Placeheld project and build:
$ circleci await -- --

$ # Placeheld project and explicit build:
$ circleci await -- 1

$ # Explicit project and build:
$ circleci await rockymadden/circleci-cli 1

$ # With filter:
$ circleci await --filter='.build_num'

browse:

$ # Implicit project and build:
$ circleci browse

$ # Placeheld project and build:
$ circleci browse -- --

$ # Placeheld project and explicit build:
$ circleci browse -- 1

$ # Explicit project and build:
$ circleci browse rockymadden/circleci-cli 1

build:

$ # Implicit project and build:
$ circleci build

$ # Placeheld project and build:
$ circleci build -- --

$ # Placeheld project and explicit build:
$ circleci build -- 1

$ # Explicit project and build:
$ circleci build rockymadden/circleci-cli 1

$ # With filter:
$ circleci build --filter='.build_num'

builds:

$ # Implicit project:
$ circleci builds

$ # Placeheld project:
$ circleci builds --

$ # Explicit project:
$ circleci builds rockymadden/circleci-cli

$ # With filter:
$ circleci builds --filter='.[] | .build_num'

cancel:

$ # Implicit project and build:
$ circleci cancel

$ # Placeheld project and build:
$ circleci cancel -- --

$ # Placeheld project and explicit build:
$ circleci cancel -- 1

$ # Explicit project and build:
$ circleci cancel rockymadden/circleci-cli 1

$ # With filter:
$ circleci cancel --filter='.status'

me:

$ # With filter:
$ circleci me --filter='.login'

notify:

$ # Implicit project and build:
$ circleci notify

$ # Placeheld project and build:
$ circleci notify -- --

$ # Placeheld project and explicit build:
$ circleci notify -- 1

$ # Explicit project and build:
$ circleci notify rockymadden/circleci-cli 1

project:

$ # Implicit project:
$ circleci project

$ # Placeheld project:
$ circleci project --

$ # Explicit project:
$ circleci project rockymadden/circleci-cli

$ # With filter:
$ circleci project --filter='.username + "/" + .reponame'

projects:

$ # With filter:
$ circleci projects --filter='.[] | .username + "/" + .reponame'

retry:

$ # Implicit project and build:
$ circleci retry

$ # Placeheld project and build:
$ circleci retry -- --

$ # Placeheld project and explicit build:
$ circleci retry -- 1

$ # Explicit project and build:
$ circleci retry rockymadden/circleci-cli 1

$ # With filter:
$ circleci retry --filter='.status'

trigger:

$ # Implicit project and branch:
$ circleci trigger

$ # Placeheld project and branch:
$ circleci trigger -- --

$ # Placeheld project and explicit branch:
$ circleci trigger -- master

$ # Explicit project and branch:
$ circleci trigger rockymadden/circleci-cli master

$ # With build parameters:
$ circleci trigger --parameter-key=key1 --parameter-value=val1 --parameter-key=key2 --parameter-value=val2

$ # With build parameters (short form):
$ circleci trigger -K key1 -V val1 -K key2 -V val2

$ # With revision:
$ circleci trigger --revision=634f9656ccf6e0cad7385782e776569bddbf84d6

$ # With revision (short form):
$ circleci trigger -R 634f9656ccf6e0cad7385782e776569bddbf84d6

$ # With filter:
$ circleci trigger --filter='.vcs_revision'

$ # With filter (short form):
$ circleci trigger -f '.vcs_revision'

from https://github.com/rockymadden/circleci-cli