# @streamr/cli-tools Command line tool for interacting with [Streamr](https://streamr.network). See [Changelog](CHANGELOG.md) for version information and changes. ## Table of Contents - [Install](#install) - [Use](#use) ## Install ``` npm install -g @streamr/cli-tools ``` Node.js `20` is the minimum required version. Node.js `22`, NPM `10` and later versions are recommended. ## Use All commands follow pattern `streamr `, e.g. ``` streamr stream subscribe streamr mock-data generate ``` To get a list of all commands simply run `streamr`. To list subcommands run e.g. `streamr stream` Run `streamr --help` to get more information about a a command, its options, and so forth. If there is a stream parameter in a command, it can be defined as a full id (e.g. `0x1234567890123456789012345678901234567890/foo/bar`) or a path (e.g. `/foo/bar`). If path notation is used, the stream ID is made by prefixing the authenticated Ethereum address (`--private-key `) to the path. ### Subscribe Used to subscribe to a stream and output real-time JSON objects to stdout line-by-line. For example, to subscribe to a public stream such as the tram demo do ``` streamr stream subscribe streamr.eth/demos/helsinki-trams ``` To subscribe to a private stream and authenticate with an Ethereum private key: ``` streamr stream subscribe streamId --private-key ``` To subscribe to a particular [stream partition](https://streamr.network/docs/streams/partitioning), use the partition flag: ``` streamr stream subscribe streamId -p ``` ### Publish Used to publish events to a stream from stdin line-by-line. Each line should be a valid JSON object. Example of use: ``` streamr stream publish --private-key ``` ### Generate Generate random JSON objects to stdout line-by-line. Useful for generating test data to be published to a stream with `publish`, e.g.: ``` streamr mock-data generate | streamr stream publish --private-key ``` ### Search Query a list of streams by a search term and/or permissions. E.g.: ``` streamr stream search foobar --user 0x1234567890123456789012345678901234567890 ``` #### Search term A search term query searchers over the stream id field. E.g: ``` streamr stream search foobar ``` It could find these streams: ``` 0x1234567890123456789012345678901234567890/abc/foobar/1 foobar.eth/lorem-ipsum ``` #### Permission A permission query searches over stream permissions. You can either query by direct permissions (which are explicitly granted to a user), or by all permissions (including public permissions, which apply to all users). E.g. all streams where a user has some direct permission: ``` streamr stream search --user 0x1234567890123456789012345678901234567890 ``` All streams accessible by a user: ``` streamr stream search --user 0x1234567890123456789012345678901234567890 --public ``` The argument of the `--user` option can be omitted. In that case, it defaults to the authenticated user (specified by `--private-key`). It is also possible to filter by specific permissions by using `--all` and `--any`. E.g. if you want to find the streams you can subscribe to: ``` streamr stream search --user --public --all subscribe --private-key ``` If more than one permission is needed, specify the permissions in a comma-separated list (e.g. `--all subscribe,publish`). It returns streams where _all_ listed permissions are granted. If just _any_ of the permissions is required, use `--any` instead of `--all`. Please prefer `--all` to `--any` when possible as it has better query performance. ### Show Show detailed information about a specific stream ``` streamr stream show --private-key ``` ### Create Create a new stream ``` streamr stream create --private-key ``` E.g. ``` streamr stream create /foo/bar streamr stream create 0x1234567890123456789012345678901234567890/foobar streamr stream create yourdomain.ens/foobar ``` ### Resend Request a resend of historical data printed as JSON objects to stdout line-by-line. For example, to fetch the 10 latest messages of a public stream such as the tram demo do ``` streamr stream resend last 10 streamr.eth/demos/helsinki-trams ``` To fetch data starting from a particular date-time ``` streamr stream resend from 2019-05-10T17:00:00 --private-key ``` To fetch data between two date-times ``` streamr stream resend range 2019-05-10T17:00:00 2019-05-11T21:00:00 --private-key ``` ### Vote The CLI tool can be used to vote on Streamr governance proposals as an alternative to doing it manually in the [voting UI](https://vote.streamr.network). This is useful if you have tokens in a large number of wallets (for example due to staking) and you therefore prefer to cast your votes programmatically. ``` streamr governance vote --private-key ``` The easiest way to find the `proposalId` is to click on a proposal in the [voting UI](https://vote.streamr.network) and then look at the browser URL. The URL has the form `https://vote.streamr.network/#/proposal/`, i.e. the last part of the URL is the `proposalId`. It starts with `0x...`. The `choiceId` is just a sequence number. You can again use the UI to check what the choices are. The first option from the top is `1`, the next one is `2`, and so on. For example: ``` streamr governance vote 0x2109759e060ba5a37d70be00522e00da77397f838c01c12f74c8d834ad4f4b0c 1 --private-key ``` You must pass either the `--private-key` or `--config` option. ### Configuration User can specify environment and identity details with the following command line arguments: - `--private-key `, e.g. `--private-key 0x1234567890123456789012345678901234567890123456789012345678901234` - `--config `, e.g. `--config foobar.json` - `--env` use a pre-defined environment, e.g. `--env dev2` to use the [development environment](https://github.com/streamr-dev/streamr-docker-dev) The `--config` argument tries to read a configuration file from the current working directory (either without a file extension, or with `.json` extension added). It also tries to read it from `~/.streamr/config/${id}.json` dotfile. If no `--config` argument is specified, default settings are read from `~/.streamr/config/default.json`, if that file exists. The configuration file is a JSON. It has one root-level property `client`, which contains any configuration properties for the [@streamr/sdk](https://github.com/streamr-dev/network/blob/main/packages/sdk/). Example: ``` { "client": { "auth": { "privateKey": ... } } } ``` ### Examples: Piping with subscribe and publish You can use the piping facilities of your *nix operating system with commands `publish` and `subscribe` to achieve some useful operations. Below is a list of some ideas. #### Subscribing to a stream from any programming language You can pipe the line-by-line JSON objects output by `subscribe` to your program written in any language. Just make the program read JSON objects from stdin. ``` streamr stream subscribe streamr.eth/demos/helsinki-trams | ruby calculate-average-speed.rb ``` #### Publishing to a stream from any programming language If your program produces JSON objects to stdout (line-by-line), you can redirect it to command `publish` to publish the JSON objects to a stream. ``` python printSensorReadingsAsJson.py | streamr stream publish --private-key ``` #### Transforming streams You can also subscribe to a stream, apply a transformation, and then pipe the transformed output into another stream. ``` streamr stream subscribe | ./calculateMovingAverages | streamr stream publish --private-key ``` Same rules apply here as before. Your program should accept line-by-line JSON objects via stdin and output JSON objects to stdout line-by-line. #### Copying a production stream into development environment If you have a working stream in production that you'd also like to use in your development environment, you can combine the `subscribe` and `publish` commands to effectively copy the real-time events. ``` streamr stream subscribe streamr.eth/demos/helsinki-trams | streamr stream publish --dev --private-key ```