Using the IDX CLI¶
Prerequisites¶
The IDX CLI requires Node.js v14 and npm v6 (usually installed with Node.js). Make sure to have both installed.
On Linux you will also need the libsecret library to be installed, as instructed here.
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 streams 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 streams would already be present, but for private test networks and local nodes, you may have to ensure these streams are created before using IDX.
In order to bootstrap a Ceramic network with the necessary IDX streams, simply run the bootstrap command:
idx bootstrap
Create your DID¶
IDX uses Decentralized Identifiers (DID) for authentication and Identity Index streams are therefore controlled by a DID.
Before being able to interact with the Identity Index stream, 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 index contents¶
By running then index:inspect it is possible to inspect the IDX index contents 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 record:
idx index:get me basicProfile
All the commands provided by the IDX CLI can be found in the CLI documentation.