GATE Cloud command-line client

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 7 or later JRE to run. Source code and documentation are available as part of the Java client library on GitHub.

1. 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: AMCxxxxxxxxxx
API key password: 
Writing configuration to /...../client.conf
Configuration saved successfully.

The password is not echoed to the screen.

2. 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.

2.1. list-items

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
     3  GATE Cloud News Pipeline          €0.80 per hour

2.2. reserve-job

Reserve an annotation job based on a particular pipeline. The pipeline can be specified by ID (as returned by list-jobs) or simply by copying and pasting the URL given on the web shop detail page for the pipeline. A name for the new job may optionally be given as a second parameter.

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

2.3. upload-inputs

Upload one or more local files to be used as inputs for a job. You can upload several files in one invocation, 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-inputs 15 -type ZIP \
>   -encoding UTF-8 -fileExtensions ".html, .xml" *.zip

2.4. common-crawl

Create an input specification for a job by searching the Common Crawl corpus. This command waits until the search is complete, and you can interrupt the search by pressing ctrl-C if it is clearly matching too many documents.

$ java -jar gate-cloud-cli.jar common-crawl 15 -hostname \
>    -pathPrefix /news
Created input
Starting search...
Search complete: 16040 item(s) found.

2.5. add-file-output

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

2.6. start-job

Start a fully-configured job running.

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

2.7. execution-log

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

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

2.8. download-all-results

Download all the results from a completed job into local files.

$ java -jar gate-cloud-cli.jar download-all-results 15