CLI Commands

Qri ("query") is a global dataset version control system on the distributed web.

qri addAdd a dataset from another peer
qri bodyGet the body of a dataset
qri configGet and set local configuration information
qri connectConnect to the distributed web by spinning up a Qri node
qri diffCompare differences between two datasets
qri exportCopy datasets to your local filenamesystem
qri getGet elements of qri datasets
qri infoShow summarized description of a dataset
qri listShow a list of datasets
qri logShow log of dataset history
qri peersCommands for working with peers
qri publishMake your dataset available on the registry and to your connected peers
qri registryCommands for working with a qri registry
qri removeRemove a dataset from your local repository
qri renameChange the name of a dataset
qri renderExecute a template against a dataset
qri saveCreate a new dataset or save changes to an existing dataset
qri searchSearch qri
qri setupInitialize qri and IPFS repositories, provision a new qri ID
qri useSelect datasets for use with the qri get command
qri validateShow schema validation errors
qri versionPrint the version number

qri add

Add a dataset from another peer


Add retrieves a dataset owned by another peer and adds it to your repo. The dataset reference of the dataset will remain the same, including the name of the peer that originally added the dataset. You must have qri connect running in another terminal to use this command.

qri add [flags]


# add a dataset named their_data, owned by other_peer:
$ qri add other_peer/their_data


-h, --help help for add

qri config get

get configuration settings


get outputs your current configuration file with private keys removed by default, making it easier to share your qri configuration settings.

You can get particular parts of the config by using dot notation to traverse the config object. For details on each config field checkout:

The --with-private-keys option will show private keys. PLEASE PLEASE PLEASE NEVER SHARE YOUR PRIVATE KEYS WITH ANYONE. EVER. Anyone with your private keys can impersonate you on qri.

qri config get [flags]


# get the entire config
qri config get
# get the config profile
qri config get profile
# get the profile description
qri config get profile.description


-c, --concise print output without indentation, only applies to json format
-f, --format string data format to export. either json or yaml (default "yaml")
-h, --help help for get
-o, --output string path to export to
--with-private-keys include private keys in export

qri config set

Set configuration options


'qri config set' allows you to set configuration options. You can set particular parts of the config by using dot notation to traverse the config object.

While the 'qri config get' command allows you to view the whole config, or only parts of it, the 'qri config set' command is more specific.

If the config object were a tree and each field a branch, you can only set the leaves of the branches. In other words, the you cannot set a field that is itself an object or array. For details on each config field checkout:

qri config set [flags]


# set a profile description
qri config set profile.description "This is my new description that I
am very proud of and want displayed in my profile"
# disable rpc communication
qri config set rpc.enabled false


-h, --help help for set

qri config

Get and set local configuration information


'qri config' encapsulates all settings that control the behaviour of qri. This includes all kinds of stuff: your profile details; enabling & disabling different services; what kind of output qri logs to; which ports on qri serves on; etc.

Configuration is stored as a .yaml file kept at $QRI_PATH, or provided at CLI runtime via command a line argument.

For details on each config field checkout:


# get your profile information
$ qri config get profile
# set your api port to 4444
$ qri config set api.port 4444
# disable rpc connections:
$ qri config set rpc.enabled false


-h, --help help for config

qri connect

Connect to the distributed web by spinning up a Qri node


While it’s not totally accurate, connect is like starting a server. Running connect will start a process and stay there until you exit the process (ctrl+c from the terminal, or killing the process using tools like activity monitor on the mac, or the aptly-named “kill” command). Connect does three main things:

  • Connect to the qri distributed network
  • Connect to IPFS
  • Start a local API server

When you run connect you are connecting to the distributed web, interacting with peers & swapping data.

qri connect [flags]


--api-port int port to start api on
--disable-api disables api, overrides the api-port flag
--disable-p2p disables webapp, overrides the webapp-port flag
--disable-rpc disables rpc, overrides the rpc-port flag
--disable-webapp disables webapp, overrides the webapp-port flag
--disconnect-after int duration to keep connected in seconds, 0 means run indefinitely
-h, --help help for connect
--read-only run qri in read-only mode, limits the api endpoints
--registry string specify registry to setup with. only works when --setup is true
--rpc-port int port to start rpc listener on
--setup run setup if necessary, reading options from environment variables
--webapp-port int port to serve webapp on

