Satori Docs

Your definitive guide to subscribing and publishing live data

Satori RTM CLI Direct link

Satori RTM CLI (satori-rtm-cli) is a standalone command line tool to interact with RTM from the terminal. You use RTM CLI to test, debug, and inspect RTM channels while developing Satori apps or Streambots™. RTM CLI allows you to perform simple RTM operations from the command line, such as subscribing or publishing to channels.

Install RTM CLI Direct link

RTM CLI is available from PyPI. To install the RTM CLI package:

  1. Install Python.
  2. Run the following from the command line:
    sudo pip install satori-rtm-cli
  1. To verify that RTM CLI was successfully installed, run the following from the command line. You should receive the usage options for RTM CLI:

See below for information on troubleshooting installation issues.

RTM CLI Usages and Options Direct link

Usage Description
satori-rtm-cli --help

Show usages and options.

satori-rtm-cli [options] [-j] \
   [--position <offset>] \
   [[--count <count>] | [--age <sec>]] \
subscribe <channels>...

Subscribe to channels.

satori-rtm-cli [options] [-j]  \
   [-p <sec>] \
view <query>

Subscribe with a streamview.

satori-rtm-cli [options] publish [-q] <channel>

Publish to a channel.

satori-rtm-cli [options] [-j] read <key>

Read <value> from <key> channel.

satori-rtm-cli [options] \
   [-q] \
write <key> <value>

Publish <value> to <key> channel.

satori-rtm-cli [options] delete [-q] <key>

Delete messages from <key> channel.

satori-rtm-cli [options] \
record [--output_file=<output_file>] \
   [--size_limit_in_bytes=<size_limit>] \
   [--time_limit_in_seconds=<time_limit>] \
   [--message_count_limit=<message_limit>] \

Record messages to an output file.

satori-rtm-cli [options] [-q] [-i <file>] \
   [-r <rate>] \
   [--override_channel=<override_channel>] \

Replay the channel recording to a channel. If a recording has messages from multiple channels, the replay command publishes to the same multiple channels unless the --override_channel option is used.

Options supported in RTM CLI are:

Option (Short and Long Formats) Description
-a <appkey>

The appkey for your RTM project.

--age <age>

In seconds, the time frame of the past messages to be included in the subscription data.

-c <config_file_path>

The path to the config file. The default path is $HOME/.config/satori/rtm-cli.config.

--count <count>

The number of past messages to be included in the subscription data.

-d simple|reliable|advanced

The subscription mode:

  • simple: RTM doesn't track the position value for the subscription.
  • reliable: RTM goes to the next available message when resubscribing. If the position points to an expired message, RTM fast-forwards to the earliest position that points to a non-expired message.
  • advanced: RTM goes to the next available message when resubscribing. If the position points to an expired message, the resubscription attempt fails. RTM sends an expired_position error and stops the subscription process.

-e <endpoint>

The endpoint for the RTM project. The default is the Satori Live Data endpoint, wss:// You do not need to specify an endpoint when reading from live channels.

-i <input_file>

The input file containing the messages.


Return a formatted output for readability.

-l <N|inf>
--loop <N|inf> 

The number of times to loop back.`--loop inf` means loop forever. Compatible only with the --input_file option.

-n <role-name>

The name of the role to authenticate with.

-o <output_file>

The name of the output file.

-p <period_in_seconds>

How long to subscribe to a channel.

--position <position>

The message offset in a channel to subscribe from. Use when subscribing to a single channel. See Channels for detail about a position in a channel.


Disable the acknowledgement from RTM whether the operation succeeded or failed.

-r <rate_or_unlimited>

Relative rate of replaying. Can be a <number>x (2x for double speed, 0.5x for half speed) or "unlimited" for replaying as fast as possible, default is 1x.

-s <role-secret>

The role secret key to authenticate to RTM with.

-v <verbosity>

Specify the logging level, 0, 1, 2, or 3. The default is 1.

  • 0: errors only
  • 1 : errors, warnings
  • 2 : errors, warnings, info messages
  • 3 : errors, warnings, info messages, debug statements

RTM CLI Config File

You can add the RTM CLI options in a config file and pass the file path with the -config or -c option when you execute RTM CLI.

The following is an example config file.

# Comments start with '#'

# If --key is a flag that satori-rtm-cli can take
# Then configuring it here looks like this:
# key = "value"

# For example, this is how you configure endpoint and appkey:
endpoint = "wss://"
appkey = "YOUR_APPKEY"

# Example of an option for integer value:
verbosity = 3

# Same for boolean
prettify_json = true

RTM CLI Example Usages Direct link

This section contains sample RTM CLI commands.

The examples assume that $MY_ENDPOINT, $MY_APPKEY and $MY_CHANNEL have valid values.


satori-rtm-cli --endpoint=<ENDPOINT> --appkey=<APPKEY> subscribe example.out

# subscribe to a private channel from a specific position
satori-rtm-cli --endpoint $MY_ENDPOINT --appkey $MY_APPKEY --position 12345678:012 --prettify_json subscribe big-rss

# include 10 last messages when subscribing
satori-rtm-cli --endpoint $MY_ENDPOINT --appkey $MY_APPKEY --count 10 --prettify_json subscribe big-rss

# include 5 last seconds worth of messages when subscribing
satori-rtm-cli --endpoint $MY_ENDPOINT --appkey $MY_APPKEY --age 5 --prettify_json subscribe big-rss


