Using The CLI

This guide walks you through the core workflow of the Hypermass CLI.

First-time setup

To begin, initialize your local Hypermass environment:

hypermass init

Follow the interactive prompts to configure your client:

• Access Key: Provide your unique Access Key.
• Initial Subscription: Enter at least one stream ID to follow (e.g., _254gGE43g).

Basic Sync

Once configured, you can start receiving updates from your subscribed streams immediately:

hypermass sync

Connection Established

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.

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.

Advanced: Publish and Subscribe

In this step, we will perform a full "loop-back" test by both publishing and subscribing to the same stream.

Create a Stream

Log into hypermass.io, create a new stream (e.g., "Lab-Test-01"), and copy the Stream ID from the stream's subscribe tab. When creating the stream set the type to JSON.

Locate your Configuration

Since configuration paths vary by operating system, run the following to find yours:

hypermass info

Look for the Hypermass Config Location and open the hypermass-config.yaml file found there.

Configure the Loop-back

Modify your hypermass-config.yaml to include both a publication-source and a subscription-target for your new stream.

• Replace _XXYYZZ with your real Stream ID.
• Replace <<YOUR_HOME_DIR>> with a directory path you have access to

subscription-targets:
  - key: "_XXYYZZ" # the key of the stream
    target-directory: <<YOUR_HOME_DIR>>/hypermass/subscribe/test-stream # override the default target directory for this stream
    # where to start streaming when first connecting, default is latest. Allowed values: latest, earliest
    writer-type: "file-per-payload" # select "file-per-payload" for one file per payload, "folder-with-metadata" for a folder with metadata, default is "file-per-payload"
publication-sources:
  - key: "_XXYYZZ" # the key of the stream
    target-directory: <<YOUR_HOME_DIR>>/hypermass/publish/test-stream # override the default target directory for this stream
    disposer-type: "delete-on-success" # select "delete-on-success" or "move-on-success" as needed

Run the Sync

Start the sync process again:

hypermass sync

Test the Cycle

Add a file to your local /publish/test-stream folder with the contents:

{
  "message": "Hello, world!"
}

The CLI will detect the file, upload it, and verify it.

Upon success, the file is deleted from /publish (per your disposer-type).

Seconds later, the subscription logic will trigger, and the same file will appear in your /subscribe/test-stream folder. Note that when you received the file back, all subscribers also received a copy (in our case this was likely no-one, but be aware all streams are publicly viewable!).

Mission Accomplished

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.