# Flo.w CLI

# Introduction

The Flo.w CLI is a command-line tool for developers working with Flo.w Engine and creating Flo.w applications.

The CLI provides commands for working with Flo.w resources such as api-keys, datasets and tile sources. It also allows a developer to upload geospatial data to create new Flo.w datasets and tile sources.

Many of the commands provide an interactive mode, which guides the developer through the operation using a series of prompts. Non-interactive mode is also available when using the CLI tool from shell scripts.

The Flo.w CLI interacts with Flo.w Engine by issuing requests to the Flo.w Engine REST API on behalf of the developer.

# Prerequisites

We recommend using a Node version manager to install Node.js and NPM:

nvm (opens new window) for Mac and Linux.
nvm-windows (opens new window) for Windows.

# Quick Start

To install the Flo.w CLI as a global package perform the following command:

npm install -g flow-engine-cli

Create a .flowrc.json configuration file in your home directory:

// .flowrc.json
{
  "host":"https://flow.emu-analytics.net",
  "apiKey":"b6b77cc4-904a-46d1-aa0f-3bf3848ce4c7"
}

To check that installation has succeeded, run the following command:

# Display version information
flow version

You should see the following version information as output:

╔═══════════════╤══════════════════════════════════════╗
║ Property      │ Value                                ║
╟───────────────┼──────────────────────────────────────╢
║ CLI version   │ 1.0.45                               ║
╟───────────────┼──────────────────────────────────────╢
║ Flo.w version │ v1.0.49                              ║
╟───────────────┼──────────────────────────────────────╢
║ Flo.w host    │ https://flow.emu-analytics.net       ║
╟───────────────┼──────────────────────────────────────╢
║ API key       │ b6b77cc4-904a-46d1-aa0f-3bf3848ce4c7 ║
╚═══════════════╧══════════════════════════════════════╝

Run the following command to list Flo.w Datasets associated with the Flo.w demo application:

# List datasets
flow datasets ls

You should receive a list of defined Datasets:

╔════╤════════════════════════╤═══════════════════════════╤══════════════════════════════════════╤═══════╗
║    │ id                     │ name                      │ description                          │ type  ║
╟────┼────────────────────────┼───────────────────────────┼──────────────────────────────────────┼───────╢
║ 1  │ airquality             │ Air Quality               │ Air quality measurements in London   │ table ║
╟────┼────────────────────────┼───────────────────────────┼──────────────────────────────────────┼───────╢
║ 2  │ airquality_with_params │ Parameterized air quality │ Returns records with NO2 > {{no2_fil │ sql   ║
║    │                        │ query                     │ ter}}                                │       ║
╟────┼────────────────────────┼───────────────────────────┼──────────────────────────────────────┼───────╢
║ 3  │ greenspace             │ Green Space Index         │ England green space index by LSOA    │ sql   ║
╟────┼────────────────────────┼───────────────────────────┼──────────────────────────────────────┼───────╢
║ 4  │ london_boroughs        │ London Boroughs           │ London borough polygons              │ table ║
╟────┼────────────────────────┼───────────────────────────┼──────────────────────────────────────┼───────╢
║ .. │ ...                    │ ...                       │ ...                                  │ ...   ║
╟────┼────────────────────────┼───────────────────────────┼──────────────────────────────────────┼───────╢

To get a list of top-level commands, run:

# List top level commands
flow --help

For additional help on a command or sub-command, use the --help option with the command:

# Get help on the 'datasets update' command
flow datasets update --help

# Configuration

Flo.w CLI uses a configuration file (.flowrc.json) for common options such as the Flo.w Engine host URL and API key. When run, the CLI will search for a .flowrc.json file starting in the current directory and moving upwards until a configuration file is found. In practice, you will place a global .flowrc.json file in your home directory and project-specific configuration files in project sub-directories.

At a minimum, the .flowrc.json configuration file should specify host and apiKey to provide credentials for accessing Flo.w Engine. Additional options can be set using the long form of the option name displayed in the command help text.

// .flowrc.json
{
  "host":"https://flow.emu-analytics.net",
  "apiKey":"b6b77cc4-904a-46d1-aa0f-3bf3848ce4c7"
}

Options can also be set using environment variables. Prefix the long form of the option name with FLOW_. This is useful for temporarily switching API key in a command shell:

# Switch API key
export FLOW_API_KEY=xxxx-xxxxx-xxxx-xxxx-xxxxx

# Switch Flo.w Engine host
export FLOW_HOST=http://locahost:3000

Configuration precedence

