/synse-cli

Unified CLI for the Synse platform

Primary LanguageGoGNU General Public License v3.0GPL-3.0

Synse CLI

Build Status FOSSA Status Go ReportCard

A command-line interface for Vapor IO's Synse platform.

Overview

The synse CLI provides a simple but comprehensive tool to interact with Synse Server (via its HTTP API) and Synse plugins (via the internal gRPC API). It allows for real-time queries and interaction with devices exposed by Synse. This makes getting started with Synse easy, and enabled rapid debugging and development against various Synse components.

Installing

Homebrew

The Synse CLI may be install via Homebrew. First, add the vapor-ware tap

brew tap vapor-ware/formula

Then, you can install the CLI

brew install vapor-ware/formula/synse

Precompiled Binaries

Precompiled binaries are available as artifacts on GitHub releases. To download the binary and place it on your $PATH:

# Set variables for download
export CLI_VERSION="3.0.0"
export CLI_OS="darwin"
export CLI_ARCH="amd64"

# Download and install the CLI
wget \
  https://github.com/vapor-ware/synse-cli/releases/download/${CLI_VERSION}/synse-cli_${CLI_VERSION}_${CLI_OS}_${CLI_ARCH}.tar.gz \
  -O /usr/local/bin/synse

# Make the binary executable
chmod +x /usr/local/bin/synse

From Source

If you wish to build from source, you will first need to fork and clone the repo. From within the project directory, you can build using the Makefile target:

make build

Which will create the synse binary in the project directory. If you wish, you can add it to your PATH.

Getting Started

With the CLI installed, you can run synse --help to get usage info. You can get additional info on all commands and sub-commands by running the command with the --help flag.

There are three primary commands to be aware of:

  • context: Configuration management for server/plugin instances.
  • server: Interact with a Synse Server instance via HTTP.
  • plugin: Interact with a plugin instance via gRPC.

Contexts

Prior to interacting with a server or plugin instance, a new context for it needs to be created. If running the example deployment found in this repo (which runs Synse Server at localhost:5000 and the emulator plugin at localhost:5001), this can be done with:

# Add a server context and set it as the current server.
synse context add server local localhost:5000 --set

# Add a plugin context and set it as the current plugin.
synse context add plugin emulator localhost:5001 --set

You can then list the contexts and see that those are both present and marked as active. Now when you run a synse server ... or synse plugin ... command, it knows which instance to communicate with.

$ synse context list
CURRENT   NAME       TYPE     ADDRESS
*         emulator   plugin   localhost:5001
*         local      server   localhost:5000

Compatibility

Below is a table describing the compatibility of Synse CLI versions with Synse platform versions.

Synse v2 Synse v3
CLI v1.x ✗ ✗
CLI v2.x ✓ ✗
CLI v3.x ✗ ✓

License

FOSSA Status