CLI: sync

The holistics sync commands keep your local AML project in continuous two-way sync with Holistics. Save a file in your IDE and the Holistics preview updates within seconds. Edits and commits made in the Holistics UI flow back to your local folder automatically, and local commits flow to Holistics.

You don't need a GitHub or GitLab repo. holistics sync init downloads your project straight from Holistics.

See the Local agentic development guide for the full development loop.

Replaces holistics sync-code

holistics sync-code is deprecated. Use holistics sync start, status and stop instead. sync-code still runs but prints a deprecation notice.

Commands

Each command works on one local project. Run them from the project folder, or pass its path.

Command	Description
holistics sync init [dir]	Download a Holistics project into a new local git repo, ready for holistics sync start
holistics sync start [repo-path]	Start syncing local AML code with Holistics
holistics sync status [repo-path]	Show the sync session's state, including any pending input
holistics sync stop [repo-path]	Stop the running sync session
holistics sync input [repo-path]	Answer the question a stopped sync session is waiting for, then restart it

[repo-path] is the path to your local project. It defaults to the current folder.

Prerequisites

Log in with holistics auth before running any sync command. See Authentication.

holistics sync init

Downloads the current Holistics branch of your project into a new local git repo.

holistics sync init [dir]

The project is the one you logged in to with holistics auth. There's nothing to pick. Before downloading, the CLI prints the project name, server and branch, so you can confirm it's the right one.

• [dir]: local folder to download into. It's only a folder name and doesn't select the project. It must be new or empty. If you leave it out, the CLI asks, and suggests the project name in kebab-case.

holistics sync start

Starts a sync session for the local project.

holistics sync start [repo-path] [--background]

• -b, --background: run sync as a background process. Without it, the command runs in the foreground until you press Ctrl+C.

holistics sync status

Shows whether a session is running and what to do next, including any holistics sync input command it is waiting for.

holistics sync status [repo-path] [--wait]

• --wait: wait until the session finishes a fresh sync cycle. Useful after a batch of edits, before reading the code in Holistics.
• Exit code: 0 when healthy, 1 when something needs attention.

holistics sync stop

Stops the running sync session.

holistics sync stop [repo-path]

holistics sync input

Sync stops and waits for input when your local branch and the Holistics branch differ, or when both are on the production branch.

holistics sync input [repo-path] --switch-branch <name>

• --switch-branch <name>: sync on branch <name>. Whichever side is not on it moves onto it. The branch is created where it is missing.

Run holistics sync status first. It lists the exact commands to choose from.

Example

Log in, download your project and start syncing it in the background:

holistics auth
holistics sync init
cd <folder-from-init>
holistics sync start --background
holistics sync status

holistics sync init asks for a folder name and suggests your project name. Use that folder in the cd step.

Conflicts

Conflicts happen when the same lines change locally and in Holistics. Resolve them without stopping sync. Restarting resolves nothing.

1. Open the conflicted file and fix the conflict markers.
2. Run git add <file>. Saving alone is not enough.
3. If holistics sync status shows an open merge, run git commit once every file is resolved. Sync resumes.

A rebase, cherry-pick, revert or detached HEAD stops sync. Finish the git operation, then run holistics sync start --background again.