Announcing the tru.ID CLI
Tags: cli, mobile, security, 2fa
Published: 2021-03-03 01:55:09

As a developer-first and API-first company, we prioritise tools that will make you, the developer, successful. Today we're excited to announce the tru.ID CLI: built on top of our public APIs, open sourced, and your go-to developer tool when building on the **tru.ID** platform.

## Why a CLI?

Many of us spend a lot of time in the terminal, so a CLI enables you to work from where you already are. IDEs such as Visual Studio Code and Android Studio come with in-built terminals. But having a CLI also allows us to build integrations into existing development workflows, via scripts, outside of the IDE. For example, [Xcode behaviours](https://developer.apple.com/library/archive/documentation/ToolsLanguages/Conceptual/Xcode_Overview/CustomizingYourWorkflow.html) or integration into CI/CD workflows.

## Using Oclif & Open Source

The [tru.ID](http://tru.ID) CLI is built upon the excellent [oclif open CLI framework](https://oclif.io/) by Heroku. Oclif provides a foundation for CLI functionality such as subcommands, command arguments and flags, plugin support and lots of utilities that enable us to focus on features instead of building our own CLI framework.

If you'd like to see how we've used Oclif the [**tru.ID** CLI](https://github.com/tru-ID/tru-cli) is on GitHub. Within the GitHub repo you'll find two branches:

- `main` for the latest stable release
- `canary` if you'd like to try out the latest features

We'd love to hear what you think so please ask questions, share ideas and raise PRs on the [tru-ID/cli repo](https://github.com/tru-ID/tru-cli/issues).

## Install and Setup the **tru.ID** CLI

For the moment the only installation option is via NPM so you'll need Node.js installed.

With Node.js installed you install the **tru.ID** CLI as follows:

```bash
$ npm install -g @tru_id/cli
```

Or, if you prefer [Yarn](https://yarnpkg.com/):

```bash
$ yarn global add @tru_id/cli
```

To try out the latest features use `@tru_id/cli@canary`.

With the `tru` command installed, setup the CLI with the credentials you'll find within the [**tru.ID** console](https://tru.id/console).

```bash
$ tru setup:credentials {client_id} {client_secret} eu
```

`eu` is the region where your account data is stored and, at the time of this blog post, is the only region we have available (more coming soon).

You can now query the credit you have available using:

```bash
$ tru workspaces
```

And the output will be similar to:

```bash
credentials.client_id                data_residency balance.amount_available balance.currency created_at
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx EU             28                       API              2020-08-12T12:46:56+0000
```

## Creating a **tru.ID** Project

Projects are configuration containers within the **tru.ID** platform and you'll normally have a one-to-one mapping of a tru.ID project to an application that you are developing (though you may also create a project per environment: `dev`, `staging` and `prod`). A key piece of configuration are the project `credentials` which contain a `client_id` and `client_secret` that you use to authenticate interactions with the tru.ID APIs.

You create projects using the CLI:

```bash
$ tru projects:create "My Awesome Project"
```

And you'll see output such as:

```bash
Creating Project "My Awesome Project"
Project configuration saved to "~/my_awesome_project/tru.json".
```

The `tru.json` file contains your project configuration including the project credentials. Don't check this into source control!

With a project created you can `cd my_awesome_project` so the CLI can read the `tru.json` file from the `cwd` and you have everything you need to fully utilise the **tru.ID** CLI.

## Trying the tru.ID APIs

CLIs normally focus on platform management functionality, such as creating and managing projects, but we decided to also add commands to let you try out our products from the terminal. Of course, you can also try these out programmatically too.

### SIMCheck

[SIMCheck](https://tru.id/docs/sim-check) is an API that queries when the SIM card associated with a phone number last changed:

```bash
$ tru simchecks:create
```

With the output being similar to the following, which prompts for the phone number to be checked:

```bash
? Please enter the phone number you would like to SIMCheck +{phone_number}
Creating SIMCheck for +{phone_number}

	status: COMPLETED
	no_sim_change: true
	last_sim_change_at: 2017-01-26T07:16:57+0000
```

The `no_sim_change` value indicates that the SIM card hasn't changed within the last seven (7) days, and `last_sim_change_at` specifies the last change date (when I changed my mobile phone provider from giffgaff UK to EE UK).

### PhoneCheck

PhoneCheck verifies that a phone number is associated with a SIM card within the mobile device. This is achieved via tru.ID's integration with MNOs (Mobile Network Operators) around the world. For a more in-depth look at how this works, check out the [PhoneCheck integration guide](https://tru.id/docs/phone-check/integration). Of course, you can also try this out via our CLI:

```bash
$ tru phonechecks:create --workflow
```

The output of this command prompts for a phone number and also displays a QR code to scan on a mobile device. It also provides instructions to disable WiFi on the device, as part of the PhoneCheck workflow is to make a web request over the device's mobile data connection.

```bash
? Please enter the phone number you would like to PhoneCheck +{phone_number}
Creating PhoneCheck for +{phone_number}
PhoneCheck ACCEPTED
check_id: 76a36abb-8495-403a-9f71-531c80c6a26b
check_url: https://eu.api.tru.id/phone_check/v0.1/checks/76a36abb-8495-403a-9f71-531c80c6a26b/redirect
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
█ ▄▄▄▄▄ █▄█  ██ ▄███ ▀▄▄ ▄▀█ ██ ▄  ▀██▀█▀▀  █  ▄ ██ ▄▄▄▄▄ █
█ █   █ █ ▄▀▄ █▄█▄█▀█████ ▄█ ██▄▄▄▄█▀▀█▀ █ ▀█▄▀▄ ██ █   █ █
█ █▄▄▄█ █▄ █▀  ▀▀▀   ▀▀  ▀█ ▄▄▄   ▄█▄▄   ▀ ▀▄▄▄▀▄██ █▄▄▄█ █
█▄▄▄▄▄▄▄█▄▀▄█▄█▄█▄█▄▀▄█▄█ ▀ █▄█ █▄█ ▀▄▀ ▀ ▀ ▀▄█ ▀▄█▄▄▄▄▄▄▄█
█    ▀▀▄▀▄▄▀▄▀▀█▄▄ ▀▄▄  ▀ ▄ ▄▄▄  ███ █▀██ ▀▀ ▀▀▄▄  ██ ▄▄▀▄█
███▀▄▀▄▄█▄ ▀   ▀██ ██▄▄▄▀ ▄▄██▀ █▄ ▀ ▀▀▄ ▄ ▀█ ▄  ▄████ █  █
█▀▄█ ▀▀▄█▀ ▄█▄▄ █▄█▄  █▄▄██ █▀▄▄ ▀ ▄▀▄   ▀▄▄▀▀ ▄▄█▄▀▄▀ █▄▄█
█▄██ ▄ ▄▄ ▄▀▀▀▀█ ▄▀██▄▄▀▀ ▄▄▄█ ▄▄ ██▄█ █▀ █ █ ▄█▀▀ ▄▀▀▀ █▀█
█▄▀▀▄██▄█▄▄▄  ▄▄▄ █▀██▄█ ▄ █▄█ ▄▄▄▄ ▀█▀▄▀▀▄▄▄▄▄  ▄ █ █▄██ █
█ ▀ ▄ ▀▄▄▀  █▄▀▀ ▄  ██▀█▀▄▀ ▄█ ▀██▀▄█▀▄ █▀▀█▀█▀  ▀▀▄▀▀▀█▀▀█
███ ▄▀ ▄ ▀  ▀▀ ██ ▄███  ▀ ▄▀▄ █▀██▄▄▀▀███ ▄ ▀▀ ▄▀ █▄█▄▀ █▀█
█▀▄ ▀██▄▀ █ ▀█ ▄▀▄ █ ▄  ▀███▄▄█▄█▄▄▄█▀▄▀█▀▀ ▄█  █▄▀▀█▄██▄ █
█▀▄██ ▄▄ ▄ █ ▀ ▄█▄   ▀█▀█▄ ▀█▀▀█▄▀ █▄▄ ▀███▄▄█ ██▄  ▀█▄█▄▄█
██▄▀  ▄▄▄ ▀▀ ▀█▀▀ ▄▄▄▀█▄█ ▄ ▄▄▄   █▄▀██▄▀▀█▄▄▀▄▄▀ ▄▄▄ ▀▀▀▀█
█ ▀ ▄ █▄█ ▀█▀ ▄▀▀ █▄██▀▀ █▀ █▄█ ▄▄ ▀█▀ ▄▄▀ ██▄▄▀▄ █▄█ ▀▄▀ █
██▀▀█ ▄▄  ██▄▄█▄ ▄█▀ ▀█ ▀█▄  ▄▄  ▄█▄▄ █  ▀▄▀██ ▄▄  ▄ ▄██ ▀█
█ ▄██ ▄▄ ███▀█▄█▄███ ▄    █▄▀█ █ ▀ ▄▀▀▄██▄▄▀█▀██▀█▀▄ █▀▄▄▀█
██▄   ▀▄█▀▄ ▄▀██▀  ▀ █▄▀ ▄▄█ ▀███ █ █  █▀▄█▄▄ █▄█▀█ ▄ ███▄█
█▄██▀ █▄█▄▄█ ▄█▀███ ▀██▀█▄█▄ ▄ ▄ ▀ █▀ █ ██▄▄█▀▀█▀▀▄▄▀█ ▀▀██
█▀▄█▄▄▄▄▄█  █ ██ ▄▀▄  ▄▀▀ ▀ ▄▄ █ ▀█▀ ▀█ █▄▀ ▀▀██▀ █▀▄█ ▀█▄█
█▀▄█ █▄▄▀ █▀▀ █▀  ▀▀██▄▀█▄▀▄▀▀▄██▄▀▀████ ▀ ██▄ ▀▄█▄▀▄ ▀██▄█
██  ▀▀▄▄▀ ▄ ▄██▄▀▀█▄▀ █ ▄▄▄     ▄█ ▄  ▀   █▄ ▄ ▀██ █ ██▄▄▀█
█▀▄▀▄█▀▄ ▀▀ █ ▄▀ █▀▀ ▄ █▄ ▄  █▀█▀▀ ▄████▀▄▀▀ ▀███▄ ▀██▄ ▄ █
█ ▀ ▀▀▄▄▄ ██▀▄▀   ▀█▀█ ▀▀█  ▄ ███▀▀▄▄▀ █▀▄█ ▄ █  █▀ ██▀▄  █
███████▄█▀▀▄ ▀▄█ ██ ▀ ▀██▄▀ ▄▄▄ ▀▀███▄  ▄█▀▄▀███▀ ▄▄▄ ▀▀ ██
█ ▄▄▄▄▄ ██ █ █▄█▀█  ▀ ███ ▄ █▄█ █▀▄▀█▀ ▄▄ ▄ ▄▀▄█▄ █▄█ █▀▄▀█
█ █   █ █▀ █▀▄ █▀█ ▀ ▄ █▀▄▀  ▄▄   ▀▀█▀██▄▀█▄▄▄█   ▄▄ ▄▀▄ ██
█ █▄▄▄█ █ █▄▄▄▀▀  ▄▄▄▀▄ ▀ ▀▀█▀██ ▄  ▀ █ ██▄██▄▀▄▀ █▀███▄█▀█
█▄▄▄▄▄▄▄█▄▄▄▄▄▄▄█▄▄██▄▄▄█████▄▄███▄▄▄██▄▄▄▄▄██▄▄▄██▄█▄▄▄███

Please ensure the mobile phone with the phone number +{phone_number} is disconnected from WiFi and is using your mobile data connection.

Then scan the QR code and navigate to the check_url.

Waiting for a PhoneCheck result... done

PhoneCheck Workflow result:
	status:  COMPLETED
	match:  true ✅
```

QR codes in the terminal. Pretty cool, huh!

As well as creating resources you can also query existing ones:

```bash
$ tru phonechecks:list 76a36abb-8495-403a-9f71-531c80c6a26b
check_id                             created_at               status    match charge_currency charge_amount
76a36abb-8495-403a-9f71-531c80c6a26b 2021-02-23T21:08:56+0000 COMPLETED true  API
```

You can also try out `tru phonechecks:list` with flags such as `--search` to add query conditions the API request, `--filter` to filter a result from the API, and `--output` to change the output format e.g. `--output json`.

### SubscriberCheck

The CLI also supports [SubscriberCheck](https://tru.id/docs/subscriber-check), which runs a PhoneCheck but also includes a SIMCheck within the result. We'll leave trying that out to you, but here's the creation command that runs through the QR code workflow:

```bash
$ tru subscriberchecks:create --workflow
```

## What Else Can the CLI Do?

Two other commands worth highlighting are `oauth2` and `coverage`.

### OAuth2

Our APIs use OAuth2 credentials and access tokens for authentication. But we know that sometimes you just want access to an access token without having to concatenate a project `client_id` and `client_secret`, Base 64 encode that value, make a request to the [`/token` endpoint](https://tru.id/docs/reference/api#operation/oauth2-token) to create an access token, and then eventually getting to use it. So, the `oauth2` command makes it a bit easier to create an access token when you're just trying things out.

Note: Running the following command from a directory that contains a `tru.json` project configuration file will use the credentials for the project. If you run the command without a `tru.json` in the `cwd` you'll use the credentials you supplied in the `tru setup:credentials` command.

```bash
$ tru oauth2:token
```

Then you just need to copy the access token and use it:

```bash
access_token
GXuXq1DKa2LdBikD0jC8DenJgJTdgPSONLC0TpYqIzQ.ko9hRxKojOYhSvWkUBsPtHNPSUtB5KMwCqw8_FjUW6c
```

You can also assign the output to a variable and use it either in a mobile client or to try things out via cURL:

```bash
$ TOKEN=$(tru oauth2:token --no-header)
$ curl -s -X GET \
-H "Authorization: Bearer $TOKEN" \
https://eu.api.tru.id/phone_check/v0.1/checks/76a36abb-8495-403a-9f71-531c80c6a26b
{"check_id":"76a36abb-8495-403a-9f71-531c80c6a26b","status":"COMPLETED","match":true,"charge_amount":1.00,"charge_currency":"API","created_at":"2021-02-23T21:08:56+0000","updated_at":"2021-02-23T21:09:26+0000","_links":{"self":{"href":"https://eu.api.tru.id/phone_check/v0.1/checks/76a36abb-8495-403a-9f71-531c80c6a26b"}}}%
```

### Coverage

[Coverage](https://tru.id/docs/reference/api#tag/coverage) provides two endpoints and is thus a ["topic"](https://oclif.io/docs/topics) with two commands in the CLI.

`coverage:country {country_code}` allows you to query if the **tru.ID** platform has coverage for a given country. You can use either a phone number [country code prefix](https://en.wikipedia.org/wiki/List_of_country_calling_codes):

```bash
$ tru coverage:country +44
product_name     network_id network_name currency amount
Phone Check      23410      O2 UK        API      1
Phone Check      23415      Vodafone UK  API      1
Phone Check      23420      3 UK         API      1
Phone Check      23430      EE UK        API      1
Sim Check        23410      O2 UK        API      1
Sim Check        23415      Vodafone UK  API      1
Sim Check        23420      3 UK         API      1
Sim Check        23430      EE UK        API      1
Subscriber Check 23410      O2 UK        API      1
Subscriber Check 23415      Vodafone UK  API      1
Subscriber Check 23420      3 UK         API      1
Subscriber Check 23430      EE UK        API      1
```

Or a [two-letter alpha country code](https://www.iban.com/country-codes):

```bash
$ tru coverage:country CA
product_name network_id network_name currency amount
Phone Check  302220     Telus        API      1
Phone Check  302610     Bell         API      1
Phone Check  302720     Rogers       API      1
```

`coverage:reach` also performs a **tru.ID** platform coverage query but based on the IP address (IPv4 or IPv6) of the device:

```bash
$ tru coverage:reach 213.205.197.123
network_id network_name country_code supported_products
23430      EE UK        GB           Phone Check,Sim Check,Subscriber Check
```

## Try out the CLI and let us know what you think

In this post we've covered a number of the main commands but there's more that the CLI offers. Either install the **tru.ID** CLI (`npm install -g @tru_id/cli`) and `tru --help` to find out more, or take a look at the [CLI Reference docs](https://tru.id/docs/reference/cli) to see what else is possible.

We believe the **tru.ID** CLI offers a good first developer experience of our platform. But we'd love to know what you think via <a href="mailto:feedback@tru.id?subject=CLI Feedback">feedback@tru.id</a>.

If you haven't already, [signup for a **tru.ID** account](https://tru.id/signup), [follow @_tru_id on Twitter](https://twitter.com/_tru_id) and join our mission to reimagine mobile authentication.