Getting started

About this guide

In this guide we'll start your exploration of the Aluma service, first by installing the Aluma CLI and then using the service to do some basic data extraction.

Working through this guide should take about 10 minutes.

Create an Aluma account

If you haven't already, create a Aluma account using the dashboard.

Install the Aluma CLI

  1. Download Aluma CLI for Windows (or follow the Linux or macOS instructions).

  2. Check that installation was successful. Open a command prompt, go to the directory you downloaded to, and enter the following command:

aluma --help

You should see a list of all the commands available in the CLI.


Adding aluma.exe to your PATH

If you want the CLI to be available from the command-prompt whichever directory you are in:

  • create a new directory (e.g C:\aluma or %APPDATA%\local\aluma)
  • add this directory to the PATH
  • move aluma.exe to it.

Connect the CLI to your account

Before you can use the CLI, you need to connect it to your account.

  1. Login to the dashboard
  2. Go to the API Clients page
  3. Click the 'Create API Client' button to create a new client and call it "Aluma CLI client".

Create an API Client (click to enlarge)

  1. Open a command prompt.
  2. Type the following command and paste your Client ID and Secret from the dashboard when prompted:
aluma login

Install example documents

In this guide and the other guides in the documentation we'll use a set of sample documents we've put together to help you understand what Aluma can do.

Before continuing you'll need to install the example documents:

  1. Download the example documents zip archive.
  2. Extract the documents from the archive into a folder named examples. The following steps in this guide and other guides assume that you've created this folder in your terminal/command prompt's current working directory.

Extract data

Now you've connected the CLI to your account, let's do some basic data extraction.

We'll extract the name and social security number from the Dive Record sample documents.


To extract data from documents, we need to create an Extractor which specifies the data we want and how to find it.

There are two different ways to create an Extractor:

  • By using one or more of the available Extraction Modules that capture common types of data, such as dates, reference numbers, names and phone numbers.
  • By creating a custom extractor using the Visual Studio plugin

Alternatively, there are some off-the-shelf extractors available, such as the UK Invoice extractor.

There are modules available for the names and social security numbers we want to capture from these documents.

Enter the following command to create an extractor called dive-record using those modules:

aluma create extractor from-modules dive-record aluma.us_social_security_number

Now let's use it on our documents. Enter the following command to run extraction on all of the documents:

aluma extract dive-record examples/dive-records/*.pdf 

The extract command sends each document to the service and streams results to the console as each file is processed. The documents are processed in parallel, so the order of the results may differ. You will see output like this:

File                   Name                     SSN
dive-record-0001.pdf   Jenna Horton             487-99-4312
dive-record-0002.pdf   Jarod Dunlop             004-31-5237
dive-record-0003.pdf   Mrs Sara R Moose         734-63-2750       
dive-record-0004.pdf   Chris M Spencer          690-07-9479
dive-record-0005.pdf   Margaret J Reinhart      225-19-0469