Docs · GitOps

Your flows belong in git

The flowsdesigner CLI lets you treat WhatsApp automations like any other code — pull, edit in your editor, code-review in a PR, push back.

Install

npm install -g @flowsdesigner/cli

Node 18+. Also works with npx @flowsdesigner/cli if you don’t want to install globally.

1 — Log in

Generate an API key at Settings → API Keys. Make sure the gitops scope is selected.

flowsdesigner login

The CLI prompts for the key and saves it to ~/.flowsdesignerrc (0600 permissions).

2 — Initialize the repo

mkdir my-whatsapp-flows && cd my-whatsapp-flows
git init
flowsdesigner init

Creates flows/, a .flowsdesigner.json state file, and adds .flowsdesignerrc to your .gitignore so your key never leaks.

3 — Pull your flows

flowsdesigner pull

Result:

✓ Pulled 4 flow(s) → flows/
  flows/booking-flow-abc123.yml
  flows/cart-recovery-def456.yml
  flows/test-drive-ghi789.yml
  flows/welcome-jkl012.yml

4 — Edit + commit

Each file is plain YAML:

id: cmp123abc
name: Booking flow
slug: booking-flow-abc123
description: Captures booking requests
trigger:
  type: KEYWORD
  value: book
priority: 10
active: true
version: 3
nodes:
  - id: n1
    type: message
    data: {...}
edges:
  - source: n1
    target: n2

Edit it in your editor, then commit:

git add flows/booking-flow-abc123.yml
git commit -m "Tighten booking confirmation copy"
git push origin main

5 — Preview the change

flowsdesigner diff
# updated 1 flow(s):
#    ~ Booking flow (booking-flow-abc123)
# (dry run — no changes were written)

Server-side dry run — confirms what would change without writing.

6 — Push it live

flowsdesigner push

Server appends a new FlowVersion row on every push that touches the body — your history is append-only, rollback is just git revert.

CI / CD

Add this to .github/workflows/deploy.yml to auto-deploy on push to main:

name: Deploy flows
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm install -g @flowsdesigner/cli
      - run: flowsdesigner push
        env:
          FLOWSDESIGNER_TOKEN: ${{ secrets.FLOWSDESIGNER_TOKEN }}

Add FLOWSDESIGNER_TOKEN to your repo’s secrets. Done.

Pattern: one repo, many clients

Agencies managing multiple clients can keep one repo per client:

my-agency/
├── clients/
│   ├── alsaeedi-auto/
│   │   ├── flows/...
│   │   ├── .flowsdesigner.json
│   │   └── .env       # FLOWSDESIGNER_TOKEN=...
│   ├── pinkmart-clinic/
│   │   ├── flows/...
│   │   └── ...
│   └── shared/
│       ├── booking-template.yml
│       └── csat-template.yml
└── README.md

The shared/ dir is YAML you copy into client repos. Cross-client improvements ship across the agency’s entire book at once.

API reference Need help? Contact us