Using the CLI

Showing the effective requests in curl is cool but something that might be even cooler would be to do the same things with a simple cli¹!

Installation

info

You need Node.js installed. The simpler way to do that is to install nvm:

# Install nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install current LTS version of Node.js:
nvm i 14

To install the datastore cli, execute the following command:

npm install -g @getanthill/datastore@latest

Check the installation with

which datastore
# home/alicecooper/.nvm/versions/node/v14.4.0/bin/datastore
which ds
# home/alicecooper/.nvm/versions/node/v14.4.0/bin/ds

Basics

By default, the cli will try to communicate with a datastore deployed locally available on the port 3001 and with a valid authorization token token².

So, if your datastore is running, you can start using the cli with:

ds --help
# Usage: ds [options] [command]
# 
# Options:
#   -v, --vers                         output the current # version
#   -h, --help                         display help for # command
# 
# Commands:
#   heartbeat                          Check the availability # of the service
#                                      (/heartbeat)
#   users
#   stream [options] <model> <source>  Stream entities # changes or events
#   help [command]                     display help for # command

Starting with the heartbeat is always a good practice, so let's try the command:

ds heartbeat
# { state: 'up' }

What a surprise!

Playing with entities

Let's now play with the cli on the users model:

ds users create --firstname Eve
# {
#   created_at: '2021-10-28T20:04:36.70`0Z',
#   firstname: 'Eve',`
#   updated_at: '2021-10-28T20:04:36.70`0Z',
#   version: 0,`
#   user_id: '617b025406ff040013a7214f'`
# }

for simpler than writing the curl request again and again and again.

We can use the cli with jq to increase our productivity a lot! Let's say we have 4 users, all from the same family but we missed adding the lastname to their documents #lifeismovingfast. Let's try the following command using ds, jq and xargs:

ds users find --format json --fields user_id | \
  jq -r '.[].user_id' | \
  xargs -i{} ds users update {} --lastname Doe
# {
#   created_at: '2021-10-28T20:06:42.144Z',
#   firstname: 'Alice',
#   updated_at: '2021-10-28T20:11:04.522Z',
#   version: 1,
#   user_id: '617b02d206ff040013a72151',
#   lastname: 'Doe'
# }
# ...

All the documents have been update with the exact same field lastname=Doe and are now in version=1.

--help

The JSON Schema you defined in you model is automatically linked and applied to the cli so you can use it without any fear: the contract is always strictly validated.

ds users create --help
# Usage: ds users create [options]
# 
# Create a new entity for users
# 
# Options:
#   --user_id <user_id...>   Correlation field
#   --json <json>            JSON Query
#   --firstname <firstname>  Firstname of the user
#   --lastname <lastname>    Lastname of the user
#   --debug                  Debug the request (default: false)
#   --dry-run                Simulate the request without executing it # (default: false)
#   --format <format>        Response format
#   -h, --help               display help for command

and

ds users find --help
# Usage: ds users find [options]
# 
# Get available entities for users
# 
# Options:
#   --user_id <user_id...>   Correlation field
#   --json <json>            JSON Query
#   --firstname <firstname>  Firstname of the user
#   --lastname <lastname>    Lastname of the user
#   --debug                  Debug the request (default: false)
#   --dry-run                Simulate the request without executing it # (default: false)
#   --format <format>        Response format
#   --fields <fields...>     Response format
#   --sort <sorts...>        Response format
#   --must-hash              Remove the hash request
#   --page <page>            Page (default: "0")
#   --page-size <page-size>  Page size (default: "20")
#   -h, --help               display help for command

--format json

By default, the output is displayed fine if you need to pipe the output, you can use the --format json option. For example, with jq, you can filter results properties:

Using the --format json option

ds users find --format json | \
  jq '.[] | {firstname: .firstname, lastname: .lastname}'
# {
#   "firstname": "Alice",
#   "lastname": "Doe"
# }
# {
#   "firstname": "Bernard",
#   "lastname": "Doe"
# }
# {
#   "firstname": "Charly",
#   "lastname": "Doe"
# }
# {
#   "firstname": "Dorothy",
#   "lastname": "Doe"
# }

--fields <fields...>

In the find command, you can request only the fields that you need with the option --fields. An equivalent command to the previous one would be:

Using the --fields option

ds users find --fields firstname lastname --format json | jq
# {
#   "firstname": "Alice",
#   "lastname": "Doe"
# }
# ...

---

1. Commmand-line Interface↩
2. https://gitlab.com/getanthill/datastore/-/blob/master/src/sdk/cli.ts#L20↩