qri diff

Compare differences between two datasets


Diff compares two datasets from your repo and prints a representation of the differences between them. You can specifify the datasets either by name or by their hash. You can compare different versions of the same dataset.

qri diff [flags]


# show diff between two versions of the same dataset:
$ qri diff me/[email protected]/ipfs/QmcBZoEQ7ot4UYKn1JM3gwd4LHorj6FJ4Ep19rfLBT3VZ8 \
me/[email protected]/ipfs/QmVvqsge5wqp4piJbLArwVB6iJSTrdM8ZRpHY7fikASrr8
# show diff between two different datasets:
$ qri diff me/population_2016 me/population_2017


-d, --display string set display format [reg|short|delta|detail]
-h, --help help for diff

qri export

Copy datasets to your local filesystem


Export gets datasets out of qri. By default it exports the dataset body, as body.csv, header asdataset.json, and ref, as ref.txt files.

To export to a specific directory, use the --output flag.

If you want an empty dataset that can be filled in with details to create a new dataset, use --blank.

qri export [flags]


# export dataset
qri export me/annual_pop
# export without the body of the dataset
qri export --no-body me/annual_pop
# export to a specific directory
qri export -o ~/new_directory me/annual_pop


--blank export a blank dataset YAML file, overrides all other flags except output
--body-format string format for dataset body. default is the original data format. options: json, csv, cbor
-f, --format string format for all exported files, except for body. yaml is the default format. options: yaml, json (default "yaml")
-h, --help help for export
-b, --no-body don't include dataset body in export
-o, --output string path to write to, default is current directory
-d, --peer-dir export to a peer name namespaced directory

qri get

Get elements of qri datasets


Get the qri dataset (except for the body). You can also get portions of the dataset: meta, structure, viz, transform, and commit. To narrow down further to specific fields in each section, use dot notation. The get command prints to the console in yaml format, by default.

You can get pertinent information on multiple datasets at the same time by supplying more than one dataset reference.

Check out to learn about each section of the dataset and its fields.

qri get [flags]


# print the entire dataset to the console
qri get me/annual_pop
# print the meta to the console
qri get meta me/annual_pop
# print the dataset body size to the console
qri get structure.length me/annual_pop
# print the dataset body size for two different datasets
qri get structure.length me/annual_pop me/annual_gdp
# print the body itself for the dataset
qri get body me/annual_pop


--concise print output without indentation, only applies to json format
-f, --format string set output format [json, yaml] (default "yaml")
-h, --help help for get

qri list

Show a list of datasets


List shows lists of datasets, including names and current hashes.

The default list is the latest version of all datasets you have on your local qri repository.

When used in conjunction with qri connect, list can list a peer's dataset. You must have qri connect running in a separate terminal window.

qri list [flags]


# show all of your datasets:
qri list
# show your datasets that have "tax" in the name
qri list tax
# to view the list of your peer's dataset,
# in one terminal window:
qri connect
# in a separate terminal window, to show all of b5's datasets:
qri list --peer b5


-f, --format string set output format [json]
-h, --help help for list
-l, --limit int limit results, default 25 (default 25)
-o, --offset int offset results, default 0
-p, --published list only published datasets

qri log

Show log of dataset history


qri log prints a list of changes to a dataset over time. Each entry in the log is a snapshot of a dataset taken at the moment it was saved that keeps exact details about how that dataset looked at at that point in time.

We call these snapshots versions. Each version has an author (the peer that created the version) and a message explaining what changed. Log prints these details in order of occurrence, starting with the most recent known version, working backwards in time.

qri log [flags]


show log for the dataset b5/precip:
$ qri log b5/precip


-h, --help help for log
-l, --limit int limit results, default 25 (default 25)
-o, --offset int offset results, default 0

qri peers connect

Connect to a peer


Connect to a peer using a peername, peer ID, or multiaddress. Qri will use this name, id, or address to find a peer to which it has not automatically connected.

You must have a Qri node running (qri connect) in a separate terminal. You will only be able to connect to a peer that also has spun up it's own Qri node.

A multiaddress, or multiaddr, is the most specific way to refer to a peer's location, and is therefore the most sure-fire way to connect to a peer.

