Qri CLI Quickstart
Follow these steps to get started with Qri’s Command Line Interface. To see the same workflow using a GUI, see Qri Desktop Quickstart
qri commands to be available in your terminal, you must have the Qri binary installed through one of the following methods:
- Install a Mac, Windows, or Linux build of Qri
- Homebrew installation (macOS only):
brew install qri-io/qri/qri
- Install a Windows or Linux build of Qri
- Build Qri from source
Before you can use Qri, you must run
qri setup. This sets your cryptographic keys, auto-generates a username, and initializes the Qri environment on your computer.
$ qri setupchoose a peername: [persimmon_cane_corso]:set up qri repo at: ~/.qri
If you already have a Qri Cloud account, you need to connect your username with your CLI keypair.
If you do not have an account, sign up. Your new credentials will be stored for CLI use.
$ qri registry prove --username foo --password applesauce
While it’s possible to use Qri without an account, signing up ensures that your username is unique and gives you access to Qri Cloud for one-click data publishing. Choose a good username, it will be used to reference each of your datasets on the Qri network.
$ qri registry signup --username foo --email [email protected].io --password applesauce
At this point you’ve created an identity but don’t yet have any datasets in your collection
qri list to show your sad, empty dataset collection.
$ qri listfoo has no datasets
Let’s add some data!
To create your first dataset, start with a CSV. If you don’t have one handy you can use this dataset of all earthquakes in the last week from the U.S. Geological Survey.
First, create an empty directory on your filesystem to store the dataset's working files. Give the directory a descriptive name for the dataset.
Navigate to your empty dataset directory and run
qri init with the
--source-body-path flag to import your CSV and create a new dataset. Qri will ask you to name your dataset. The dataset name may consist only of lowercase letters, numbers, and underscores/hyphens, and must be 100 characters or fewer. See Naming Datasets for more on Qri naming conventions.
$ cd ~/datasets/usgs_earthquakes$ qri init --source-body-path ~/downloads/earthquakes.csvName of new dataset [usgs_earthquakes]: usgs_earthquakesinitialized working directory for new dataset foo/usgs_earthquakes
Voila! Qri has created a new dataset! It has also created a working directory, where changes you make to the dataset can be staged. You can confirm this with
qri list, which will show your dataset's name and working directory path.
$ qri list1 foo/usgs_earthquakeslinked: ~/datasets/usgs_earthquakes
Your new dataset exists in name only... it doesn't actually contain any any versions until you make your first commit.
Before you commit, try running
qri status to see what will be committed.
$ qri statusfor linked dataset [foo/usgs_earthquakes]add: meta (source: meta.json)add: structure (source: structure.json)add: body (source: body.csv)run `qri save` to commit this dataset
Why are there three components when all you did was specify a CSV for the body? structure (including schema) is inferred by Qri when you initialize a dataset with a CSV. meta is just a placeholder component. This is qri giving you a nudge to add metadata. A dataset with good metadata is a happy dataset.
Next commit the changes with
$ qri savefor linked dataset [foo/usgs_earthquakes]dataset saved: foo/[email protected]/ipfs/QmdX8StQFjxfnWt9HVgoMNefR9zaYfvxLUSDWc3mBntXyF
Now the dataset has a single version in its history. Inspect the history with
$ qri logfor linked dataset [foo/usgs_earthquakes]1 Commit: /ipfs/QmdX8StQFjxfnWt9HVgoMNefR9zaYfvxLUSDWc3mBntXyFDate: Tue Jan 7 15:57:21 UTC 2020Storage: remoteSize: 0 Bcreated dataset
You can see the timestamp and message of your commit, along with the ipfs hash of the version.
You can also inspect the dataset’s components using the CLI. The version of the dataset you just created contains both body and structure components. You can write these to the console using
$ qri get body foo/usgs_earthquakestime,latitude,longitude,depth,mag,mag_type,nst,gap,dmin,rms,net,id,updated,place,type,horizontal_error,depth_error,mag_error,mag_nst,status,location_source,mag_source2020-01-07T15:34:50.790Z,20.1843338,-155.8861694,13.92,2.54,md,44,297,0.1179,0.16,hv,hv71322062,2020-01-07T15:38:15.290Z,"8km SW of Hawi, Hawaii",earthquake,0.85,0.82,0.17,8,automatic,hv,hv2020-01-07T15:18:58.570Z,36.2748337,-89.4588318,6.4,2.39,md,22,100,0.1382,0.28,nm,nm60272917,2020-01-07T15:30:33.128Z,"2km ENE of Ridgely, Tennessee",earthquake,0.88,2.91,0.59,17,reviewed,nm,nm2020-01-07T15:18:17.080Z,35.6698333,-117.4761667,1.68,1.15,ml,17,82,0.07134,0.24,ci,ci39026799,2020-01-07T15:21:49.663Z,"13km SSW of Searles Valley, CA",earthquake,0.46,0.78,0.1,14,automatic,ci,ci...
You can also
get the structure component, which tells us how Qri has guessed the column types in our original csv.
$ qri get structure foo/usgs_earthquakeschecksum: QmamMwutqHsPyCh4g9qi1LPQyjqHwsski3Acqf7uGsxCNYdepth: 2entries: 2341errCount: 2340format: csvformatConfig:headerRow: truelazyQuotes: truelength: 437656qri: st:0schema:items:items:- title: timetype: string- title: latitudetype: number- title: longitudetype: number- title: depthtype: number- title: magtype: number- title: mag_typetype: string- title: nsttype: integer- title: gaptype: integer- title: dmintype: number- title: rmstype: number- title: nettype: string- title: idtype: string- title: updatedtype: string- title: placetype: string- title: type
schema property in structure contains a JSONSchema document showing the
type Qri has applied to our CSV's columns. These will come in handy later for schema validation.
Use a text editor to create a
readme.md file in your dataset's working directory. Describe the dataset and help future you or your collaborators know what this dataset is all about. You know, readme stuff.
After saving changes to readme.md in your working directory, qri will be aware of the changes. Use
qri status to see the current status of the working directory:
$ qri statusfor linked dataset [foo/usgs_earthquakes_1]modified: readme (source: readme.md)
Qri lets you know that it sees the changes to the readme in the working directory and you’re clear to commit!
This time try using
qri save with the
--title flag. The title will let future you and your collaborators know what changed in this commit.
qri save --title 'added a readme'
$ qri save --title 'added a readme with download info'for linked dataset [foo/usgs_earthquakes]dataset saved: foo/[email protected]/ipfs/QmQTA7NY1Kbk7btVsjZttQmzUM8UrixaAJfU9H5A6WCGio
Commit successful! Now there are two versions of this dataset. Use
qri log to inspect the history of commits.
qri logfor linked dataset [foo/usgs_earthquakes]1 Commit: /ipfs/QmQTA7NY1Kbk7btVsjZttQmzUM8UrixaAJfU9H5A6WCGioDate: Tue Jan 7 17:49:09 UTC 2020Storage: remoteSize: 0 B'added a readme with download info'readme:added scriptBytes2 Commit: /ipfs/QmbuH3uMmhBwrngnJWcuSV23Pu3s3xfhttryunZEK27QH1Date: Tue Jan 7 17:45:00 UTC 2020Storage: remoteSize: 0 Bcreated dataset
You can continue making changes this way, committing new versions whenever you reach a critical point. All of the older versions are intact in Qri, and you can inspect and export them at any time.
Qri Cloud allows you to share your Qri Datasets publicly. Use
qri publish to push your dataset versions to the cloud.
$ qri publish foo/usgs_earthquakespublished dataset foo/[email protected]/ipfs/QmQTA7NY1Kbk7btVsjZttQmzUM8UrixaAJfU9H5A6WCGio
That’s it! Once the dataset is transferred, your dataset will have a shiny new preview page on qri.cloud, where other users will be able to find it.
It will also show up on your public profile page, which lists all of your published datasets. Other users can now add your datasets to their Qri collections!
Here are some things to try now that you’re up and running: