hexasync-cli-nodejs

HexaSync CLI is a command-line tool for building, managing, and testing HexaSync integration profiles. It provides commands for profile initialization, component generation (tasks, pullers, pushers, tables, connections, etc.), composition, and local testing.

https://github.com/hexasync-saas/hexasync-cli-nodejs/assets/103476940/4dde436b-6c83-4c32-9264-8c2cb653a4f7

Example Template Code

• ecwid/standalone
• tiktokshop-V2/ecwid

Installation

npm run build-and-install

Or run directly during development:

npm run cli -- <command> [options]

Quick Start

# Login to a HexaSync cluster
hexasync login hexasync.com

# Initialize a new project
hexasync profile init ./my-project

# Switch to a profile
hexasync profile set-context ./my-project/partials

# Compose the profile
hexasync compose -f ./my-project/partials

Table of Contents

• Commands Overview
• login
• version
• profile
  • profile set-context
  • profile init
  • profile include
  • profile override
  • profile show-info
  • profile notifications
• compose
• task
  • task generate
  • task regenerate
  • task link
  • task set-keys / set-source-id / track-changes / set-visibility / set-position
  • task files
  • task table-columns
• table
• puller
• pusher
• connection / dependency / report / schema / webhook / validation / transformation / step
• connector
• worker
• test
• Template Directives
• Common Errors & Guidance
• For Developers

Commands Overview

| Command | Alias | Description | | ---------------- | ----- | --------------------------------------------------------------------------------- | | login | l | Login to a HexaSync cluster | | version | v | Show CLI version | | profile | p | Profile management (init, switch, include, override, show info) | | compose | c | Compose YAML components into a single HexaSync profile template | | task | ta | Task CRUD, linking, column management | | table | tb | ⚠️ Obsolete. Use task table-columns and task set-* commands instead | | puller | pl | Puller generation and step management | | pusher | ps | Pusher generation and step management | | connection | co | Connection generation | | dependency | d | Dependency generation | | report | r | ⚠️ Obsolete. Report generation — use task generate --type REFERENCE instead | | schema | sc | ⚠️ Obsolete. Schema generation — use task generate --type REFERENCE instead | | webhook | wh | Webhook generation, event & listener management | | validation | va | Validation generation | | transformation | tr | Transformation generation | | step | st | Step generation | | connector | cn | Connector management | | worker | w | Worker environment configuration | | test | te | Test pull/push actions against a local worker |

Global Options

| Flag | Description | | ----------- | ------------------------------------------------------------------------------------------------------------------ | | --verbose | Show full stack trace on errors. By default, errors display a short message with a hint to rerun with --verbose. |

login

Login to a HexaSync cluster. Prompts for username, password, client ID, client secret, and redirect URI. Authenticates via SSO authorization code flow.

hexasync login <host>

| Argument | Description | | -------- | -------------------------------------------------- | | host | The HexaSync cluster hostname, e.g. hexasync.com |

version

Display the current CLI version.

hexasync version

profile

Profile management commands for initializing, switching, including, and inspecting HexaSync integration profiles.

hexasync profile <subcommand>   # or: hexasync p <subcommand>

| Subcommand | Alias | Description | | --------------- | ----- | ---------------------------------- | | set-context | sc | Switch active profile context | | init | in | Initialize a new project | | include | ic | Include files from another project | | override | o | Create .override.yaml files | | show-info | si | Show entity information | | notifications | n | Notification management |

profile set-context

Switch the active profile context. Caches all entities (tasks, pullers, pushers, reports, tables, schemas, connections) and fixes variables/task associations.

hexasync profile set-context <folder>

| Argument | Description | | -------- | -------------------------- | | folder | Path to the target project |

profile init

Initialize a new HexaSync integration project. Creates the directory structure with partials/, main.yaml, variables.yaml, deployment.yaml, and sub-folders for pullers, pushers, dependencies, webhooks, reports, and objects.

hexasync profile init <folder> [options]

| Argument | Description | | -------- | -------------------------- | | folder | Path to the target project |

