EnSync Engine Documentation Help

EnSync CLI Tool

A command-line interface for interacting with the EnSync config management service.

Table of Contents

  1. Installation

  2. Configuration

  3. Usage

  4. Common Flags

  5. Error Handling

Installation

Download the CLI Tool

Choose the correct download command for your platform.

curl -L -o CLI_1.0.0_darwin_amd64.tar.gz https://github.com/EnSync-engine/CLI/releases/download/v1.0.0/CLI_1.0.0_darwin_amd64.tar.gz
curl -L -o CLI_1.0.0_linux_amd64.tar.gz https://github.com/EnSync-engine/CLI/releases/download/v1.0.0/CLI_1.0.0_linux_amd64.tar.gz
curl -LO https://github.com/EnSync-engine/CLI/releases/download/CLI_1.0.0_windows_amd64.zip

Extract the Downloaded Archive

tar -xvf CLI_1.0.0_{platform}_amd64.tar.gz

For `.zip` files, right-click the file and select **Extract All**, or use `7zip`:

7z x CLI_1.0.0_windows_amd64.zip

Make the Binary Executable (macOS/Linux)

After extracting, make the binary executable (only for macOS/Linux):

chmod +x ensync-cli

Move the Binary to a Directory in Your PATH

To make the `ensync-cli` command accessible globally, move it to a directory included in your `PATH`.

macOS/Linux
sudo mv ensync-cli /usr/local/bin/
Windows

Move the `ensync-cli.exe` binary to a folder (e.g., `C:\Program Files\CLI\`) and add that folder to your `PATH` environment variable.

Steps to update PATH on Windows:

  1. Open the Start Menu, search for "Environment Variables," and select "Edit the system environment variables."

  2. In the System Properties window, click on the "Environment Variables" button.

  3. Under "System variables," find and select the `Path` variable, then click "Edit."

  4. Click "New," and add the folder where you placed `ensync-cli.exe` (e.g., `C:\Program Files\CLI\`).

  5. Click "OK" to save your changes and close all dialogs.


Verify the Installation

Confirm the tool was installed successfully by checking the version:

ensync-cli --version

This should output the version of the CLI tool that was installed.

If you have Go installed, you can install EnSync CLI directly using the `go install` command:

# Install the EnSync CLI tool go install github.com/rossi1/ensync-cli@latest

To install a specific version:

go install github.com/ensync-cli/cmd/ensync@v1.0.0

To install the latest version:

# Install the EnSync CLI tool go install github.com/rossi1/ensync-cli@latest

Notes:

1. Requires Go 1.17 or later. 2. Ensure `$GOPATH/bin` (or `$GOBIN`) is in your system’s `PATH`.
# Clone the repository git clone https://github.com/rossi1/ensync-cli cd ensync-cli # Build the binary make build # The binary will be available in bin/ensync

Configuration/Initial Setup

macOS/Linux

To simplify the configuration, add the environment variables to your shell configuration file:

  1. Open your shell configuration file (e.g., ~/.bashrc, ~/.zshrc, or ~/.bash_profile):

    nano ~/.bashrc
  2. Add the following lines:

    export ENSYNC_BASE_URL="http://localhost:8080/api/v1/ensync" # EnSync's config manager is hosted on port 8080 by default export ENSYNC_DEBUG=false
  3. Save the file and apply the changes:

    source ~/.bashrc

Windows

To set up environment variables on Windows:

  1. Open the Start Menu, search for "Environment Variables," and select "Edit the system environment variables."

  2. In the System Properties window, click on the "Environment Variables" button.

  3. Under "System variables," click "New," and create two variables:

    • Variable Name: ENSYNC_BASE_URL Variable Value: http://localhost:8080/api/v1/ensync

    • Variable Name: ENSYNC_DEBUG Variable Value: false

  4. Click "OK" to save the variables, then close all dialogs.

  5. Open a new Command Prompt or PowerShell window to apply the changes.

Environment Variables

Alternatively, you can configure the CLI using environment variables:

export ENSYNC_BASE_URL="http://localhost:8080/api/v1/ensync" export ENSYNC_DEBUG=false

Usage

Event Management

List Events

ensync-cli event list --access-key {your-access-key} --page 0 --limit 10 --order DESC --order-by createdAt

Example 2

ensync-cli event list --access-key {your-access-key} --order ASC --order-by name

Create Event

ensync-cli event create --access-key {your-access-key} --name "test-event" --payload '{"key":"value","another":"data"}'

Update Event

ensync-cli event update --access-key {your-access-key} --id 1 --name "updated/name/name" ensync-cli event update --access-key {your-access-key} --id 1 --payload '{"key":"new-value"}' ensync-cli event get --access-key {your-access-key} --name "updated/name/name"

Example 3

ensync-cli event get --access-key {your-access-key} --name "updated/name/name"

Access Key Management

List Access Keys

ensync access-key list

Create Access Key

ensync access-key --access-key {your-access-key} create --permissions '{"send": ["event1"], "receive": ["event2"]}'

Set Permissions

ensync access-key permissions set --access-key {your-access-key} --permissions '{"send": ["event1"], "receive": ["event2"]}'

Get Permissions

ensync access-key --access-key {your-access-key} permissions get --key "MyAccessKey"

General Options

Debug Mode

ensync --debug event list

Version Information

ensync version ensync version --json

Common Flags

  • --page: Page number for pagination (default: 0)

  • --limit: Number of items per page (default: 10)

  • --order: Sort order (ASC/DESC)

  • --order-by: Field to sort by (name/createdAt)

  • --debug: Enable debug mode

  • --config: Specify custom config file location

Error Handling

  • Exit code 0: Success

  • Exit code 1: General error

  • Exit code 2: Configuration error

  • Exit code 3: API error

Troubleshooting

  • Permission Issues:

    • On macOS/Linux, you might need sudo to move the binary to a directory like /usr/local/bin.

    • On Windows, ensure you have the necessary permissions to modify the PATH and place the binary in the appropriate folder.

  • Command Not Found: If the ensync-cli command doesn't work after installation, ensure that the binary is in your PATH and check the system's environment variables.

  • Access Key Errors: If you encounter errors related to the accessKey, ensure that:

    • The accessKey is provided via the --access-key flag.

    • The accessKey is valid and has the necessary permissions.

Conclusion

The CLI tool can be installed using curl and configured with either a configuration file, environment variables, or command-line flags. The accessKey is now required for all API interactions, and this guide provides instructions for installation and configuration across various platforms.

Last modified: 13 February 2025