cirxx

De inrichting van een cirxx-omgeving als bestanden: ophalen, in git zetten, bewerken, terugzetten. Voor wie met meer mensen aan één omgeving bouwt of een pull request over een wijziging wil hebben. Wie liever praat met een AI heeft dit niet nodig: dan haak je de MCP-server aan (Setup › Integraties › Bouwen met een AI).

Nul afhankelijkheden, alleen Node 20 of nieuwer.

Beginnen

npx cirxx login sandbox-jansen.cirxx.com
npx cirxx pull

login opent je browser, jij logt in op je eigen omgeving en keurt één scherm goed. Er komt geen sleutel in je terminal: het gereedschap krijgt een token dat verloopt, dat namens jóu werkt (nooit met meer rechten dan je zelf hebt), en dat je kunt intrekken in Setup › Integraties › Verbonden apps.

De aanmelding staat in ~/.cirxx/omgevingen.json (rechten 0600). Er staat een vernieuwtoken in, dus dat bestand hoort nergens anders te komen.

Commando's

cirxx login <adres>          inloggen in de browser
cirxx omgevingen             waar je aangemeld bent
cirxx gebruik <naam>         welke omgeving de standaard is
cirxx afmelden               het token intrekken en hier weghalen

cirxx pull [soort…]          instellingen ophalen als bestanden
cirxx diff [soort…]          verschil tussen de map en de omgeving
cirxx push [soort…]          bestanden terugzetten in de omgeving
cirxx check                  controleren zonder op te slaan
cirxx test [flow]            de flowtests draaien
cirxx deploy [soort…]        van de sandbox naar productie, als wijzigingsset

Vlaggen: -o <naam> (welke omgeving), --map <map> (standaard ./cirxx), --overschrijf, en bij push ook --controleer (niets wijzigen) en --verwijder-wat-weg-is.

Meerdere omgevingen

Een bureau werkt in meer dan één omgeving. Meld je bij elk van ze aan; ze staan naast elkaar, elk met een eigen naam en een eigen token.

cirxx login sandbox-jansen.cirxx.com -o jansen
cirxx login sandbox-de-vries.cirxx.com -o devries
cirxx gebruik jansen         de standaard voor commando's zonder -o
cirxx pull -o devries        eenmalig ergens anders
cirxx omgevingen             wat er staat, met een ster bij de standaard

Eén aanmelding hoort bij één omgeving én bij één persoon. Er komt geen token dat overal bij kan: dan zou één gelekt bestand alle klanten zijn.

Doorvoeren naar productie

cirxx deploy --check                       controleren tegen productie
cirxx deploy --naam "Kenteken bij klussen" doorvoeren
cirxx deploy fields                        alleen de velden
cirxx deploy --klaarzetten                 als voorstel neerleggen

deploy neemt wat er in de sandbox anders is dan in productie en zet het door als wijzigingsset — dezelfde weg als Setup › Sandbox, met dezelfde controles en dezelfde terugdraaiknop. Wat het níet doet:

• duwen. Wat nog in je map staat gaat niet mee; cirxx push komt eerst.
• verwijderen. Verwijderde rijen zitten nooit in een wijzigingsset: verwijderen in productie kost gegevens en blijft handwerk.
• doorvoeren zonder recht. Het recht wordt in productie gemeten, niet in de sandbox. Heb je het niet, dan is --klaarzetten de weg: dan legt de CLI een voorstel neer dat een collega in Setup met één knop doorvoert.

Is er in productie sinds de kopie iets veranderd, dan stopt deploy met een lijstje. Kies dan --overschrijf (de sandbox wint), laat die regels buiten de set, of los het per regel op in Setup › Sandbox.

De projectmap

cirxx/
  .stempels.json                 wat er in de omgeving stond toen je ophaalde
  objects/klus.json
  fields/klus/kenteken.json
  flows/f_3a1c.json
  translations/en/field/klus/kenteken.json

Eén bestand per rij, mappen per soort, en de bestandsnaam is de identiteit — niet een intern id, zodat git diff een leesbare regel geeft. De mapnaam is de soort zoals de API hem noemt (fields, saved_views, …): dezelfde naam die de wijzigingsset en de MCP-server gebruiken, en die niet meeverandert met de taal van wie hem ophaalt.

Welke rij het is, leest de CLI uit het veld identiteit in het bestand. De naam van het bestand is er voor jou; een bestand hernoemen breekt dus niets.

{
  "soort": "fields",
  "identiteit": { "object_api": "klus", "api_name": "kenteken" },
  "waarden": { "label": "Kenteken", "type": "text", "required": 0 }
}

Zet de map in git. Dan is git diff na een cirxx pull een leesbaar verslag van wat er in de omgeving veranderde — ook van een terugdraaiing.

Conflicten

pull bewaart per bestand een hash van wat er stond. Daardoor kijkt diff twee kanten op: wat jij veranderde, én wat er in de omgeving veranderde sinds je ophaalde. Is het aan beide kanten veranderd, dan weigert push dat bestand en gebeurt er niets — ook niet aan de andere bestanden in dezelfde opdracht.

Kies dan zelf:

• cirxx pull --overschrijf — de omgeving heeft voorrang;
• cirxx push --overschrijf — de map heeft voorrang.

push is bewust geen synchronisatie: wat niet in de map staat wordt niet verwijderd, tenzij je --verwijder-wat-weg-is meegeeft. Anders wist een halve pull je halve omgeving.

Wat er niet in gaat

• De definitie van een flow. Die reist mee in het bestand (zodat je hem in git ziet), maar terugzetten gaat via de flowbouwer of via de flow-handelingen van de API — nooit als ruwe JSON. Bij een push zegt de CLI het als je een definitie gewijzigd hebt.
• Een flow activeren. Een gereedschap maakt altijd een concept-versie; live zetten doet een mens.
• Records. Dit gaat over instellingen. Klantgegevens importeren doe je met de import in de app of via /api/v1/records.
• Rechtstreeks naar productie duwen. Lokale bestanden gaan naar een sandbox, en van daar met cirxx deploy als wijzigingsset naar productie — dezelfde weg als in Setup, met dezelfde controles. Heeft de omgeving geen sandbox, dan is Bouwen in productie (Setup › Integraties) de route en werkt push rechtstreeks; de harde weigeringen op gegevensverlies blijven gelden.

Uit deze repo draaien

node cli/bin/cirxx.mjs pull --map /pad/naar/projectmap

CIRXX_CONFIG verlegt het bestand met aanmeldingen, CIRXX_MAP de projectmap.