Basic Usage

Hello, World!

Using Asink as a command line tool is very simple indeed. It just requires a configuration file written in either YAML or JSON.

Here is a simple Hello World example in both YAML and then JSON:

---
tasks:
  hello-world:
    command: echo
    args:
      - 'Hello, World!'

The equivalent in JSON:

{
  "tasks" : {
    "hello-world" : {
      "command" : "echo",
      "args" : ["Hello, World!"]
    }
  }
}

The choice is yours! Although YAML supports comments and is arguably slightly easier to read.

So in the examples above we're simply executing one task which will echo out "Hello, World!". Not very useful, but an easy way to demonstrate the layout of the file.

Let's take a look at a slightly more involved example:

---
tasks:
  clone-asink:
    command: git
    args:
      - clone
      - https://github.com/GroundSix/asink.git
    group: clones

  clone-martini:
    command: git
    args:
      - clone
      - https://github.com/go-martini/martini.git
    group: clones

  do-ls:
    command: ls
    args:
      - -la
    dir: asink
    require: clone-asink

Here we are running 3 tasks. Asink will clone itself and Martini at the same time. This is because we have defined group: clones. Any tasks using the same group key will be executed at the same time. We then want to run ls -la in the asink directory. There is a require key on here which will wait for clone-asink to finish running first. As it's part of a group, do-ls will wait for all tasks in that group to execute first, before executing.

Here is a list of keys that can be used for each task, with a small example of each case:

Key	Description
command	This is the root command
args	An array of command arguments
count	The asynchronous and relative count
require	The required command is ran first
group	Groups are ran at the same time
dir	The directory to be in when running
env	Sets any env vars you might need
remote	The remote machine to run on

Command

This must just be the root command. So in this example it is git. It could be anything, however you can't pass any arguments or flags in this.

Args

In args you may pass all arguments and flags. For example if your command was ls, your args could be just ["-la"]. These are just comma-seperated values and there is no limit to how many you can use.

Count

You'll notice that the count key has requires two numbers. This is because it can run the same command lots of times in sets. In the example above it has been set to [2, 6]. This means that it will run 2 batches of the command 6 times, concurrently. So 12 times in total. This can be useful if you have a command you need to run lots of times very quickly.

Require

Sometimes you'll have a command that first requires another one to be ran first. Be default commands are ran chronologically, but if the order becomes mixed up or you have a fairly complex configuration you can define the key of another command in here and that will be ran first.

Group

Groups allow you to take advantage of Asink's concurrency. Here is a small example:

---
tasks:
  # Clones the Asink repo
  clone-asink:
    command: git
    args:
      - clone
      - https://github.com/groundsix/asink.git
    # We define a new group here called repos
    group: repos

  # Clones the PHP client libary repo
  clone-client:
    command: git
    args:
      - clone
      - https://github.com/asink/asink-php.git
    group: repos

Here we are cloning two repos, Asink and a client library. A group has been defined. This means that both of these commands will run concurrently. You can add groups to as many commands as you like. It plays well with require.

Dir

This is where you can specify the directory for the command to be ran in. It may be a relative one to where you are running asink from, or an absolute path.

Env

Env accepts a list of env keys and values you'd like to set, for example:

---
tasks:
  echo-gopath:
    # An array of env vars can be set here
    # They are always set before the command
    # is executed and are persistent until the
    # program has finished executing all tasks
    env:
      - NAME=Harry

    command: echo
    args:
      - "Gopath is set to: "
      - $GOPATH
      - "\nAlso, my name is $NAME"

Remote

The remote key allows you to specify a remote machine for the command to be ran on. See below for how this can be set up.

Remote Access (SSH)

As well as being able to run commands locally, Asink can start up SSH sessions and run commands on another machine at the same time. This is done using the remotes key outside of the tasks scope.

Here is an example of running a command on a vagrant box:

---
remotes:
  # We define a remote machine here
  vagrant:
    host: localhost
    port: 2222
    user: vagrant
    key: ~/.ssh/id_rsa

tasks:
  # Clones the Asink repo
  clone-asink:
    # We tell the task which remote to use
    remote: vagrant
    command: git
    args:
      - clone
      - https://github.com/groundsix/asink.git

Multiple remotes can be specified under the remotes key and then are accessed in tasks using the remote key. You can name this remotes whatever you like. In the example it's been named vagrant.

In your output when this is being ran you'll be able to see which remote it is being ran on as it will be highlighted blue and show the name of the remote.