Using The CLI
This guide covers the CLI's day-to-day commands. New to the CLI? Start with Getting Started.
Subscribe to a stream
Copy the Stream ID from the stream page on hypermass.io. The Get live data button shows the full command, ready to copy:
hypermass subscribe _254gGE43g
Files arrive in <home folder>/hypermass/subscriptions/_254gGE43g, and a running sync picks the subscription up straight
away. Subscribe And Publish covers both commands, and stopping a stream;
Managing Your Configuration covers changing its folder.
Basic Sync
Start receiving updates from your subscribed streams:
hypermass sync
Hypermass creates a folder for each configured stream, both for publishing and subscribing. Each folder belongs to one
stream: if a folder already exists but wasn't created by Hypermass for that stream, that stream fails to start and the
others carry on. This prevents accidental overwrites or deletions, and hypermass status shows the reason.
While this command is active, your terminal will display real-time updates. Any new files published to your subscribed streams will automatically appear in your local subscription directory. Any files you write to the publish directories you configure (see below) will be uploaded, processed and broadcast to your subscribers.
Press Ctrl + C to stop the sync. You can restart it at any time, and the CLI will resume exactly where it left off,
fetching any files you missed while the command was stopped.
Once sync is running, in another terminal you can query the status of the sync with
hypermass status
A stream waiting for its allowance to reset shows when it will carry on - see Using an account for more.
Changing your configuration
After editing hypermass-config.yaml, apply the changes to a running sync with hypermass reload - see
Reload. A new access key needs the sync to be restarted.
Advanced: Publish and Subscribe
In this step, we will perform a full "loop-back" test by both publishing and subscribing to the same stream. Publishing needs an account - see Publish your own streams to set one up.
Create a Stream
Log into hypermass.io, create a new stream (e.g., "Lab-Test-01"), and copy the Stream ID from the stream page.
When creating the stream set the type to JSON.
Publish and Subscribe to It
Replace _XXYYZZ with your Stream ID:
hypermass publish _XXYYZZ
hypermass subscribe _XXYYZZ
If the sync isn't running yet, start it with hypermass sync.
Test the Cycle
Add a file called hello.json to <home folder>/hypermass/publications/_XXYYZZ with the contents:
{
"message": "Hello, world!"
}
The CLI will detect the file, upload it, and verify it.
Upon success, the file is deleted from the publications folder.
Seconds later, the subscription logic will trigger, and the same file will appear in
<home folder>/hypermass/subscriptions/_XXYYZZ. Note that once the stream is live (use Go live on the stream page), all subscribers also receive a copy.
You can watch the process by repeatedly running the "status" command that will show the process of the file being detected, queued, uploaded, and downloaded again;
# this works everywhere
hypermass status
## on a Linux-like environment try this for real time updates;
watch hypermass status
You have successfully completed an end-to-end publication and reception cycle.
Now you're ready to process real data and build a client to process data programmatically.