| Flag | Description | | ---------------------------- | ------------------------------------------- | | -c, --create-empty-profile | Request HexaSync to create an empty profile |

profile include

Include files (components) from another project into the current profile. Supports including specific entity types and enables variable key replacements or full cloning with variable overrides.

hexasync profile include <folder> [options]

| Argument | Description | | -------- | ------------------------------------- | | folder | Path to the source project/components |

| Flag | Description | | ------------------- | -------------------------------------------------------------------------------------------------------------------- | | -t, --type <type> | Entity type: all, task, connection, pusher, dependency, transformation, validation, report, schema | | -c, --clone | Clone/duplicate the components (prompts for variable key and value replacements) | | -r, --replace | Prompt to add variable key replacements for external files | | -n, --name <name> | Search components by name, e.g.: product, sales order |

profile override

Create .override.yaml files for selected profile components. Copies the source component into the current profile as an override file.

hexasync profile override <folder> [options]

| Argument | Description | | -------- | ------------------------------------- | | folder | Path to the source project/components |

| Flag | Description | | ------------------- | ------------------------------------------------- | | -t, --type <type> | Entity type to override (same types as include) | | -n, --name <name> | Search components by name |

profile show-info

Display detailed information about a profile entity (currently supports tasks).

hexasync profile show-info [options]

| Flag | Description | | -------------------------- | ------------------------------------------------- | | -t, --type <entity-type> | Entity type: task, puller, pusher, report | | -n, --name <entity-name> | Entity name, e.g.: product, sales order |

profile notifications

Commands for generating and configuring notifications.

profile notifications generate — Generate notification components according to profile configurations.

hexasync profile notifications generate [options]

| Flag | Description | | ----------------------- | ----------------------------------------------------------------------------- | | -i, --id <id> | The notification ID in configuration, to regenerate a specific notification | | -o, --output <output> | Output notification type: trello, lark, email, etc. (default: trello) | | -e, --entity <entity> | The entity for the notification, e.g.: Sales Orders |

profile notifications configure-task-details — Preconfigure which task details are shown in a notification.

hexasync profile notifications configure-task-details -i <taskId>

compose

Compose multiple HexaSync YAML components into a single profile template. Merges all component files referenced by main.yaml, substitutes variables, and produces an output.yaml file.

hexasync compose [options]

| Flag | Description | | ---------------------------- | ------------------------------------------------------------------------------- | | -f, --folder <folder_path> | Path to the folder containing the profile (defaults to current profile) | | --raw [raw] | Keep raw variable tokens in output instead of replacing them (default: false) |

Example:

cd demos/ecwid/standalone
hexasync compose -f ./partials

demos/
└── ecwid/
    └── standalone/
        ├── partials
        ├── local.env
        └── output.yaml

Behavior:

• Reads main.yaml to discover externals and component files
• Resolves variables.yaml and performs variable substitution (unless --raw)
• Merges components using key/id-based deep merge strategy
• Sorts arrays by id for deterministic output
• Outputs output.yaml (or output-raw.yaml when --raw)

task

Task-related commands for generating, linking, and managing HexaSync tasks.

hexasync task <subcommand>   # or: hexasync ta <subcommand>

| Subcommand | Alias | Description | | ---------------- | ----- | ------------------------------------- | | generate | g | Generate a new task | | regenerate | rg | Regenerate task columns | | link | l | Link task to puller/pusher/table | | set-keys | sk | Set KEY columns | | set-source-id | ss | Set SOURCE_ID column | | track-changes | tc | Configure change tracking | | set-visibility | sv | Set column visibility | | set-position | sp | Set column positions | | files | f | Show related files | | table-columns | tb | Manage table columns (g, a, rm) |

task generate

Generate a new HexaSync task. Interactively creates a task, associated table, and optionally creates or links a puller and pusher.

hexasync task generate [options]

| Flag | Description | | ----------------------------- | --------------------------------------------------------------------- | | -n, --task-name <task-name> | Name for the task | | -t, --type <type> | Task type: SYNC, REFERENCE, REPORT, MAPPING (default: SYNC) |

Task types:

