Qri CLI command line reference
Qri (“query”) is a global dataset version control system on the distributed web.
|qri add||Add a dataset from another peer|
|qri body||Get the body of a dataset|
|qri config||Get and set local configuration information|
|qri connect||Connect to the distributed web by spinning up a Qri node|
|qri diff||Compare differences between two datasets|
|qri export||Copy datasets to your local filesystem|
|qri get||Get elements of qri datasets|
|qri info||Show summarized description of a dataset|
|qri list||Show a list of datasets|
|qri log||Show log of dataset history|
|qri new||Create a new dataset|
|qri peers||Commands for working with peers|
|qri registry||Commands for working with a qri registry|
|qri remove||Remove a dataset from your local repository|
|qri rename||Change the name of a dataset|
|qri render||Execute a template against a dataset|
|qri save||Save changes to a dataset|
|qri search||Search qri|
|qri setup||Initialize qri and IPFS repositories, provision a new qri ID|
|qri use||Select datasets for use with the qri get command|
|qri validate||Show schema validation errors|
|qri version||Print the version number|
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.
qri add [flags]
# add a dataset named their_data, owned by other_peer: $ qri add other_peer/their_data
-h, --help help for add
Get the body of a dataset
qri body reads entries from a dataset. Default is 50 entries, starting from the beginning of the body. You can using the
--offset flags to iterate through the dataset body.
qri body [flags]
# show the first 50 rows of a dataset: $ qri body me/dataset_name # show the next 50 rows of a dataset: $ qri body --offset 50 me/dataset_name # save the body as csv to file $ qri body -o new_file.csv -f csv me/dataset_name
-a, --all read all dataset entries (overrides limit, offest) -f, --format string format to export. one of [json,csv,cbor] (default "json") -h, --help help for body -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 to, default is stdout
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: https://github.com/qri-io/qri/blob/master/config/readme.md
# 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 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: https://github.com/qri-io/qri/blob/master/config/readme.md
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: https://github.com/qri-io/qri/blob/master/config/readme.md
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
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-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
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
Copy datasets to your local filesystem
Export gets datasets out of qri. By default it exports only the dataset body.
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
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 https://qri.io/docs/reference/dataset/ 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
--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
Show summarized description of a dataset
Info describes datasets. By default, it will return the peername, dataset name, the network, the dataset hash, the file size, the length of the datasets, and the validation errors.
--format flag, you can get output in json. This will return a json
representation of the dataset, without the dataset body, identical to
qri get --format json.
To get info on a peer’s dataset, you must be running
qri connect in a separate
qri info [flags]
# get info for my dataset: qri info me/annual_pop # get info for a dataset at a specific version: qri info [email protected]/ipfs/QmUNLLsPACCz1vLxQVkXqqLX5R1X345qqfHbsf67hvA3Nn or qri info me/[email protected]/ipfs/QmUNLLsPACCz1vLxQVkXqqLX5R1X345qqfHbsf67hvA3Nn # get info in json format qri info -f json me/annual_pop # to get info on a peer's dataset, spin up your qri node qri connect # then, in a separate window, request the info from peer b5 qri info b5/comics
-f, --format string set output format [json] -h, --help help for info
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
qri connect running in a separate terminal window.
qri list [flags]
# show all of your datasets: qri list # 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 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
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
Create a new dataset
New creates a dataset from data you supply. Please note that all data added to qri is made public on the distributed web when you run qri connect
Once you’ve added data, you can use the export command to pull the data out of qri, change the data outside of qri, and use the save command to record those changes to qri.
qri new [flags]
# create a new dataset named annual_pop: $ qri new --body data.csv me/annual_pop # create a dataset with a dataset data file: $ qri new --file dataset.yaml --body comics.csv me/comic_characters
-b, --body string path to file or url for contents of dataset -f, --file string dataset data file in either yaml or json format -h, --help help for new -m, --message string commit message --private make dataset private. WARNING: not yet implemented. Please refer to https://github.com/qri-io/qri/issues/291 for updates -p, --publish publish this dataset to the registry --secrets strings transform secrets as comma separated key,value,key,value,... sequence -t, --title string commit title
Commands for working with peers
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
-h, --help help for peers
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/192.168.0.194/tcp/4001/ipfs/QmUNLLsPACCz1vLxQVkXqqLX5R1X345qqfHbsf67hvA3Nn
-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/192.168.0.194/tcp/4001/ipfs/QmUNLLsPACCz1vLxQVkXqqLX5R1X345qqfHbsf67hvA3Nn
-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.
--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
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
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 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 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
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
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
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.
--output flag to save the rendered html to a file.
--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
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>).
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
--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 --body /path/to/data.csv me/annual_pop # save updated dataset (no data) to annual_pop: qri --file /path/to/dataset.yaml me/annual_pop
--body string path to file or url of data to add as dataset contents -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 --secrets strings transform secrets as comma separated key,value,key,value,... sequence -t, --title string title of commit message for save
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
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.
--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 --remove permanently remove qri, overrides all setup options
Select datasets for use with the qri get command
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
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
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
Print the version number
Qri uses semantic versioning.
For updates & further information check https://github.com/qri-io/qri/releases
qri version [flags]
-h, --help help for version