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

reserve-job

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-bundles

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-bundle

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/part01.zip
Uploading /path/to/news/part02.zip
Closing bundle...
Bundle 27 uploaded

input-from-bundle

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 https://cloud.gate.ac.uk).

$ java -jar gate-cloud-cli.jar input-from-bundle 15 27
Configuring job 15 to take input from bundle 27
Created https://cloud.gate.ac.uk/api/job/15/input/206

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 https://cloud.gate.ac.uk/api/job/15/output/12

start-job

Start a fully-configured job running.

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

execution-log

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

job-details

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: https://cloud.gate.ac.uk/api/data/bundle/35
Processing time: 01:53:10.482 (charged 02:00:00.000 so far) 
 Data processed: 5MiB (charged 0B so far)
   Job progress: 100%

download-bundle

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

$ java -jar gate-cloud-cli.jar download-bundle \
>    https://cloud.gate.ac.uk/api/data/bundle/35
part01.zip-out.zip (file 1 of 2)
part02.zip-out.zip (file 2 of 2)

download-job-files

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.