qri peers connect [flags]


# spin up a Qri node
qri connect
# in a separate terminal, connect to a specific peer
qri peers connect /ip4/


-h, --help help for connect

qri peers disconnect

Explicitly close a connection to a peer


Explicitly close a connection to a peer using a peername, peer id, or multiaddress.

You can close all connections to the Qri network by ending your Qri node session.

Use the disconnect command when you want to stay connected to the network, but want to close your connection to a specific peer. This could be because that connection is hung, the connection is pulling too many resources, or because you simply no longer need an explicit connection. This is not the same as blocking a peer or connection.

Once you close a connection to a peer, you or that peer can immediately open another connection.

You must have qri connect running in another terminal.

qri peers disconnect [flags]


# disconnect from a peer using a multiaddr
qri peers disconnect /ip4/


-h, --help help for disconnect

qri peers info

Get info on a Qri peer


The peers info command returns a peer's profile information. The default format is yaml.

Using the --verbose flag, you can also view a peer's network information.

You must have qri connect running in another terminal.

qri peers info [flags]


show info on a peer named "b5":
$ qri peers info b5
show info in json:
$ qri peers info b5 --format json


--format string output format. formats: yaml, json (default "yaml")
-h, --help help for info
-v, --verbose show verbose profile info

qri peers list

List known qri peers


Lists the peers to which your Qri node is connected.

You must have qri connect running in another terminal.

To find peers that are not online, but to which your node has previously been connected, use the --cached flag.

qri peers list [flags]


# spin up a Qri node
qri connect
# thenin a separate terminal, to list qri peers:
qri peers list
# to ensure you get a cached version of the list:
qri peers list --cached


-c, --cached show peers that aren't online, but previously seen
-h, --help help for list
-l, --limit int limit max number of peers to show (default 200)
-n, --network string specify network to show peers from [ipfs]
-s, --offset int number of peers to skip during listing

qri peers

Commands for working with peers


The peers commands allow you to interact with other peers on the Qri network. In order for these commands to work, you must be running a Qri node. This node allows you to communicate on the network. To spin up a Qri node, run qri connect in a separate terminal. This will connect you to the network, until you choose to close the connection by ending the session or closing the terminal.


-h, --help help for peers

qri publish

set dataset publicity


Publish makes your dataset available to others. While online, peers that connect to you can only see datasets and versions that you've published. Publishing a dataset always makes all previous history entries available, and any updates to a published dataset will be immediately visible to connected peers.

qri publish [flags]


# publish a dataset
$ qri publish me/dataset
# publish a few datasets
$ qri publish me/dataset me/other_dataset
# unpublish a dataset
$ qri publish -unpublish me/dataset


-h, --help help for publish
--no-registry don't publish to registry
--unpublish unpublish a dataset

qri registry pin

pin dataset data to the registry


Pin asks a registry to host a copy of your dataset, making it available for others to download on the d.web

qri registry pin [flags]


Pin a dataset to the registry:
$ qri registry pin me/dataset_name


-h, --help help for pin

qri registry publish

Publish dataset info to the registry


Publishes the dataset information onto the registry. There will be a record of your dataset on the registry, and if your dataset is less than 20mbs, Qri will back your dataset up onto the registry.

Published datasets can be found by other peers using the qri search command.

Datasets are by default published to the registry when they are created.

qri registry publish [flags]


Publish a dataset you've created to the registry:
$ qri registry publish me/dataset_name


-h, --help help for publish

qri registry status

get the status of a reference on the registry


use status to see what version of a dataset the registry has on-record, if any

qri registry status [flags]


Get status of a dataset reference::
$ qri registry status me/dataset_name


-h, --help help for status

qri registry unpin

unpin dataset data from the registry


Unpin reverses the pin process, asking a registry to remove it's hosted copy of your dataset from the registry

qri registry unpin [flags]


Unpin a dataset from the registry:
$ qri registry unpin me/dataset_name


-h, --help help for unpin

qri registry unpublish

remove dataset info from the registry


Unpublish will remove the reference to your dataset from the registry. If you dataset was previously backed up onto the registry, this backup will be removed.

This dataset will no longer show up in search results.

qri registry unpublish [flags]


Remove a dataset from the registry:
$ qri registry unpublish me/dataset_name


