Qri CLI Quickstart
Let’s take a tour through the Qri Command line client.
First, you’ll need the latest CLI binary. head over to our releases page and install the binary somewhere on your
$PATH. You should be able to type
qri help and see a nice introductory message.
Before we can do useful things with Qri, we need to set it up. So let’s start by running setup:
$ qri setup
Qri will ask you to pick a peername, this is your “handle” on qri. If you don’t want to choose one, just hit enter & Qri will use the random peername shown to you in the prompt. Changing your peername is a bit of a pain, so it’s worth taking the time now to find one that works for you.
Add your first dataset
Now let’s get our first dataset. We’ll start by searching Qri for published datasets we can use.
$ qri search 'world' 1. b5/world_bank_population World Bank Population 138 KBs, 264 entries, 0 errors
Your results may vary, but let’s use this world bank population dataset as an example. To get this dataset onto your computer, add it by referring to it’s name: ‘b5/world_bank_population’.
$ qri add 'b5/world_bank_population' ⠂ fetching 6 blocks 🗼 fetched from registry 1 b5/world_bank_population /ipfs/QmfNtuo5XQvZb3q4zGEpXcrvZRCLPz6SWBz9b44wWGp4N2 Successfully added dataset b5/[email protected]yZ4W/ipfs/QmfNtuo5XQvZb3q4zGEpXcrvZRCLPz6SWBz9b44wWGp4N2
Voila! you now have a world bank population dataset on your computer. All steps after this will operate on data stored locally in your Qri repository.
Let’s look at the dataset we just added by getting an overview of it’s contents, printed in YAML format:
$ qri get b5/world_bank_population
The output of
get can sometimes be a lot to look at. We can select parts of a dataset using
get to look at specific components. For example, the
meta component, this time in json format:
$ qri get meta --format=json b5/world_bank_population
We can also use
get to look at the body of a dataset (aka “the data”), here we’ll limit to a 1-row preview:
$ qri get body --limit 1 b5/world_bank_population
This dataset is in CSV format, let’s convert it to JSON:
$ qri get body --format json --limit 1 b5/world_bank_population
This dataset also includes a transform script that lets it self update. We can see the code for that script by
$ qri get transform.script b5/world_bank_population
get is Qri’s tool for inspecting datasets from the command line. Next let’s look at how to get data out of qri for use elsewhere.
Let’s put that data in a form we can use somewhere else, starting by just getting the “body” csv file. Exporting individual components of a dataset again, just uses
get. Here we write the output to a file called
$ qri get body --all b5/world_bank_population > world_bank_pop.csv
To export a full dataset, use
qri export. Here we’ll export as json:
$ qri export --format=json b5/world_bank_population
Or how about excel:
$ qri export --format=xlsx b5/world_bank_population
From here it’s worth exploring the other commands
qri has for examining & working with datasets. We’ll work on getting more tutorials up (you should totally contribute one!). But in the meantime there are two great resources to explore:
All commands on the CLI have a
--help flag that explains the command and provides examples. exploring help is a great way to learn about what Qri can do, and how it can help you
The Qri team often creates “lesson github repos” that walk through the creation of a dataset or a specific Qri workflow. Head over to try out the tutorials in one of those repos! https://github.com/qri-recipes