The precedence for resolving command options is:

Command line options > environment variables > .flowrc.json options

# Commands

The following top-level commands are available:

Command	Abbreviation	Description
`apikeys`		View and manage Flo.w API keys
`applications`	apps	View and manage Flo.w applications *
`databases`	dbs	View and manage databases
`datasets`	ds	View and manage datasets
`new`		Create a new application project from a template
`styles`		View and manage map styles
`tiles`		Preview and manage map tile sources
`upload`		Upload geospatial data to create a new dataset and tile source
`users`		View and manage users
`version`		View Flo.w Engine and CLI version information

* Certain operations require a master API key

Most top-level commands provide sub-commands. To view available sub-commands use the --help option with a top-level command, for example:

# Get help on 'datasets' sub-commands
flow ds --help

# Common Tasks

# Uploading Data

Use the upload command to upload geospatial data files. See Uploading Data for more details.

# Working with Datasets

The flow datasets top-level command is used to work with Flo.w Datasets. It can be abbreviated as flow ds. The following sub-commands are available:

Sub-Command	Abbreviation	Description
`attributes`	attrs	List dataset attributes
`create`		Create a new dataset
`delete`	rm, del	Delete a dataset
`list`	(default sub-command, can be omitted)	List datasets
`query`		Query a dataset
`update`		Update a dataset

The create and update sub-commands provide an interactive mode allowing the operation to be performed by following a set of prompts.

# Querying Datasets

Use the query sub-command to query a dataset. The following options can be used:

Option	Description
`--format`	Format of results (`table` - default, `json`, `geojson`, `csv`)
`--limit`	Limit the number of returned results
`--offset`	Offset the returned results
`--query`	Specify a JSON-formatted Flo.w Query Definition
`--explain`	Return the generated SQL and query plan
`--params`	Supply parameters for parameterized Flo.w Dataset queries

# Example queries

# Simple query
flow ds query airquality --limit 10

# Output
#╔═══╤═════╤══════════════════════════╤═══════════════════════════════╤═══════╤══════════╗
#║   │ no2 │ timestamp                │ name                          │ label │ geometry ║
#╟───┼─────┼──────────────────────────┼───────────────────────────────┼───────┼──────────╢
#║ 0 │ 60  │ 2006-12-31T22:59:59.000Z │ Kingston - Kingston Bypass A3 │ A30   │ <object> ║
#╚═══╧═════╧══════════════════════════╧═══════════════════════════════╧═══════╧══════════╝

# JSON Output
flow ds query airquality --limit 1 --format json

# Output
#[
#  {
#    "no2": 60,
#    "timestamp": "2006-12-31T22:59:59.000Z",
#    "name": "Kingston - Kingston Bypass A3",
#    ...
#  }
#]

# Query definition
flow ds query airquality --query '{"where":{"name":{"$like":"Ba%"}}}'

# Output
#╔═══╤══════╤══════════════════════════╤══════════════════════════════════════╤═══════╤══════════╗
#║   │ no2  │ timestamp                │ name                                 │ label │ geometry ║
#╟───┼──────┼──────────────────────────┼──────────────────────────────────────┼───────┼──────────╢
#║ 0 │ 23   │ 2017-12-31T22:59:59.000Z │ Barking and Dagenham - Rush Green    │ BG1   │ <object> ║
#╟───┼──────┼──────────────────────────┼──────────────────────────────────────┼───────┼──────────╢
#║ . │ ...  │ ...                      │ ...                                  │ ...   │ ...      ║
#╚═══╧══════╧══════════════════════════╧══════════════════════════════════════╧═══════╧══════════╝

# Working with Tile Sources

The flow tiles top-level command is used to work with Flo.w Tile Source. The following sub-commands are available:

Sub-Command	Abbreviation	Description
`create`		Create a new tile source
`delete`	rm, del	Delete a tile source
`list`	(default sub-command, can be omitted)	List tile sources
`preview`		Preview a tile source in the Maputnik (opens new window) map editor
`tilespec`		View the standard TileJSON specification (opens new window) for the tile source
`update`		Update a tile source

The create and update sub-commands provide an interactive mode allowing the operation to be performed by following a set of prompts.

# Previewing a Tile Source

A tile source is a representation of a Flo.w Dataset as a set of vector map tiles. To preview the tile source, use the flow tiles preview [tilesource-id] command and open the returned preview URL in your browser.

# Preview a tile source in Maputnik
flow tiles preview airquality

Tile Source Preview in Maputnik

← Querying Datasets Flo.w Client Library →