Command Line Tool Usage Guide

Ian Roberts edited this page Jun 10, 2018 · 2 revisions

We provide a command-line tool for easy access to the GATE Cloud APIs for one-off uses or to use in scripts. The tool is open-source and written in Java, and is made available as a single executable JAR file:

The tool requires a Java 8 or later JRE to run.

Running the tool

To run the command-line tool, simply use java -jar:

java -jar gate-cloud-cli.jar <command> <arguments>

The first argument after the JAR file name must be the command you want to run -- if run without arguments the list of available commands is displayed. The first time you use the tool you must start with the configure command in order to provide your API key, which will be stored in a configuration file.

$ java -jar gate-cloud-cli.jar configure

This client requires an API Key to authenticate to the GATE Cloud
APIs.  You can generate one from your account settings page on

API key id: GCNxxxxxxxxxx
API key password: 
Writing configuration to /...../client.conf
Configuration saved successfully.

The password is not echoed to the screen.

Summary of commands

This section is a summary of the most commonly used commands available in the tool. Every command will print a usage message when run without arguments, explaining what parameters it requires and what values they may take (with the exception of commands that do not require any parameters, namely list-jobs and list-items). For the full list of all available commands, simply run gate-cloud-cli.jar with no arguments.


List all the items (i.e. pipelines) available in the shop, optionally filtered by tag

$ java -jar gate-cloud-cli.jar list-items "English"
    ID  Name                              Price
     2  ANNIE Named Entity Recognizer     £0.80 per hour


Reserve an annotation job based on a particular pipeline. The pipeline can be specified by ID (as returned by list-jobs). A name for the new job may optionally be given as a second parameter.

$ java -jar gate-cloud-cli.jar reserve-job 2 "First ANNIE pipeline test"
Successfully reserved job.
  ID: 15
Name: First ANNIE pipeline test


List all your persistent data bundles.

$ java -jar gate-cloud-cli.jar list-bundles
    ID  Name                                      Notes
    27  Uploaded news articles
    35  Results of J-000012 (French web pages ...


Upload files to create a new persistent data bundle that can subsequently be processed by annotation jobs. You can upload several files to a single bundle, but they must all be of the same type (ZIP, TAR, ARC, etc.) and use the same configuration parameters (see the main API documentation).

$ java -jar gate-cloud-cli.jar upload-bundle "Uploaded news articles" \
>    -type ZIP -mimeTypeOverride text/html -encoding ISO-8859-1 \
>    /path/to/news/*.zip
Created bundle 27
Uploading /path/to/news/
Uploading /path/to/news/
Closing bundle...
Bundle 27 uploaded


Configure an annotation job to take input from a data bundle (either one you uploaded yourself or one you created from one of the available data sources on

$ java -jar gate-cloud-cli.jar input-from-bundle 15 27
Configuring job 15 to take input from bundle 27


Define an output specification for a job to write its output to files in a particular format.

$ java -jar gate-cloud-cli.jar add-file-output 15 -type GATE_XML \
>    -extension .gate.xml
Created output


Start a fully-configured job running.

$ java -jar gate-cloud-cli.jar start-job 15


Read the log messages generated by a job as it runs. The -watch option polls the server continuously to display new messages as they appear.

$ java -jar gate-cloud-cli.jar execution-log 15 -watch


Information about a specific job. If the job has finished running this will include the URL to the job's output data bundle.

$ java -jar gate-cloud-cli.jar job-details 15
             ID: 15
           Name: First ANNIE pipeline test
          State: COMPLETED
          Price: £0.80 per hour
   Date created: 03 July 2014 12:37:04 BST
 Date completed: 06 July 2014 13:20:26 BST
    Expiry date: 13 July 2014 13:20:26 BST
  Result bundle:
Processing time: 01:53:10.482 (charged 02:00:00.000 so far) 
 Data processed: 5MiB (charged 0B so far)
   Job progress: 100%


Download all the files in a data bundle to your local machine.

$ java -jar gate-cloud-cli.jar download-bundle \
> (file 1 of 2) (file 2 of 2)


Download supplementary files from a completed job into local files.

$ java -jar gate-cloud-cli.jar download-job-files 15
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.