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:
- gate-cloud-cli.jar (1.7MB)
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 Configuration ------------- This client requires an API Key to authenticate to the GATE Cloud APIs. You can generate one from your account settings page on %(https://cloud.gate.ac.uk/). 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.
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 ...
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
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 Processing file1.zip Created https://cloud.gate.ac.uk/api/job/15/input/57 Processing file2.zip Created https://cloud.gate.ac.uk/api/job/15/input/58 Done
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 www.bbc.co.uk \ > -pathPrefix /news Created input https://cloud.gate.ac.uk/api/job/15/input/7 Starting search... ..1210.3739.6221.9484.12616.15104.16040 Search complete: 16040 item(s) found.
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 https://cloud.gate.ac.uk/api/job/15/output/12
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 disply new messages as they appear.
$ java -jar gate-cloud-cli.jar execution-log 15 -watch
Download all the results from a completed job into local files.
$ java -jar gate-cloud-cli.jar download-all-results 15