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:
-
mainfor the latest stable release -
canaryif 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 feedback@tru.id.
If you haven't already, signup for a tru.ID account, follow @_tru_id on Twitter and join our mission to reimagine mobile authentication.
Latest comments (0)