@iota/is-cli

IS-CLI

The Command Line Interface for the Integration Services. Setup the IS-API, manage Identities and Channels with ease.

Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact

About The Project

This is the IS-CLI for easy interaction with the IOTA Integration Services. Create and manage Identities, Verifiable Credentials, Channels via command line.

(back to top)

Built With

• IOTA IS-Client
• commander
• nconf

(back to top)

Getting Started

This is an example of how you may give instructions on setting up your project locally. To get a local copy up and running follow these simple example steps.

Prerequisites

• min. Node v15.6.0

Installation

npm install -g @iota/is-cli@latest

or for one-time use

npx @iota/is-cli <command>

(back to top)

Usage

Configure CLI for local API access

is config -s http://localhost:3001 -a http://localhost:3002 -k <your-api-key>

Configure API environment

is setup-node

View all commands

is help

• For most of the channel and identity commands is a identity.json in the directory where the cli is executed needed.

(back to top)

Example

In this example we will show how to create Identities, Channels and how to subscribe to a channel, authorize one Subscriber and write data into a Channel.

Create json files

First create two files identityA.json and identitiyB.json for creating these Identities with the CLI in the next step. Rename for the second file the username.

{
	"username": "actorA",
	"claimType": "User",
	"claim": {
		"name": "John",
		"surname": "Smith"
	}
}

Create the Identities

is create-identity -i examples/identityA.json -o identityA.json 

is create-identity -i examples/identityB.json -o identityB.json 

Create a Channel

Next we will create a private Channel with a topic logs and the source device and save the created Channel in a file called channelA.json. For public Channels add the option -pC. For public Channels a subscriber is automatically authorized to the Channel but can't write into it. The user can read the history of this channel with the command is read-channel-history.

is create-channel -i identityA.json -t logs -s device -o channelA.json test-channel

Write to Channel

The creator of the Channel can directly write into it.

is write-channel -i identityA.json -p "hello world" -c channelA.json

Request Subscription

Other users need first to subscribe to a Channel.

is subscribe-channel -i identityB.json -c channelA.json

Authorize Subscription

The creator of the Channel authorize one subscriber.

is authorize-subscription -i identityA.json -c channelA.json <Id of identityB>

Write message as a subscriber

After the authorization the subscriber can write into the Channel.

is write-channel -i identityB.json -p "Can you hear me?" -c channelA.json

Read Channel

The subscriber can read the Channel entries but just only the ones after he was authorized to the Channel.

is read-channel -i identityB.json -c channelA.json

Read history of Channel

The user can also read the history of a Channel.

is read-channel-history -i identityB.json -c channelA.json -sK <preshared key of channelA> 

Especially if the Channel is public it is the only way for the subscriber to read from the Channel. For that add the option -pC and remove the option for the preshared Key -sK.

is read-channel-history -i identityB.json -c channelA.json -pC

Revoke Subscription

At any time the creator of a Channel can revoke the Subscription of other users.

is revoke-subscription -i identityA.json -c channelA.json -sI <Id of identityB>

Find subscription

We can also double check if the Subscription is revoked by simply trying to find it.

is find-subscription -i identityA.json -c channelA.json -sI <Id of identityB>

Help

is help

For one specific command

is <command> --help

Roadmap

• [x] IS API setup script
• [x] Add all IS-Client commands to the cli

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the Apache License. See LICENSE for more information.

(back to top)

Contact

Tim Sigl - @Schereo - [e-mail]
Juri Bogatyrjow - [e-mail]

Project Link: https://github.com/iotaledger/is-cli

(back to top)