-h, --help help for unpublish

qri registry

Commands for working with a qri registry


Registries are federated public records of datasets and peers. These records form a public facing central lookup for your datasets, so others can find them through search tools and via web links. You can use registry commands to control how your datasets are published to registries, opting in or out on a dataset-by-dataset basis.

Unpublished dataset info will be held locally so you can still interact with it. And your datasets will be available to others peers when you run "qri connect", but will not show up in search results, and will not be displayed on lists of registry datasets.

Qri is designed to work without a registry should you want to opt out of centralized listing entirely, but know that peers who do participate in registries may choose to deprioritize connections with you. Opting out of a registry entirely is better left to advanced users.

You can opt out of registries entirely by running: $ qri config set registry.location ""


-h, --help help for registry

qri remove

Remove a dataset from your local repository


Remove gets rid of a dataset from your qri node. After running remove, qri will no longer list your dataset as being available locally. By default, remove frees up the space taken up by the dataset, but not right away. The IPFS repo that’s storing the data will need to garbage-collect that data when it’s good & ready, which could be anytime. If you’re running low on space, garbage collection will be sooner.

Keep in mind that by default your IPFS repo is capped at 10GB in size, if you adjust this cap using IPFS, qri will respect it.

In the future we’ll add a flag that’ll force immediate removal of a dataset from both qri & IPFS. Promise.

qri remove [flags]


remove a dataset named annual_pop:
$ qri remove me/annual_pop


-h, --help help for remove

qri rename

Change the name of a dataset


Rename changes the name of a dataset.

Note that if someone has added your dataset to their qri node, and then you rename your local dataset, your peer's version of your dataset will not have the updated name. While this won't break anything, it will confuse anyone who has added your dataset before the change. Try to keep renames to a minimum.

qri rename [flags]


rename a dataset named annual_pop to annual_population:
$ qri rename me/annual_pop me/annual_population


-h, --help help for rename

qri render

Execute a template against a dataset


You can use html templates, formatted in the go/html template style, to render visualizations from your dataset. These visualizations can be charts, graphs, or just display your dataset in a different format.

Use the --output flag to save the rendered html to a file.

Use the --template flag to use a custom template. If no template is provided, Qri will render the dataset with a default template.

qri render [flags]


render a dataset called me/schools:
$ qri render -o=schools.html me/schools
render a dataset with a custom template:
$ qri render --template=template.html me/schools


-a, --all read all dataset entries (overrides limit, offest)
-h, --help help for render
-l, --limit int max number of records to read (default 50)
-s, --offset int number of records to skip
-o, --output string path to write output file
-t, --template string path to template file

qri save

Save changes to a dataset


Save is how you change a dataset, updating one or more of data, metadata, and structure. You can also update your data via url. Every time you run save, an entry is added to your dataset’s log (which you can see by running qri log <dataset_reference>).

If the dataset you're changing has defined a transform, running qri save will re execute the transform. To only re-run the transform, run save with no args.

Every time you save, you can provide a message about what you changed and why. If you don’t provide a message Qri will automatically generate one for you.

When you make an update and save a dataset that you originally added from a different peer, the dataset gets renamed from peers_name/dataset_name to my_name/dataset_name.

The --message and --title flags allow you to add a commit message and title to the save.

qri save [flags]


# save updated data to dataset annual_pop:
qri save --body /path/to/data.csv me/annual_pop
# save updated dataset (no data) to annual_pop:
qri save --file /path/to/dataset.yaml me/annual_pop
# re-execute a dataset that has a transform:
qri save me/tf_dataset


--body string path to file or url of data to add as dataset contents
--dry-run simulate saving a dataset
-f, --file string dataset data file (yaml or json)
-h, --help help for save
-m, --message string commit message for save
-p, --publish publish this dataset to the registry
--recall string restore revisions from dataset history
--secrets strings transform secrets as comma separated key,value,key,value,... sequence
-t, --title string title of commit message for save

Search qri


Search datasets & peers that match your query. Search pings the qri registry.

Any dataset that has been published to the registry is available for search.

qri search [flags]


# search
$ qri search "annual population"


-f, --format string set output format [json]
-h, --help help for search

qri setup

Initialize qri and IPFS repositories, provision a new qri ID


