Command Line Interface

Download the command line client here.

Interacting with your cluster is accomplished by means of a command line tool bclient. bclient takes care of storing IP addresses and TLS certificates to allow straightforward management of your jobs.

Standard usage take the form

bclient command [OPTIONS]...

To get help on any command, type

bclient command -help

Job States

A job can be in one of the following states:

new

The job was created, but won’t be run until it is queued.

queued

The job is waiting to be run.

running

The job is currently being run on a compute node.

completed

The job has completed, not necessarily successfully.

cancelled

The job was cancelled.

Failed

The job failed to complete. See job-info for details.


Error Codes

The command line client will return error codes in various situations. These are

Code Description
0 Success
1 Unknown internal error in bclient
2 The command wasn’t understood
3 The cluster isn’t active
4 Local filesystem error
32 Unknown internal networking error
33 Transport error
34 Bad command arguments
64 Not authorized (master server)
128 Unknown internal error on head node
129 Not authorized (head node)
130 File system error (head node)
131 Item not found
132 Invalid path
133 Invalid tag

Commands

init

KEY=your-clusters-api-key
bclient init -key $KEY
IP Address: XXX.XXX.XXX.XXX

The init command will contact the master server and get the IP address and public certificate for the cluster with the given API key. This is stored for subsequent commands.

job-create

bclient job-create -key $KEY
00590758-58b9-c308-b398-c8c93f18475a

The job-create command will create a new job on the cluster and return its unique job ID. This command accepts options for the job’s priority, a tag, and an optional timeout in seconds. The job will be in the new state.

job-enqueue

bclient job-enqueue -key $KEY -job-id $JOBID

The job-enqueue command will only affect a job in the new state an put it in the queued state.

job-delete

bclient job-delete -key $KEY -job-id $JOBID

The job-delete command will delete a job and its files.

job-cancel

bclient job-cancel -key $KEY -job-id $JOBID

The job-cancel command will cancel a job. The job state will be cancelled.

job-info

bclient job-info -key $KEY -job-id $JOBID
JobID:      00590758-58b9-c308-b398-c8c93f18475a
Tag:        default
Priority:   1
Timeout:    0
State:      new
Msg:
EnqueuedAt: 0
StartedAt:  0
FinishedAt: 0
ResultCode: 0

The job-info command retrieves the information regarding the current job.

The times EnqueuedAt, StartedAt, and FinishedAt are displayed as unix timestamps (seconds since Thursday, 1 January 1970).

job-list-files

bclient job-list-files -key $KEY -job-id $JOBID
output.txt
run.sh

Lists all files in the job’s directory on the server.

job-upload

bclient job-upload -key $KEY -job-id $JOBID -job-dir jobdir

The job-upload command uploads all files in the specified directory into the job’s directory on the cluster.

job-download

bclient job-download -key $KEY -job-id $JOBID -job-dir jobdir

The job-download command downloads all files from the job’s directory on the cluster to a local directory. By default it won’t overwrite files.

queue-list-new

bclient queue-list-new -key $KEY

List jobs in the new state. You can optionally provide a tag.

queue-list-queued

Same as queue-list-new, but lists jobs in the queued and running states.

queue-list-completed

Same as queue-list-new, but lists jobs in the completed, cancelled, and failed states.


Language Integration

The command line interface was designed to make writing language specific wrappers simple. Arguments are used consistently throughout, and the output is simple to parse.

Head Node Failure

In the event that the head node fails, it will be replaced with a new server having a new IP address and private certificate. In this case the command line client would need to call the init command again.

Executing a command on a failed head node will likely result in either of error codes 32 or 33.

A simple strategy when encountering a suspected failed head node is to retry the init command in a loop with a minute or two of sleep between each attempt. The init command will succeed when the head node is available again.