Sync and CI

FetchCatch sync is a three-way model — like git, like Terraform. Your repo holds the desired state, the server holds the live state, and the CLI keeps them honest using content hashes.

Sync is not publish

fcc apply writes drafts. fcc publish snapshots a draft as a numbered, callable version visible to /v1/evaluate. Whether the console, the CLI, or both can publish is controlled by the workspace governance mode — see governance.md.

The three states

For every resource the CLI tracks three hashes:

Comparing the three gives us a precise change kind:

The hash is SHA-256 of canonical (compact, camelCase) JSON. Pretty-printing on disk does not affect it.

Deleting flows

Only flows can be deleted via sync apply. Response types and API sources still require the console (response types: Response types page; blocked if flows reference them).

Deleting a flow removes its draft and published versions from the workspace. Historical runs remain in the runs list for audit; /v1/evaluate/{slug} returns 404 afterward.

Commands (the day-to-day loop)

fcc pull                  # bring local in sync with server (refuses to overwrite conflicts)
fcc plan                  # preview: what would apply do?
fcc apply                 # push your changes (writes drafts; refused on DesignerOnly)
fcc publish               # snapshot drafts as numbered, callable versions
fcc status                # short version of plan
fcc drift                 # CI-friendly drift report (exit 2 on divergence)

Multi-environment? Add --env <name> to any of the above and configure named environments in project.json — see environments.md.

When the designer and the CLI both touched the same file:

fcc diff flows/x.json                              # unified diff of local vs remote
fcc resolve flows/x.json --keep-mine               # local wins, overwrite remote
fcc resolve flows/x.json --keep-theirs             # remote wins, overwrite local
fcc resolve flows/x.json --edit                    # open both in $EDITOR, then keep-mine
fcc apply                                          # actually push

And for the "who broke prod" moment:

fcc history flows/x.json                           # list versions: v1, v2, v3...
fcc rollback flows/x.json --version 3              # restore that version

Exit codes (the contract CI relies on)

Strict. Documented. Use them in scripts.

JSON output

Every state command supports --json:

fcc plan --json
fcc status --json
fcc apply --json
fcc history flows/x.json --json

Schema for plan/status/apply (one shape, all fields always present):

{
  "inSync": false,
  "push": [
    { "type": "flow", "relativePath": "flows/x.json", "kind": "ModifiedLocal" }
  ],
  "pull": [],
  "conflicts": [],
  "skippedPullOnly": [],
  "applied": 1,
  "skipped": 0,
  "errors": 0,
  "items": [
    { "type": "flow", "id": "…", "relativePath": "flows/x.json", "status": "applied", "message": null }
  ]
}

items is populated only by apply. skippedPullOnly lists local changes the CLI will not push (pull-only metadata such as api-keys/*.json). kind is one of NewLocal, NewRemote, ModifiedLocal, ModifiedRemote, DeletedLocal, DeletedRemote, Conflict.

Pull-only resources

Some workspace files are pulled for reference but cannot be pushed via sync:

If a local api-keys/*.json file exists but the key is not on the server (for example a leftover test file in git), fcc plan and fcc apply list it under skippedPullOnly and skip it instead of failing with a server error.

Conflict resolution

By default, fcc apply is non-destructive on conflict:

1. Detects that local and remote both diverged from base.
2. Saves the remote version next to yours as flows/x.remote.json so you can diff it.
3. Skips the conflicting file and exits 3 so CI fails. The CLI always prints (and --json includes) the exact relativePath of each conflict — use this in CI summaries instead of relying on the count alone.

Commit sync-state.json after resolve. fcc resolve updates .fetchcatch/sync-state.json with reconciled base hashes. If you commit only the flow (or api-source) file but not sync-state.json, the next CI run still sees stale base hashes and may report the same conflict again.

Recovery options in increasing order of severity:

--force drops the optimistic-concurrency hash check on the server. Use it only when you've explicitly decided the repo is the single source of truth — typically in a "deploy from main" pipeline that runs after a human-reviewed PR.

Recommended CI

A two-job workflow: plan on PR, apply on merge to main. The plan job posts a markdown summary as a PR comment and fails the check if conflicts exist; the apply job fails if a designer edit landed between PR open and merge so a human can decide between resolve and --force.

Full workflow file →

Authentication

CLI tokens are issued from Console → Settings → CLI tokens, scoped to a tenant + workspace. In CI:

env:
  FETCHCATCH_TOKEN: ${{ secrets.FETCHCATCH_TOKEN }}
  CI: "true"

Setting CI=true (which GitHub Actions does for you) auto-disables interactive prompts.

Pin the CLI version

CLI binaries are hosted publicly under fetchcatch.com/downloads. The recommended pattern in CI is to resolve the asset URL through the public manifest — that way the storage backing can change without your workflow breaking:

env:
  FCC_VERSION: "0.1.22"

steps:
  - run: |
      set -euo pipefail
      url=$(curl -fsSL https://fetchcatch.com/downloads/manifest.json \
        | jq -r --arg v "$FCC_VERSION" \
          '.releases[] | select(.version==$v) | .assets[] | select(.platform=="linux-x64") | .url')
      curl -fsSL -o /usr/local/bin/fcc "$url"
      chmod +x /usr/local/bin/fcc

Drop the select(.version==$v) filter and use .releases[0] to track the latest release automatically. Pinning is safer.

Designer awareness

When you pull from CI or your laptop, the flow designer shows a non-blocking amber banner for ~30 minutes: "alice@… pulled this workspace 4 minutes ago from runner-abc123. Refresh before editing to avoid conflicts." This is a hint, not a lock — the conflict detector is still the safety net.

Best practices

Protocol (for tool authors)

The CLI is a thin wrapper over these HTTP endpoints: