Sync (fetch / push)

Fetch

Pull the latest compiled data from Mask Databases.

npx mask-sync-fetch

Push

Share your locally compiled data with your team.

npx mask-sync-push

Typical workflow

1. Clone repo → run mask-sync-fetch to get the latest.
2. Develop and run the compiler when you add or change prompts.
3. Run mask-sync-push to share your changes.
4. Teammates run mask-sync-fetch to get your updates.

Force fetch (override local unsynced)

By default, fetch protects local prompts marked isSynced: false. If your team decides the cloud version is final, use force fetch:

npx mask-sync-fetch --override-local-unsynced

This mode can overwrite local unsynced drafts for conflicting prompt keys.

Scenario: two users edit same prompt

If User A pushes first and team wants A's version to be final:

1. User A runs mask-sync-push.
2. User B runs mask-sync-fetch --override-local-unsynced.
3. User B runs node mask.compile.cjs to regenerate output from aligned maps.

If User B runs default fetch instead, unsynced local edits may be kept.

Scenario: prompts deleted in portal

• Default fetch: synced local prompts are removed; unsynced local drafts may remain.
• Force fetch: remote deletions are applied even to unsynced local prompts.
• If all prompts are deleted remotely, force fetch aligns local to that empty state.

Scenario: local delete then prompt reappears

In sync mode, compile uses merged system + local state. If a prompt still exists in system/cloud, it can reappear in local after compile. If you want cloud truth now, run force fetch first, then node mask.compile.cjs.

Scenario: push does not replace cloud entry

A push can be skipped if cloud metadata is newer, or if the effective hash/spec did not change. In that case, fetch and run node mask.compile.cjs again, then push again.

Git and .mask/

Add .mask/ to .gitignore so generated and synced files stay local. Project settings are declared in mask.compile.cjs (overrideConfig); keep secrets in env vars referenced from that file. After cloning on a new laptop, run mask-sync-fetch (with a valid API key) to pull the same compiled data from Mask Databases that your team pushed with mask-sync-push.

Deleting prompts locally

To remove prompts from your local .mask/ files without touching Mask Databases, use mask-delete. It supports deletion by hash or prompt text, and includes an interactive shell. See Deleting prompts for full usage.