konecty-meta-sync
Konecty Meta Sync
Synchronize metadata between a filesystem repository and the Konecty database.
Prerequisites
Requires admin credentials from konecty-session. User must have admin: true.
Requires a metadata repository with the standard structure:
MetaObjects/
Contact/
document.json
list/Default.json
view/Default.json
access/Default.json
access/Corretor.json
pivot/Default.json
hook/scriptBeforeValidation.js
hook/validationData.json
hook/validationScript.js
hook/scriptAfterSave.js
Namespace/
document.json
Workflow
1. Plan (preview changes — ALWAYS run first)
python3 scripts/meta_sync.py plan --from repo --to prod --repo /path/to/metas
python3 scripts/meta_sync.py plan --from prod --to repo --repo /path/to/metas
Shows a diff of changes that would be applied. No changes are made.
2. Apply (execute changes with confirmation)
python3 scripts/meta_sync.py apply --from repo --to prod --repo /path/to/metas
Interactive confirmation: shows each change and asks for approval.
python3 scripts/meta_sync.py apply --from repo --to prod --repo /path/to/metas --auto-approve
Non-interactive: applies all changes (for CI/CD).
python3 scripts/meta_sync.py apply --from repo --to prod --repo /path/to/metas --only Contact Contact:list:Default
Selective: applies only the specified metas.
Before each document/composite write, hooks are prevalidated using backend POST /api/admin/meta/hook/validate. Invalid hooks are skipped and reported.
3. Diff (single item comparison)
python3 scripts/meta_sync.py diff --repo /path/to/metas --meta-id Contact
python3 scripts/meta_sync.py diff --repo /path/to/metas --meta-id "Contact:list:Default"
4. Pull (fetch from prod to repo)
python3 scripts/meta_sync.py pull --repo /path/to/metas --document Contact
python3 scripts/meta_sync.py pull --repo /path/to/metas --all
Direction model
--from repo --to prod: Repository is source of truth, push to database--from prod --to repo: Database is source of truth, pull to repository
Key concepts
- Hooks (.js/.json files) in
hook/subdirectory are injected into the document meta - Hook payloads are prevalidated against backend rules before apply
- Namespace is synced as
MetaObjects/Namespace/document.json - The
--onlyflag allows selective application from a plan - The
--auto-approveflag skips interactive confirmation (for CI/CD) - After applying changes, a reload (
POST /api/admin/meta/reload) is triggered automatically
Script reference
See scripts/meta_sync.py. Stdlib only.
More from konecty/skills
konecty-meta-namespace
Manage Konecty Namespace global configuration: email servers, RabbitMQ queue config, storage, webhooks, plan settings, portal config. Use when the user wants to configure SMTP servers, add RabbitMQ queues, set up storage, configure global webhooks (onCreate/onUpdate/onDelete), manage Konsistent settings, or view global tenant configuration. Requires admin credentials.
9konecty-session
Opens a Konecty session via OTP login (request OTP, then verify OTP) and persists the access token in .env or ~/.konecty/credentials for use by other skills. Use when the user wants to log in to Konecty with OTP, store credentials, set up KONECTY_TOKEN, or establish a session so other Konecty skills can call the API. Only works when the namespace has OTP enabled (email or WhatsApp).
8konecty-create
Creates records in any Konecty module via POST /rest/data/:document. Guides through the full pre-creation workflow: discovering fields and types with konecty-modules, resolving lookup _ids with the built-in lookup command, checking picklist options, validating required fields, and submitting the payload. Use when the user wants to create a new record, insert data, send a message, add an activity, register a contact, create an opportunity, or create any document in Konecty. Requires an active konecty-session (KONECTY_URL and KONECTY_TOKEN in ~/.konecty/.env or ~/.konecty/credentials).
8konecty-meta-list
Manage Konecty list view metadata: show list definitions, manage columns, filters, sorters, calendars, and boards. Use when the user wants to create or modify list views, change column visibility or order, update default filters, or configure calendar/board views. Requires admin credentials.
8konecty-meta-view
Manage Konecty form view metadata: show view definitions, inspect visual tree (visualGroups, visualSymlinks, reverseLookups), upsert views. Use when the user wants to create or modify form layouts, rearrange fields in forms, add visual groups, or configure reverse lookups in views. Requires admin credentials.
8konecty-meta-hook
Generate and manage Konecty hook code: scriptBeforeValidation, validationData, validationScript, scriptAfterSave. Use when the user wants to create, read, update, or delete hooks, generate hook code from requirements, scaffold hook templates, or validate hook correctness. Requires admin credentials.
8