Skip to main content
Install expl, sign in, then search for published content and read it. Do the steps below in order and you get your first result on this one page.

Steps

1. Install

If you use Exploratory Desktop, expl is already installed. If not, install it with npm. Node.js 20 or later is required.
This installs the latest version. To pin a version, see Installation. Open a new terminal and check it.
If the first line reads expl <version>, it works.
For other ways to install, and for what to do when two copies are installed, see Installation.

2. Sign in

Your browser opens. Sign in to Exploratory and allow access.
Shows the server, your user and how you are signed in. If you see “Logged in to exploratory.io as …” after login, you are signed in. Write the search words right after the command. A value written without a flag name, like this, is called a positional argument.
--scope all searches content published by other people as well as your own. --type data limits the result to data. An empty result means that nothing matched; it is not a sign-in error. To search for notes, use --type note. Result
If the result lists content with ids and URLs, the search works.

4. Read

Replace <id> with an id from the search result. --json prints the server’s result as JSON. In the result below, IDs, URLs, and names are replaced for illustration. Long output is trimmed, so the JSON below is an excerpt, not a complete JSON. Result
The result holds the text. For a note, dashboard or slide it can also hold the list of headings (metadata.toc), depending on its length and your options. When it is missing, add --include-toc to return it, or get the heading ids with --query.

5. Aggregate (optional)

For a data item, first check the column names and types.
Replace <id> with the id of a data item. In the result below, IDs, URLs, and names are replaced for illustration. Long output is trimmed. Result
Once you know the column names, aggregate. This example sums the sales column for each value of the region column and sorts the totals from the largest.
Replace <dataset_id> with the data id and region with a real column name. Wrap each JSON value in single quotes (’). In the result below, IDs, URLs, and names are replaced for illustration. It sums sales by region on the Sales Orders data. The values match Sales by Region in the Sales Orders Dashboard. Result
The result includes the data version and update time. Check which data the numbers are based on.

If something does not work

  • The search result is empty: nothing matched. It is not a sign-in error. Change the search words, or use --scope all.
  • You cannot open a browser: in a script or CI, where there is no browser, sign in with an API key instead: expl server login --with-token (see API keys). For a machine that cannot open a browser, see Sign in.
  • You see Run "expl server login".: you are not signed in, or the saved login was rejected. Run expl server login.
  • You see expl: command not found: open a new terminal and try again.
  • You do not know which id to use: use an id from the search result.
  • The list of headings (metadata.toc) is missing from a note: add --include-toc, or get the heading ids with --query.
See Troubleshooting for more.

Next

  • Read notes - How to read long notes and get chart numbers.
  • Query data - How to write the JSON arguments.
  • Automation - Create an API key and run it in CI.
  • Use - Find the command for what you want to do.
  • Troubleshooting - Find a fix by symptom.