| Type | Description | | ----------- | --------------------------------------------------------------------- | | SYNC | Standard synchronization task with ignoreRemoval: true | | REFERENCE | Reference data task (e.g., audit, lookup) with ignoreRemoval: false | | REPORT | Reporting task | | MAPPING | Data mapping task |

The --type flag is case-insensitive: --type sync and --type SYNC are equivalent.

Connection selection:

During task generation, the CLI prompts for pull and push connections. The connection list includes both project connections and built-in prefixes:

| Prefix | Description | | ----------- | ----------------------- | | None | No connection prefix | | Audit | Audit-related tasks | | Reference | Reference data tasks | | HexaSync | HexaSync internal tasks |

Post-create columns prompt:

After generating the task, puller, and pusher, the CLI prompts to manage table columns:

• Generate columns from puller — auto-generate columns from the puller's PULL_DATA step response filters
• Add columns manually — add columns interactively
• Skip — skip column management

File naming convention:

Generated file names use __ (double underscore) to separate the connection prefix from the entity name, and _ (single underscore) to separate name parts from the entity type suffix:

| Prefix | Entity Name | Generated File | | ------------------------------ | -------------------- | ----------------------------------------------------- | | [Business Central > Shopify] | Item Bonded Stocks | BusinessCentral_Shopify__ItemBondedStocks_Task.yaml | | [Audit] | Orphan Customers | Audit__OrphanCustomers_Task.yaml | | [Google Sheets] | Excluded Products | GoogleSheets__ExcludedProducts_Task.yaml | | (empty) | Item Stocks | ItemStocks_Task.yaml |

Variable keys follow the same convention (e.g., BusinessCentral_Shopify__ItemBondedStocks_Task_Id, Audit__OrphanCustomers_Task_Table_Name).

task regenerate

Regenerate task columns from the puller's PULL_DATA step response filters.

hexasync task regenerate -n <name>

task link

Link a task to a puller, pusher, or table.

hexasync task link [options]

| Flag | Description | | ------------------- | ---------------------------------------------- | | -n, --name <name> | Search task by name | | -t, --type <type> | Entity to link: puller, pusher, or table |

task set-keys

Set KEY columns for the task's related table. The commands set-source-id, track-changes, set-visibility, and set-position follow the same pattern.

hexasync task set-keys -n <name>
hexasync task set-source-id -n <name>
hexasync task track-changes -n <name>
hexasync task set-visibility -n <name>
hexasync task set-position -n <name>

All accept -i, --id <id> and -n, --name <name>.

task set-position

Set the display position of columns in the task's related table. Visible columns always have a position (required). Hidden columns have optional positions.

The auto-assign feature assigns default positions based on priority:

| Priority | Index Group | Description | | ----------- | ------------------- | --------------------------------------- | | 1 (highest) | SOURCE_ID | Source identifier columns come first | | 2 | KEYS | Key columns | | 3 | TRACK_FOR_CHANGES | Change-tracked columns | | 4 (lowest) | (other) | Remaining columns sorted alphabetically |

After auto-assignment, an interactive grid is displayed for manual adjustments.

task files

Show files related to a task (task, puller, pusher, table) with paths and metadata.

hexasync task files -n <name>

task table-columns

Manage columns for a task's related table.

hexasync task table-columns <subcommand>

| Subcommand | Description | | ---------- | -------------------------------------------------------------------------- | | generate | Auto-generate table columns from the puller's response filters (API steps) | | add | Add new columns to a task's table interactively | | remove | Remove columns from a task's table |

All accept -n, --name <name> (and add/remove also accept -i, --id <id>).

After generating, adding, or removing columns, the CLI automatically triggers the set-position flow to assign column positions.

table

⚠️ Obsolete: The table command is obsolete. Use task table-columns for column management and task set-keys, task set-source-id, task track-changes, task set-visibility, task set-position instead.

Table-related commands for managing columns and index groups independently (outside of a task context).

hexasync table <subcommand>   # or: hexasync tb <subcommand>

