Skip to main content

Local development with external IDEs

Introduction​

Holistics is built for development outside the UI. Everything in Holistics — models, datasets, metrics, and 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:

Development workflow​

Here's the typical workflow for developing Holistics analytics code 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. 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 before merging.

5. Validate your code​

Validate your changes using one of these methods:

Both integrate cleanly into CI/CD workflows — for example, a GitHub PR workflow that validates on every commit.

6. Create a pull request​

Create a pull request either:

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

7. Code review and merge​

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

8. Deploy​

Deploy using the Holistics web UI, or set up a GitHub workflow to auto-publish via the Publish API.

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 — AI-powered IDE with good support for custom languages
  • JetBrains IDEs — IntelliJ, WebStorm, etc.
  • Vim/Neovim — For terminal-based workflows

For AI-assisted development with tools like Claude Code or Cursor, see MCP Server for AI Agents.

What's next​

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