satori-rtm-cli --appkey $MY_APPKEY --prettify_json view 'select * from `big-rss` where title like "%Japan%" or title like "%Korea%"'

# RECORD (machine-friendly output, every line is a JSON object)

# record to stdout (press Control-C to stop)
satori-rtm-cli --appkey $MY_APPKEY record big-rss

# record to file (press Control-C to stop)
satori-rtm-cli --appkey $MY_APPKEY -o big-rss.recording record big-rss

# replay big-rss recording to $MY_CHANNEL
satori-rtm-cli --endpoint $MY_ENDPOINT --appkey $MY_APPKEY replay -i big-rss.recording --override_channel $MY_CHANNEL

# replay big-rss recording to $MY_CHANNEL at half speed
satori-rtm-cli --endpoint $MY_ENDPOINT --appkey $MY_APPKEY replay --rate 0.5x -i big-rss.recording --override_channel $MY_CHANNEL

# replay big-rss recording to $MY_CHANNEL at triple speed
satori-rtm-cli --endpoint $MY_ENDPOINT --appkey $MY_APPKEY replay --rate 3x -i big-rss.recording --override_channel $MY_CHANNEL

# replay big-rss recording to $MY_CHANNEL as fast as possible
satori-rtm-cli --endpoint $MY_ENDPOINT --appkey $MY_APPKEY replay --rate unlimited -i big-rss.recording --override_channel $MY_CHANNEL

# replay big-rss recording to $MY_CHANNEL five times
satori-rtm-cli --endpoint $MY_ENDPOINT --appkey $MY_APPKEY replay --loop 5 -i big-rss.recording --override_channel $MY_CHANNEL

# replay big-rss recording to $MY_CHANNEL in a loop forever
satori-rtm-cli --endpoint $MY_ENDPOINT --appkey $MY_APPKEY replay --loop inf -i big-rss.recording --override_channel $MY_CHANNEL


# publish a single JSON object message
echo '{"coords": {"x": 0.0, "y": 0.0}}' | satori-rtm-cli --endpoint $MY_ENDPOINT --appkey $MY_APPKEY publish $MY_CHANNEL

# publish a single string message
echo "Hello" | satori-rtm-cli --endpoint $MY_ENDPOINT --appkey $MY_APPKEY publish $MY_CHANNEL

# publish a few messages
echo "Hello\nHallo\nCiao" | satori-rtm-cli --endpoint $MY_ENDPOINT --appkey $MY_APPKEY publish $MY_CHANNEL

# publish a few messages from a file
echo "Hello\nHallo\nCiao" > hello.txt
satori-rtm-cli --endpoint $MY_ENDPOINT --appkey $MY_APPKEY -i hello.txt publish $MY_CHANNEL

# publish json messages from a file. jq ( is used to convert file to value-per-line format).
# $ cat messages
# {"key1": "value",
#          "key2": "foo"
#     }
# ["array", "of",
#  "stuff"]
jq -c . messages | satori-rtm-cli -e $MY_ENDPOINT -a $MY_APPKEY publish $MY_CHANNEL

# publish a message every 5 seconds to create some activity in the channel
while true; do echo "mymessage" | satori-rtm-cli -e $MY_ENDPOINT -a $MY_APPKEY publish $MY_CHANNEL && sleep 5; done


# write
echo '{"coords": {"x": 0.0, "y": 0.0}}' | satori-rtm-cli --endpoint $MY_ENDPOINT --appkey $MY_APPKEY write $MY_CHANNEL

# read
satori-rtm-cli --endpoint $MY_ENDPOINT --appkey $MY_APPKEY read $MY_CHANNEL

# delete
satori-rtm-cli --endpoint $MY_ENDPOINT --appkey $MY_APPKEY delete $MY_CHANNEL

Troubleshoot RTM CLI Direct link

This section provides tips to troubleshoot RTM CLI installation issues.

NOTE: When you are trying different ways to install satori-rtm-cli, beaware that pip will not reinstall the package by default, even with different installation flags. Uninstall the package first before trying another way of installing:

  1. pip uninstall satori-rtm-cli
  2. pip install --some --new -flags satori-rtm-cli

Problem: The satori-rtm-cli package failed to install.

Symptom: The "pip show -f satori-rtm-cli" command returns an empty output.

We recommend that you install the package as root with the sudo command. When installing with sudo, satori-rtm-cli is installed in a location that's already on PATH, and it will become available in your shell. A notable exception is pip from MacPorts as it installs scripts deeply into its internal directory so you can't run them immediately after installation.

If you are not able to install satori-rtm-cli as root, your other options are:

  • Install the package in a subdirectory of the user directory. The location of the subdirectory is based on your OS and Python installation. To see what it is on your system, run:
    pip install --user satori-rtm-cli
  • Install the package into a specific directory that is in your PATH and is writable by you. For example if such a directory is $HOME/bin, run:
    pip install --user --install-option="--install-scripts=$HOME/bin" satori-rtm-cli

Problem: satori-rtm-cli package installed successfully, but satori-rtm-cli is not available in the shell.

Symptom: Running satori-rtm-cli results in an error, such as "bash: command not found: satori-rtm-cli".

There are two options to fix the issue:

  • Add the location of satori-rtm-cli to your PATH. You can get the location by running:
    pip show -f satori-rtm-cli
  • Uninstall satori-rtm-cli and install it again into a directory that already is in your PATH. For example, if desired destination directory is "$HOME/bin", install the package with:
    pip install --user --install-option="--install-scripts=$HOME/bin" satori-rtm-cli