Add: simple manual for icktool

1 files changed, 95 insertions, 0 deletions

diff --git a/icktool.mdwn b/icktool.mdwn
new file mode 100644
index 0000000..c5cac28
--- /dev/null
+++ b/icktool.mdwn
@@ -0,0 +1,95 @@
+[[!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
+
+Configuration
+-----------------------------------------------------------------------------
+
+Create the file `~/.config/icktool/icktool.yaml` with the following
+content:
+
+    config:
+        controller: https://ick2
+        token-private-key-cmd: pass show ick2/token_key
+        verify-tls: no
+
+Change the `controller` line to be the URL to your controller.
+
+Change the `token-private-key-cmd` to something that outputs the
+private part of the token signing key.
+
+Change `verify-tls` to `yes` if you have a CA-signed TLS certificate.
+(The default setup uses self-signed ones.)
+
+
+Using
+-----------------------------------------------------------------------------
+
+To see all projects and pipelines use the `status` command:
+
+    $ ./icktool status
+                 project |           pipeline | status | build_status |       log
+    -------------------- | ------------------ | ------ | ------------ | ---------
+    $ 
+
+There should be no projects initially. To create some, create a file
+`ick.yaml` 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 < ick.yaml
+
+Trigger a build:
+
+    ./icktool trigger say_hello greet
+
+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