Using the IDX CLI

Prerequisites

The Ceramic and IDX CLIs require the Node.js runtime and the npm CLI to be installed.

If you have not installed the Ceramic CLI, it is recommended you use it alongside the IDX CLI, otherwise you will have to use a remote Ceramic server:

npm install --global @ceramicnetwork/cli

Installation

npm install --global @ceramicstudio/idx-cli

The CLI should then be accessible as idx.

Up and running

Most commands of the IDX CLI need to communicate with a Ceramic HTTP server, using one of the following options:

Explicit flag

By setting the --ceramic flag when running a command, it is possible to specify what Ceramic HTTP URL to use, for example:

idx index:inspect <did> --ceramic=https://my-ceramic-server.tld

Environment variable

If present, the CERAMIC_URL environment variable will be used by the CLI, for example on a UNIX system:

CERAMIC_URL=https://my-ceramic-server.tld idx index:inspect <did>

CLI configuration

Instead of having to explicitely provide a command flag or environment variable, the default Ceramic HTTP URL to connect to can be stored in a configuration used by the CLI, such as:

idx config:set ceramic-url https://my-ceramic-server.tld

The config:get command can be used to check the URL stored in configuration:

idx config:get ceramic-url

Local Ceramic daemon (default)

If no other method is provided, the CLI will fallback to use the default URL of the Ceramic daemon: http://localhost:7007.

If you see an error when using the IDX CLI stating it can't connect to http://localhost:7007, it means no other URL has been provided and the Ceramic daemon is not running.

To start the Ceramic daemon, having the Ceramic CLI installed as instructed above, simply run the daemon command:

ceramic daemon

Bootstrap Ceramic for IDX

The IDX library relies on some Ceramic documents used as schemas and definitions from the IDX specifications to be accessible on the Ceramic network.

When using the main Ceramic network and public testnets it is likely these documents would already be present, but for private test networks and local nodes, you may have to ensure these documents are created before using IDX.

In order to bootstrap a Ceramic network with the necessary IDX documents, simply run the bootstrap command:

idx bootstrap

Create your DID

IDX uses Decentralized Identifiers (DID) for authentication and Identity Index documents are therefore controlled by a DID.

Before being able to interact with the Identity Index document, it is necessary to create the DID that will control it. This can easily be done using the IDX CLI:

idx did:create --label=me

Here we also set the optional label flag as a local identifier for the DID, providing a simpler way to reference it.

It is possible to display all the locally created DIDs and their labels by running the did:list command:

idx did:list

Inspect the IDX document

By running then index:inspect it is possible to inspect the IDX document associated to a DID.

Assuming you have created a DID using the step above, you can run the following command:

idx index:inspect me

Interact with IDX

Finally, once all the steps above have been successfully followed, you can start interacting with contents in your Identity Index, for example setting your basic profile using the provided IDX definition:

idx index:set me basicProfile '{"name":"Alice"}'

By running the index:get command, you can check the stored document contents:

idx index:get me basicProfile

All the commands provided by the IDX CLI can be found in the CLI documentation.