Skip to main content

Holistics CLI

Beta

The Holistics CLI is currently in beta. Some features may not be available or may be unstable.

Introduction

The Holistics CLI tool provides a powerful tooling to interact with Holistics services. This tool allows developers and analysts to integrate Holistics capabilities directly into their analytics development pipeline.

With the Holistics CLI, you can:

  • Compile AML files into JSON objects
  • Validate AML repositories for errors
  • Integrate and upload dbt models

The CLI tool is a self-contained binary that does not require installing any additional dependencies.

Installation

For macOS and Linux

Run the following command to install the Holistics CLI:

curl -fsSL https://raw.githubusercontent.com/holistics/holistics-cli/refs/heads/master/install.sh | bash
Shell Support

The installation script supports bash, zsh, and fish. If you are using other shells, please update PATH to include ~/.holistics/bin.

For Windows

At the moment, we do not have an installation script for Windows. Please manually download the latest release, then add it to your Path in the Environment Variables.

Authentication

Find your API key in the Users > Settings section within the Holistics app.

Then, run the following command to authenticate:

$ holistics auth <api_key>

Your API Key will be saved in ~/.holistics.yml. Subsequent commands that require authentication with Holistics will use this API Key to authenticate.

Important - Invalid Authentication Token error

By default, the CLI connects to the Asia-Pacific servers. If your account is in another server (EU or US), you can specify the server by running:

holistics auth [address] <your-api-key>

Where address can be:

  • eu for the EU server
  • us for the US server
  • sg for the Asia-Pacific server
  • The custom URL of the server you want to connect to

Examples

holistics auth <your-api-key>                      # Default: Use the Asia-Pacific server
holistics auth eu <your-api-key> # Use the EU server
holistics auth secure.holistics.io <your-api-key> # Use the custom server
caution

For backwards compatibility, the CLI still allows the use of the environment variable HOLISTICS_HOST to specify the server location. HOLISTICS_HOST will take precedence over the saved address.

However, this is deprecated and will be removed in the future.

Either of the following ways will still work:

HOLISTICS_HOST=eu.holistics.io holistics auth <api-key>
export HOLISTICS_HOST=eu.holistics.io
holistics auth <api-key>

Quick Start

Upload a dbt model

To upload a dbt model, you need to have a manifest JSON file.

For example, to upload manifest.json to data source demodb, run the following command:

holistics dbt upload --file-path manifest.json --data-source demodb

Compile AML files

Note:

In order to compile AML files, the current working directory must be the root directory of a valid AML repository.

To compile AML models, run the following command:

holistics aml compile **/*.model.aml

Modules Overview

The Holistics CLI is organized into several modules, each with its own set of commands and options.

ModuleDescription
amlAML-related commands
dbtdbt-related commands

Let us know what you think about this document :)