Announcing the tru.ID CLI

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 or integration into CI/CD workflows.

Using Oclif & Open Source

The tru.ID CLI is built upon the excellent oclif open CLI framework 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 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.

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:

$ npm install -g @tru_id/cli

Or, if you prefer Yarn:

$ 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.

$ 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:

$ tru workspaces

And the output will be similar to:

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:

$ tru projects:create "My Awesome Project"

And you'll see output such as:

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 is an API that queries when the SIM card associated with a phone number last changed:

$ tru simchecks:create

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

? 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. Of course, you can also try this out via our CLI:

$ 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.

? 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:

$ 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, 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:

$ 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 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.

$ tru oauth2:token

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

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:

$ 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 provides two endpoints and is thus a "topic" 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:

$ 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:

$ 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:

$ 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 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 [e-mail].

If you haven't already, signup for a tru.ID account, follow @_tru_id on Twitter and join our mission to reimagine mobile authentication.