Manage data hubs with the Semarchy CLI

The Semarchy command line interface (CLI) provides a powerful toolset for managing and automating various aspects of your MDM project with the Semarchy extension for VS Code.

This page provides an overview of the CLI commands, their syntax, usage, and options available for managing and deploying models within Semarchy xDM.

Command syntax

The Semarchy CLI commands follow a pattern that includes capabilities, object types, action verbs, and parameters.
Here is a breakdown of the syntax:

semarchy <capability> <object_type> <action_verb> [<parameters>]

Where:

  • semarchy: indicates the start of the command.

  • (Optional) <capability>: specifies a capability identifier (di, dm, or dg) that categorizes the command’s scope within the platform. If omitted, it indicates manipulation at a platform-wide level.

  • <object_type>: specifies the type of the object being manipulated or operated upon by the command (e.g., job, data_location, datasource, etc.).

  • <action_verb>: describes the action to be performed on the object (e.g., build, deploy).

  • (Optional) [<parameters>]: represents additional options, flags, or arguments that modify the command’s behavior or provide necessary inputs (e.g., --workspace, --instance-url, --datasource, --apiKey, etc.).

Parameters reference

Arguments

Argument Value Description

--workspace

<workspaceDirectory>

Full path of a model’s root folder.

Flags

Long flag Short flag Output

--help

-h

Displays help information for the command.

--version

-V

Displays version number.

Options

Long option Short option Expected value

--apiKey

-a

API key for authentication with the xDM runtime.

--authInfo

-A

Basic authentication information in the format username:password.

--password

Password for basic authentication.

--port

-p

Port of the xDM runtime.
Default value: '' (empty string)

--url

-u

URL of the xDM runtime.
Default value: http://localhost

--username

Username for basic authentication.

Commands

build

The build command validates and consolidates YAML files within the specified workspace directory into a single JSON file.

Syntax

semarchy build <options> <workspace_directory>

For more information on the placeholders, see Parameters reference.

Output

Upon successful execution, a JSON file (<ROOT>/.build/<model_name>.json) is generated in the root directory.

deploy

The deploy command is used to build a workspace and then deploy the consolidated model to an xDM instance. This process involves validating and consolidating the YAML files in the specified workspace directory into a single JSON file and then deploying this model to the runtime environment via the deployment API.

Syntax

semarchy dm data-location deploy
    [--workspace <workspace_directory>]
    --instance-url <xdm_instance_url>
    --instance-port <xdm_instance_port>
    --data-location <data_location_name>
    --api-key <api_key>
    --username <username>
    --password <password>

For more information on the placeholders, see Parameters reference.

Output

Upon successful execution, the deploy command builds the model and calls the deployment API on the xDM runtime to deploy the model.

The exact output will depend on the specifics of the deployment process and the target environment.
Examples

To deploy a model located in /path/to/workspace to an xDM instance running at http://my_xdm_instance on port 8080 using an API key for authentication, you would use the following command:

semarchy dm model deploy
    --workspace /path/to/workspace
    --instance-url http://my_xdm_instance
    --instance-port 8080
    --api-key my_api_key

If you need to use basic authentication instead, you would specify the username and password using the --authInfo option:

semarchy dm model deploy
    --workspace /path/to/workspace
    --instance-url http://my_xdm_instance
    --port 8080
    --username my_username
    --password my_password