=====
jenks
=====

Jenks is a command-line tool, designed to interact with a remote jenkins host, including:

Start by either filling out a configuration file, or adding a job with::

    $ jenks config -a http://localhost:8080/job/bar/

After that, you can get status information with:

    $ jenks
    0: localhost, foo (last build #7) SUCCESS
    1: localhost, bar (last build #3) SUCCESS

Jenks works with unique keys assigned to each job, rather than job
names. You can see it in the above example: it's the 0 and 1 at the
beginning of the line.

You can trigger the job foo from above with::

    $ jenks trigger :0

Get the latest build information from the job bar with::

    $ jenks build :1

Get information about multiple jobs simultaneously by adding multiple keys::

    $ jenks -l :10

And you can pull up more information with::

    $ jenks docs

Installation
============

* since jenkinsapi (the main dependency) is only python2
  compatible, jenks is currently only python2 compatible.

There's a few ways to install Jenks.

Through pip::

    pip install jenks
    pip install http://github.com/toumorokoshi/jenks/tarball/master

Through `sprinter <http://sprinter.readthedocs.org/en/latest/>`_::

    sprinter install https://raw.github.com/toumorokoshi/jenks/master/sprinter.cfg


Configuration (.jenksrc)
========================

Jenks requires a .jenksrc file to configure itself. Jenks searches in
the current directory and moves up parent directories until it finds one.

A .jenksrc file should be a yaml file, with a dictionary of hosts and
some keys for configuration.

Here is an example .jenksrc file with all options::

    'localhost':
      url: 'http://localhost:8080/'
      jobs:
        - foo
        - bar
    'http://jenkins.local':
      jobs:
        - baz

the in-depth configuration for a host is:

* url: the url to the host. If the url doesn't exist, the host name is used as the url
* jobs: a list of job names to add to the list

Keys
====

By default, Jenks will perform operations on all jobs in the
configuration. However, you can restrict the jobs to specific ones by
passing a list of keys. Each job is given a unique key generated by
jenks. For example, using -l on the example configuration will yield::

    $ jenks -l
    0 http://jenkins.local baz
    1 localhost foo
    2 localhost bar

The character at the beginning of each line is the key. Each key is a
single character in the set: [0-9a-zA-Z]. You can pass in a string of
characters prefixed with a colon to get information about those::

    $ jenks -l :20
    0 http://jenkins.local baz
    2 localhost bar

You can pass in keys as:

* an argument::

    $ jenks -c :0

* with standard in::

    $ echo '0' | jenks

Job Codes
=========

You can also reference jobs from the jenksrc by name, using the job
code syntax. The job code syntax looks like::

    <host_key>/<job_name>
    localhost/bar

For example, here's how to get information about the latest build of a job by job code::

    $ jenks build localhost/bar

Examples
========

Ones of Jenks' goals is to follow the Unix philosophy of doing one
thing and doing it well. By being a modular part and supporting stdin,
it's possible to chain Jenks with other commands.

For example, here's a command that only lists status of jobs whose host or job name match a specific regex::

    $ jenks -l | grep "foo" | cut -d ' ' -f 1 | jenks
    0: localhost, foo (last build #7) SUCCESS

Monitor the status of your Jenkins jobs::

    $ watch jenks
