Skip to main content

Local development with external IDEs

Introduction​

This guide walks you through a typical local development workflow using your preferred IDE, with continuous 2-way sync between your local files and Holistics.

Prerequisites​

Before you begin, make sure you have:

Development workflow​

Here's the typical workflow for developing Holistics locally:

1. Enable Git Workflow and connect repository​

In Holistics, enable Git Workflow for your project and connect it to an external Git repository (GitHub, GitLab, or Bitbucket).

This is a one-time setup per project.

See Connect to an external Git repository for the full guide.

2. Set up your local project​

Clone the repository, create a branch, and open it in your IDE:

git clone [email protected]:your-org/your-holistics-repository.git
cd your-holistics-repository
git checkout -b feature/add-new-dashboard

A typical project structure looks like:

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

3. Authenticate the CLI and start the sync​

First, authenticate the CLI with your Holistics API key (find it under Users > Settings in the Holistics app). Pick your region:

App domain

holistics auth secure <api_key>

A successful auth prints:

Logging into https://<secure/us/eu>.holistics.io
Authentication successful. Info:
- ID: 12345
- Email: [email protected]
- Server URL: https://<secure/us/eu>.holistics.io

See Holistics CLI for full auth options.

Then, from the project root, start continuous bidirectional sync between your local files and the Holistics cloud dev branch:

holistics sync-code .

Leave this running in a terminal tab while you work. Local file saves push to the cloud within seconds, and the browser preview updates without a manual refresh. Edits made in the Holistics UI flow back to your local files automatically.

To stop the sync, press Ctrl+C.

4. Ship to production​

When your change is ready for review, commit and push your branch:

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

Then open a pull request through:

  • Your Git tooling (gh pr create, GitLab CLI, etc.)
  • Your Git host's web UI (GitHub, GitLab, etc.)
  • The Holistics web UI

5. Code review and merge​

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

6. 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

Tooling​

Validation​

You can validate your AML at any time, either locally with the CLI or in CI/CD with the Validation API:

  • 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.

VS Code extension​

We offer a VS Code extension that supports syntax highlighting, autocomplete, hover information, and go-to-definition.

Holistics VS Code extension

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

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

MCP Server​

The Holistics MCP Server gives AI coding agents (Claude Code, Cursor, Codex, etc.) live access to your Holistics workspace. It exposes tools to:

  • Explore datasets, models, and dimensions
  • Execute AQL queries
  • Execute visualizations
  • Inspect data sources and table schemas
  • Search Holistics docs

AI Skills​

The holistics/skills repo packages reusable AML/AQL/analytics workflows as plugins. Relevant for local AMQL development:

  • holistics-development — building AMQL projects (models, datasets, dashboards) with coding agents

Install in Claude Code via the plugin marketplace:

/plugin marketplace add holistics/skills

Then install the plugins you need via /plugin > Marketplaces > holistics-skills > Browse plugins > holistics-development.

For other AI agents, import the skill files directly from the repo.

Lineage​

Coming soon

holistics aml lineage will let you dump your project's lineage graph as JSON for refactor planning and integrations with external metadata tools. Stay tuned.

Publish API​

Trigger a publish from a script or CI/CD using the submit_publish endpoint. The endpoint returns a job ID that you can poll via /jobs/<id>/result for completion.

curl -X POST \
  -H "X-Holistics-Key: $HOLISTICS_API_KEY" \
  -H "Content-Type: application/json" \
  "https://<your-holistics-domain>/api/v2/aml_studio/projects/submit_publish"

Expected response:

{
  "job": {
    "id": "abc123",
    "status": "running"
  }
}

Pair this with the Validation API on PRs and an auto-publish action on merge for end-to-end CI/CD. See Auto-publish on merge for a full GitHub Action example.

Troubleshooting​

Changes not appearing in Holistics​

  • Confirm holistics sync-code . is still running in your terminal (it stops on Ctrl+C or when the terminal closes)
  • Make sure you're previewing the same branch the sync is configured for
  • If sync-code is not running, you can fall back to git commit && git push and switch branches in the Holistics UI to preview

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 --rebase before pushing

What's next​

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