[[!meta title="Using icktool"]]

Icktool is a command line program that uses the ick controller API to
manage projects and pipelines and querying status.

Installation
-----------------------------------------------------------------------------

Currently, you are best off running icktool from the [ick2.git][] source
code repository:

    git clone git://git.liw.fi/ick2
    cd ick2
    ./icktool --help

[ick2.git]: http://git.liw.fi/ick2

Alternatively, you can install the Debian package from
<http://code.liw.fi/debian/>.


Configuration
-----------------------------------------------------------------------------

Create the file `~/.config/icktool/icktool.yaml` with the following
content:

    config:
        controller: https://ick2
        verify-tls: no

Create the file `~/.config/icktool/credentials.conf` with the following
content:

    [https://ick2/token]
    client_id = admin
    client_secret = qwert

Change the `controller` line and the first line of `credentials.conf`
to be the URL to your controller.

Change `verify-tls` to `yes` if you have a CA-signed TLS certificate,
such as by Let's Encrypt.


Using
-----------------------------------------------------------------------------

To see all projects and pipelines use the `status` command:

    $ ./icktool status
    project | build_status | log_id
    ------- | ------------ | ------
    $ 

There should be no projects initially. To create some, create a file
`hello.ick` with the following content:

    projects:

      - project: say_hello
        parameters:
          target: world
        pipelines:
          - greet

    pipelines:

      - pipeline: greet
        parameters:
          - target
        actions:
          - shell: |
              t="$(params | jq -r .target)"
              echo "hello, $t"
            where: host

[jq][] is a handy command line tool for doing things with data in JSON
form. Here it is used to extract the value of a parameter. `params` is
a shell function provided by ick that outputs all parameters as JSON.

[jq]: https://github.com/stedolan/jq

Tell the controller about the new project:

    ./icktool make-it-so hello.ick

Trigger a build:

    ./icktool trigger say_hello

Check status (repeatedly until the build finishes):

    watch ./icktool status

Check the build log (you can run this while the build happens, as
well):

    ./icktool show-latest-log say_hello

Get help on command line use:

    ./icktool --help
    ./icktool help
    ./icktool help make-it-so


Triggering builds from version control servers, etc
-----------------------------------------------------------------------------

To trigger a build of project foo, access the
`https://controller/projects/foo/+trigger` (HTTP GET method, no
authentication needed).