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:


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


The job is waiting to be run.


The job is currently being run on a compute node.


The job has completed, not necessarily successfully.


The job was cancelled.


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



bclient init -key $KEY

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.


bclient job-create -key $KEY

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.


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.


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

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


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

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


bclient job-info -key $KEY -job-id $JOBID
JobID:      00590758-58b9-c308-b398-c8c93f18475a
Tag:        default
Priority:   1
Timeout:    0
State:      new
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).


bclient job-list-files -key $KEY -job-id $JOBID

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


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.


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.


bclient queue-list-new -key $KEY

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


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


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.