| Subcommand | Alias | Description | | ------------------ | ----- | -------------------------------------- | | set-keys | sk | Set KEY columns for a table | | set-source-id | ss | Set SOURCE_ID for a table | | track-changes | tc | Track changes for table columns | | set-visibility | sv | Set column visibility | | set-position | sp | Set column positions | | set-index-groups | si | Add, update, or overwrite index groups |

All accept -i, --id <id> and -n, --name <name>. set-index-groups also accepts -t, --type <type> (task, report, schema).

puller

Puller-related commands.

hexasync puller <subcommand>   # or: hexasync pl <subcommand>

puller generate (alias: g)

Generate a new HexaSync puller component.

hexasync puller generate [options]

| Flag | Description | | ---------------------------------------- | ------------------------- | | -c, --connection-name <connection> | Search connection by name | | -n, --name <name> | Name of the puller | | -ts, --use-time-based <use-time-based> | Enable time-based pulling |

puller steps generate

Generate a step for a puller (e.g., API call, SQL query). Steps sub-command alias: s, generate alias: g.

hexasync puller steps generate [options]

| Flag | Description | | ----------------------- | --------------------------------------------------------------- | | -n, --name <name> | Name of the step | | -x, --sample <sample> | CURL sample request or path to a file containing a CURL request |

pusher

Pusher-related commands.

hexasync pusher <subcommand>   # or: hexasync ps <subcommand>

pusher generate (alias: g)

Generate a new HexaSync pusher component.

hexasync pusher generate [options]

| Flag | Description | | ----------------------------------------- | ----------------------------- | | -t, --task-name <task-name> | Search for the task by name | | -c, --connection-name <connection-name> | Search for connection by name |

pusher steps generate

Generate a step for a pusher. Same interactive flow as puller steps. Steps alias: s, generate alias: g.

hexasync pusher steps generate -n <name> [-x <sample>]

connection

hexasync connection generate   # or: hexasync co g

Generate a new connection component.

dependency

hexasync dependency generate   # or: hexasync d g

Generate a new dependency component.

report

⚠️ Obsolete: The report command is obsolete and will not be approved. Use task generate --type REFERENCE for reference tasks or task generate --type SYNC for audit tasks instead.

hexasync report <subcommand>   # or: hexasync r <subcommand>

| Subcommand | Alias | Description | | ---------------- | ----- | ------------------------------------------------ | | generate | g | Generate a new report component | | generate-table | gt | Generate a table for a report | | set-source-id | ss | Set SOURCE_ID for the report's table | | set-keys | sk | Set KEY columns for the report's table | | track-changes | tc | Configure change tracking for the report's table | | set-visibility | sv | Set column visibility for the report's table |

All set-* subcommands accept -i, --id <id> and -n, --name <name>.

schema

⚠️ Obsolete: The schema command is obsolete and will not be approved. Use task generate --type REFERENCE for reference tasks or task generate --type SYNC for audit tasks instead.

hexasync schema <subcommand>   # or: hexasync sc <subcommand>

| Subcommand | Alias | Description | | ---------------- | ----- | ------------------------------------------------ | | generate | g | Generate a new schema component | | regenerate | rg | Regenerate schema columns | | set-source-id | ss | Set SOURCE_ID for the schema's table | | set-keys | sk | Set KEY columns for the schema's table | | track-changes | tc | Configure change tracking for the schema's table | | set-visibility | sv | Set column visibility for the schema's table |

All set-* subcommands accept -i, --id <id> and -n, --name <name>.

webhook

hexasync webhook <subcommand>   # or: hexasync wh <subcommand>

| Subcommand | Alias | Description | | -------------- | ----- | -------------------------------- | | generate | g | Generate a new webhook component | | add-event | ae | Add an event to a webhook | | add-listener | al | Add a listener to a webhook |

validation

hexasync validation generate   # or: hexasync va g

Generate a new validation component.

transformation

hexasync transformation generate   # or: hexasync tr g

Generate a new transformation component.

step

hexasync step generate   # or: hexasync st g

Generate a new step component (standalone, outside of puller/pusher context).

connector

Commands for managing connectors.

hexasync connector create   # or: hexasync cn c

Create a new connector interactively. Prompts for name, connector ID (UUID), full name, description, and slug. Saves to the global connector configuration file.