Setup is the first command you run to get a fresh install of Qri. If you’ve never run qri before, you’ll need to run setup before you can do anything.

Setup does a few things:

  • create a qri repository to keep all of your data
  • provisions a new qri ID
  • create an IPFS repository if one doesn’t exist

This command is automatically run if you invoke any Qri command without first running setup. If setup has already been run, by default Qri won’t let you overwrite this info.

Use the --remove to remove your Qri repo. This deletes your entire repo, including all your datasets, and de-registers your peername from the registry.

qri setup [flags]


run setup with a peername of your choosing:
$ qri setup --peername=your_great_peername


-a, --anonymous use an auto-generated peername
--config-data string json-encoded configuration data, specify a filepath with '@' prefix
-h, --help help for setup
--init-ipfs initialize an IPFS repo if one isn't present (default true)
--ipfs-config string json-encoded configuration data, specify a filepath with '@' prefix
--overwrite overwrite repo if one exists
--peername string choose your desired peername
--registry string override default registry URL, set to 'none' to remove registry
--remove permanently remove qri, overrides all setup options

qri update

add/create the lastest version of a dataset


Update fast-forwards your dataset to the latest known version. If the dataset is not in your namespace (i.e. dataset name doesn't start with your peername), update will ask the peer for any new versions and download them. Updating a peer dataset accepts no arguments other than the dataset name and --dry-run flag.

For peer update to work, the peer must be online at the time. We know this is irritating, we're working on a solution.

Calling update on a dataset in your namespace will advance your dataset by re-running any specified transform script, creating a new version of your dataset in the process. If your dataset doesn't have a transform script, update will error.

qri update [flags]


# get the freshest version of a dataset from a peer
qri update other_person/dataset
# update your local dataset by re-running the dataset transform
qri update me/dataset_with_transform
# supply secrets to an update, publish on successful run
qri update me/dataset_with_transform -p --secrets=keyboard,cat


--dry-run simulate updating a dataset
-h, --help help for update
-m, --message string commit message for update
--recall string restore revisions from dataset history, only 'tf' applies when updating
--secrets strings transform secrets as comma separated key,value,key,value,... sequence
-t, --title string title of commit message for update

qri use

Select datasets for use with the qri get command


Run the use command to have Qri remember references to a specific datasets. These datasets will be referenced for future commands, if no dataset reference is explicitly given for those commands.

We created this command to ease the typing/copy and pasting burden while using Qri to explore a dataset.

qri use [flags]


# use dataset me/dataset_name, then get meta.title:
qri use me/dataset_name
qri get meta.title
# clear current selection:
qri use --clear
# show current selected dataset references:
qri use --list
# add multiple references to the remembered list
qri use me/population_2017 me/population_2018


-c, --clear clear the current selection
-h, --help help for use
-l, --list list selected references

qri validate

Show schema validation errors


Validate checks data for errors using a schema and then printing a list of issues. By default validate checks a dataset's body against it’s own schema. Validate is a flexible command that works with data and schemas either inside or outside of qri by providing one or both of --body and --schema arguments.

Providing --schema and --body is an “external validation" that uses nothing stored in qri. When only one of schema or body args are provided, the other comes from a dataset reference. For example, to check how a file “data.csv” validates against a dataset "foo”, we would run:

$ qri validate --body data.csv me/foo

In this case, qri will will print any validation as if data.csv was foo’s data.

To see how changes to a schema will validate against a dataset in qri, we would run:

$ qri validate --schema schema.json me/foo

In this case, qri will print validation errors as if stucture.json was the schema for dataset "me/foo"

Using validate this way is a great way to see how changes to data or schema will affect a dataset before saving changes to a dataset.

You can get the current schema of a dataset by running the qri get structure.schema command.

Note: --body and --schema flags will override the dataset if both flags are provided.

qri validate [flags]


# show errors in an existing dataset:
qri validate b5/comics
# validate a new body against an existing schema
qri validate --body new_data.csv me/annual_pop
# validate data against a new schema
qri validate --body data.csv --schema schema.json


-b, --body string data file to initialize from
-h, --help help for validate
--schema string json schema file to use for validation

qri version

Print the version number


Qri uses semantic versioning.

For updates & further information check

qri version [flags]


-h, --help help for version