The PreCeive batch client is ideal for bulky datasets, spreadsheets, your own database or just a bunch of Tweets.

The software is open source and is free to use commercially or otherwise.


Download the latest release from or build your own by cloning the repository at

You need your PreCeive REST API credentials handy. If you do not have them, please sign up for a trial licence at PreCeive API Signup.

You will need Java 8 to run the app. Download Java here.

Running the App

Run Scripts

Once you have installed Java, we recommend that you start by running the example scripts that are provided in the bin directory.

Operating System Run Script
Linux, Mac OS X bin/preceive-cli
Windows bin\preceive-cli.bat


NB. For simplicity in the examples below, we use Linux (and Mac OS X) command line commands throughout the documentation.

PreCeive REST API Credentials

To use the PreCeive REST API service, you will need to input your PreCeive account username and password. There are currently two ways to submit your credentials.

1) Your credentials can be specified as explicit command line arguments each time you run the app:

$ bin/preceive-cli -user <username> -password <password> ...

2) Alternatively, you can store your credentials in your environment variables and reuse them later:

Linux, Mac OS X

export THEYSAY_USER=<username>
export THEYSAY_PASSWORD=<password>
bin/preceive-cli ...


bin\preceive-cli.bat ...


The app ships with an example script which illustrate how to submit data from local files to PreCeive REST API.
To run the example script (bin/

$ bin/preceive-cli -user <username> -password <password> -output results/results.json -endpoints /v1/sentiment -batch corpus/getting_started.json corpus/getting_started.tsv corpus/getting_started.json

This command analyses the contents of three example texts by calling the endpoint. The results – i.e. the responses from the PreCeive REST API – will be appended to results/results.json file.

File Formats

For more information about using data from Excel spreadsheets, CSV/TSV, or JSON formatted files, please read the documentation on GitHub.

Command Line Options

For the full list of command line options, type

$ bin/preceive-cli -help

Please also check out the command line documentation.


Andy Pritchard

Andy Pritchard