worker

Commands for configuring the HexaSync Worker development environment.

worker set-context

Set a profile and configuration location for testing with a local HexaSync Worker. Updates the worker's .env file with the selected profile ID, database name, storage path, and development-mode environment variables.

hexasync worker set-context --worker <workerPath> --profile <profileName>
# or: hexasync w sc --worker <workerPath> --profile <profileName>

| Flag | Description | | ------------------------- | ------------------------------- | | --worker <workerPath> | Path to the worker directory | | --profile <profileName> | Profile name or alias to search |

Behavior: Reads profiles.yaml from the worker directory, uses fuzzy search to match profiles by alias, and updates .env in <workerPath>/hexasync.api/ with HEXASYNC_PROFILE_ID, HEXASYNC_DB_NAME, HEXASYNC_PROFILES_STORAGE, and development-mode flags.

test

Test pull/push actions against a local HexaSync Worker instance.

hexasync test <type> [options]   # or: hexasync te <type>

| Argument | Description | | -------- | ----------------------------------------------------------- | | type | Action type to test: pull, push, enqueue, transform |

| Flag | Description | | ------------------------------ | ------------------------------------------------------------------ | | -i, --task-id <taskId> | Task ID (at least one of --task-id or --task-name is required) | | -n, --task-name <taskName> | Task name. Use * for all tasks | | -p, --profile-id <profileId> | Profile ID | | -w, --worker-url <workerUrl> | Worker URL (default: http://localhost:4004) |

Examples:

hexasync test pull -n "Product"
hexasync test pull -n "*"             # all tasks
hexasync test pull -i "abc-123" -w "http://localhost:5000"

Note: Currently only the pull action type is implemented.

Template Directives

Beside properties of ProfileDefinition, there are directives defined by the Composer for serving features. These directives are used in compose-time only, not included in the final code.

usings

• Define using which code in official-templates

# template: demos/tiktokshop-V2/ecwid/partials/usings.yaml

usings:
  - key: tiktokshop-V2
    type: OFFLINE
    metadata:
      type: FOLDER
      path: /tiktokshop-V2/partials
      filePathFilterPattern:
        flags: i
        exclude: (StockDataPusher|Utility|Delete|UpdateDeliveredPusher)
  - key: ecwid
    type: OFFLINE
    metadata:
      type: FOLDER
      path: /ecwid/partials
      filePathFilterPattern:
        flags: i
        exclude: (Stock|OrderStatus)
  - key: generic
    type: OFFLINE
    metadata:
      type: FOLDER
      path: /generic/partials
  - key: hexasync
    type: OFFLINE
    metadata:
      type: FOLDER
      path: /hexasync/partials

variables

• Supported define variables locally inside any files, no need of global preserved variables.yaml files. These code will be hoisted in compose-time

# templates: demos/tiktokshop-V2/ecwid/partials/components/compositions/transformations/Order/SalesOrder/SalesOrderTrackingInformationEcwidToTikTokShopTransformation.yaml

variables:
  '**SalesOrderTrackingInformationEcwidToTikTokShopTransformationObjectId**': '236eab02-5358-4720-a2b2-a0467d8b7ff8'

objectAssociations:
  '**EcwidOrderTrackingInformationDataObjectId**':
    pusher:
      id: '**TikTokShopShipPackagePusherId**' # Defined in `official-templates: tiktokshop-V2/partials/tasks/variables/common/Order/SalesOrder.yaml`

startupTasks:
  - key: ENABLE_ORDER_TRACKING_INFORMATION_SYNC_ECWID_TO_TIKTOKSHOP
    targetType: SCHEDULER
    targetId: '**EcwidOrderTrackingInformationDataObjectId**'
    metadata:
      scheduler_expression: '0/15 * * ? * * *'
      is_enabled: true
      is_running: true

validators

• Same concept as validations in ProfileDefinition. But the syntax provide way to refactor
• In final code, will be composed to validations

# templates: demos/tiktokshop-V2/ecwid/partials/components/compositions/transformations/Product/ProductEcwidToTikTokShopTransformation.yaml

variables:
  '**EcwidProductDataValidatorId**': '9729074e-de61-4e80-8a9f-0c3f9bca5dd1'

validators:
  - id: '**EcwidProductDataValidatorId**'
    usings:
      # Defined in `official-templates`, not `templates`, because `TikTokShopActiveProductDataPusher` require Product data to satisfy the same validations
      # Below define `columns` for mapping the correct name defined in TikTokShop validator to be Ecwid property name
      # See the `official-templates` code below
      - '**TikTokShopActiveProductDataPusherValidatorId**'
    columns:
      - id: 4bbfcb53-e172-4426-b3cb-5627ebb323b0
        metadata:
          field_name: sku
      - id: 0cb420ec-b14e-4cdb-8e1d-3dd0e89dd398
        metadata:
          field_name: name
    # ... and more ...

objectAssociations:
  '**EcwidProductDataObjectId**':
    pusher:
      id: '**TikTokShopActiveProductDataPusherId**'
    validator:
      id: '**EcwidProductDataValidatorId**'

# official-templates: tiktokshop-V2/partials/pushers/Product/TikTokShopActiveProductDataPusher.yaml

validators:
  - id: '**TikTokShopActiveProductDataPusherValidatorId**'
    columns:
      - id: 4bbfcb53-e172-4426-b3cb-5627ebb323b0
        type: NOT_EMPTY
        metadata:
          field_name: seller_sku
      - id: 0cb420ec-b14e-4cdb-8e1d-3dd0e89dd398
        type: MIN_LENGTH
        metadata:
          field_name: product_name
          value: '25'
    # ... and more ...

# template output: demos/tiktokshop-V2/ecwid/output.yaml

validations:
  4e857bc8-78ed-4e17-aebd-fab5fedebae2:
    - id: 4bbfcb53-e172-4426-b3cb-5627ebb323b0
      type: NOT_EMPTY
      metadata:
        field_name: sku
      index: 0
    - id: 0cb420ec-b14e-4cdb-8e1d-3dd0e89dd398
      type: MIN_LENGTH
      metadata:
        field_name: name
        value: '25'

customs

• Use to create custom component from existing ProfileDefinition property and Composer directives (HOC pattern)
• FEATURE IS IN DEVELOPMENT...

Common Errors & Guidance

YAMLParseError: Map keys must be unique at line 97, column 1

1. Check if any key, id, GUID defined is duplicated. Common case is declare PullerId/ObjectId/PusherId copy/paste but forgot to generate random UUID
2. Check if in a single file, declare duplicate fields, i.e: objects, pullers, ...

objects:
  - id: "**EcwidProductDataObjectId**"
    ignoreRemoval: true
    dependencies:
      IMAGE:
        dependedOn: "**ProductImageEcwidToTikTokShopTransformationObjectId**"
        type: KEYS
        data:
          nullable: false
          constraints:
            - synced
          keys:
            product_id: product_id


objects:
  - id: "**ProductEcwidToTikTokShopTransformationObjectId**"
    valueTableName: "**ProductEcwidToTikTokShopTransformationObjectTableName**"
    name: "**ProductEcwidToTikTokShopTransformationObjectName**"
    ignoreRemoval: true

TypeError: Cannot read properties of undefined (reading 'filter')

Check if current folder contain reserved folder partials

For Developers

Debugging

npm run debugger:sample-template # Using `mocks/sample-template`
npm run debugger:real-template # Path to specific `templates` folder

Merge mechanism based entirely on id/key of Array/Object

• For key, user has inputed into
• For id, DO NOT CODE IN COMPOSER TO AUTOGENERATE uuid FOR IT.

Useful Breakpoints

DeepMergeHelper.ts > if (typeof sourceElem !== "object")

sourceElem?.id == '**EcwidProductDataPullerId**';

compose.ts > _convertTemplateToProfile()

key === '<template/profile key name>';

CLI Design

Primary

• Building a TypeScript CLI with Commander

Secondary

• Creating a CLI tool with Node.js

Currently choose "Caught Exceptions"/"Uncaught Exceptions" before run the script will cause debugger to be hang