Skip to main content

Local development with external IDEs

Introduction​

Holistics is built for development outside the UI. Everything in Holistics (models, datasets, metrics, dashboards) is defined as code, version controlled in Git, and can be managed through CLI and API.

This guide walks you through a typical local development workflow using your preferred IDE.

Prerequisites​

Before you begin, make sure you have:

  • A Holistics project connected to an external Git repository (GitHub, GitLab, Bitbucket, etc.)
  • Git installed on your local machine
  • An IDE of your choice (VSCode, Cursor, etc.)
  • (Optional) Holistics CLI installed
    • Not required, but helpful for validating AML code locally when switching between the Holistics UI and your editor

Development workflow​

Here's the typical workflow for developing Holistics analytics code locally:

How it works:

  • One-time setup:
  • 2 ways to develop:
    • Local → Remote → Holistics:
      • Edit AML files in your IDE, validate with the CLI, then commit and push
      • Holistics syncs your changes automatically
    • Holistics → Remote → Local:
      • Make changes directly in Holistics (for example, reposition dashboard widgets)
      • Commit in Holistics
      • git pull locally
  • Ship:
    • Create a pull request
    • Review and merge
    • Publish via the UI or API
tip

Unlike purely local-first tools, Holistics supports making changes in both the UI and your local IDE because some tasks like repositioning dashboard widgets are easier in the UI. Just commit in Holistics, it will automatically sync to remote repository, and from there you can pull locally.

1. Clone your repository​

Clone your Holistics project repository to your local machine:

git clone [email protected]:your-org/your-holistics-repo.git
cd your-holistics-repo

2. Create a development branch​

Create a new branch for your changes:

git checkout -b feature/add-new-dashboard

3. Make changes in your IDE​

Open the project in your preferred IDE and start editing AML files. Your project structure typically looks like:

your-holistics-repo/
├── models/
│   ├── orders.model.aml
│   └── users.model.aml
├── datasets/
│   └── ecommerce.dataset.aml
└── dashboards/
    └── sales_overview.page.aml

4. (Optional) Validate your code​

Before pushing, validate your changes using one of these methods:

  • CLI validation for local validation:

    holistics aml validate

  • Validation API for project-level validation in CI/CD pipelines:

    curl -X POST https://<holistics domain>/api/v2/aml_studio/projects/submit_validate \
      -H "X-Holistics-Key: $HOLISTICS_API_KEY" \
      -d '{
        "branch": "feature/add-new-dashboard"
        "commit-oid": "abc123def456",
      }'

Both approaches integrate cleanly into CI/CD workflows. For example, you can set up a GitHub Action to run holistics aml validate on every push to ensure code quality before merging.

5. Push and preview​

Push your changes to your branch:

git add .
git commit -m "Add new sales dashboard"
git push -u origin feature/add-new-dashboard

In the Holistics web UI, switch to your branch to preview your changes.

6. Create a pull request​

Create a pull request either:

  • Locally via your Git tooling (gh pr create, GitLab CLI, etc.)
  • Through your Git hosting provider's web UI (GitHub, GitLab, etc.)
  • Through the Holistics web UI

7. Code review and merge​

Have your team review the changes. Once approved, merge to your master branch.

8. Publish​

Publish either:

  • Manually through the Holistics UI
  • Set up a GitHub Action to auto-publish on merge using the Publish API
  • Call the Publish API locally

IDE tooling​

VS Code extension​

We offer a VS Code extension that enhances your local development experience with:

  • Syntax highlighting for AML files
  • Autocomplete for AML keywords and properties
  • Hover information showing documentation for AML elements
  • Go-to-definition to navigate between models, datasets, and dashboards

To install, search for "Holistics" in the VS Code Extensions marketplace, or run:

code --install-extension holistics.holistics-aml-vscode-ext

Other IDEs​

AML files are plain text, so any IDE works for editing. Popular choices include:

  • Cursor
  • JetBrains IDEs
  • Vim/Neovim
  • Zed

AI-assisted development​

Use AI coding tools like Claude Code or Cursor with Holistics' MCP Server to:

  • Query your data using natural language

Troubleshooting​

Changes not appearing in Holistics​

  • Make sure you've pushed to the correct branch
  • In the Holistics UI, switch to your branch and click refresh

Validation errors​

  • Run holistics aml validate locally before pushing
  • Check the AML reference for syntax details

Merge conflicts​

  • If both local and UI changes were made on the same branch, resolve conflicts locally with git pull before pushing

What's next​

Open Markdown
Let us know what you think about this document :)