Quick start

What you get

InterfaceDelta checks the agent services your project depends on (MCP servers, A2A agents, OpenAPI services) for interface changes and tells you deterministically whether each change is breaking. You commit the service list and baselines in your repository, and a GitHub Action fails a pull request when a configured change appears.

Install

The CLI needs Node.js 22 or newer.

npm install -g interfacedelta@0.4.0
interfacedelta version

interfacedelta version prints 0.4.0, the CLI's own version constant. You can also run it without installing: npx interfacedelta@0.4.0 check.

Write .interfacedelta/dependencies.json

In your repository root, create .interfacedelta/dependencies.json. This example lists one MCP server and one OpenAPI service. Replace the example.com URLs with your own reachable public HTTPS services before running the commands; these placeholder addresses are not working services. Remove an entry if you only need one service:

{
  "formatVersion": "interfacedelta-dependencies-v1",
  "failOn": "breaking",
  "dependencies": [
    {
      "name": "docs-search",
      "url": "https://mcp.docs-search.example.com",
      "mcpEndpoint": "https://mcp.docs-search.example.com/mcp",
      "baseline": "docs-search.json"
    },
    {
      "name": "orders-api",
      "url": "https://api.example.com",
      "baseline": "orders-api.json"
    }
  ]
}

Check locally

From the repository root:

interfacedelta baseline
interfacedelta check

baseline inspects each service once and writes the missing .json baseline files next to the dependencies file. check compares each service with its baseline. Review the baselines, then commit the dependencies file and baselines with git add .interfacedelta && git commit -m "Add InterfaceDelta baselines". Existing baselines are preserved; use baseline --force only after reviewing a change you intend to adopt.

For two unchanged services, a passing run looks like this (your URLs will differ):

InterfaceDelta compatibility check

Policy: ci-policy-v2 (breaking); on-error: fail
Dependencies: 2
Failed: 0
Errors: 0
Blocked: 0
Warned: 0
Result: PASSED

Dependencies
- docs-search  PASSED  unchanged  https://mcp.docs-search.example.com/
- orders-api  PASSED  unchanged  https://api.example.com/

Exit codes are stable:

For a dependencies file the highest applies, in the order 2, 3 (unless --on-error warn), 1.

Add the GitHub Action

Create .github/workflows/interfacedelta.yml in your repository:

name: InterfaceDelta
on: pull_request

permissions:
  contents: read
  security-events: write

jobs:
  compatibility:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - uses: arto-a/interfacedelta-action@c06ddb383cbd5d4b4fe487e9af7906f155d72257 # v0.4.0
        with:
          sarif-output: interfacedelta.sarif
      # Pin upload-sarif to a reviewed commit SHA before adopting this workflow.
      - uses: github/codeql-action/upload-sarif@v3
        if: ${{ !cancelled() && hashFiles('interfacedelta.sarif') != '' }}
        with:
          sarif_file: interfacedelta.sarif

The Action needs no InterfaceDelta token and no GITHUB_TOKEN for the check itself: it reads .interfacedelta/dependencies.json (the default), inspects each public service, and fails the job when a decision blocks. security-events: write is needed only for the SARIF upload step; remove that permission, the entire upload step, and sarif-output if you do not use code scanning. The upload runs even if the check fails, when a SARIF file exists. The check uses the file’s policy (breaking changes and inspection errors fail by default). Push your commit and open a pull request to run it; unchanged reachable services should pass. SARIF upload is optional and requires code scanning to be available for your repository.

Useful inputs, all optional:

• dependencies: path to the dependencies file (default .interfacedelta/dependencies.json).
• fail-on: comma-separated breaking (default), non_breaking, indeterminate, informational, metadata.
• on-error: fail (default) or warn; a dependency that cannot be reached is then a warning, not a failure.
• sarif-output: write a SARIF 2.1.0 file for GitHub code scanning.
• url, mcp-endpoint, baseline: check one service instead of the file.

Watch it hosted (optional)

The workflow above checks pull requests. Hosted watching requires Pro or Team. Hosted InterfaceDelta checks continuously and delivers each decision to its owner (Slack, a signed webhook, a GitHub issue, or email) before the next build breaks. Sync the same dependencies file from CI with either the CLI or the Action:

export INTERFACEDELTA_API_TOKEN=...   # a watch token from Routing → Watch tokens, with lockfiles:write
interfacedelta watch

Create a separate .github/workflows/interfacedelta-watch.yml (replace main if your default branch has another name):

name: InterfaceDelta watch
on:
  push:
    branches: [main]
    paths: ['.interfacedelta/**']
  workflow_dispatch:
permissions:
  contents: read
jobs:
  watch:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
      - uses: arto-a/interfacedelta-action@c06ddb383cbd5d4b4fe487e9af7906f155d72257 # v0.4.0
        with:
          check: false
          watch: true
          api-token: ${{ secrets.INTERFACEDELTA_WATCH_TOKEN }}

The Action form runs on your default branch whenever the file changes, with actions/checkout set to fetch-depth: 0 so commit order can be proved. Baselines stay in your repository and are not uploaded.

Create the token in the site under Routing, in Watch tokens: each token is bound to one repository and branch, and watch needs the lockfiles:write scope. Store it as the INTERFACEDELTA_WATCH_TOKEN repository secret and pass it through the Action’s api-token input. The CLI reads that same watch-token value from INTERFACEDELTA_API_TOKEN. Account REST API tokens do not grant repository watching. Configure destinations in Routing for delivery; GitHub issues also need the issues workflow in the delivery guide. Hosted observations are public, so they may differ from a local signed-in check.

Troubleshooting

Errors print as InterfaceDelta error: <message> on stderr. The examples below identify common failures; paths and validation details depend on your file.

The dependencies file is missing. Dependencies file could not be read: .interfacedelta/dependencies.json. Create it (see the README), or check one service with `interfacedelta check <url> --baseline <file>`. Run from the directory that contains .interfacedelta/, or pass --dependencies <file>.

The dependencies file is not valid JSON. Dependencies is not valid JSON. Fix the syntax; exit code 2.

A field is wrong. Dependencies file is invalid at <field>: <what is wrong>. The path after at names the field, for example dependencies.0.url. Common causes: a missing baseline, a formatVersion that is not exactly interfacedelta-dependencies-v1, an unknown field, or a name with a character outside letters, digits, ., _, -.

A baseline file is missing. Baseline file could not be read: /your/repo/.interfacedelta/docs-search.json. Record one with `interfacedelta baseline`. Run interfacedelta baseline, then commit the new file.

A baseline path escapes the directory. Dependencies file is invalid at dependencies.0.baseline: A baseline is a relative .json path inside the dependencies directory. Baselines must stay within the dependencies directory; move the file and fix the path. Duplicate names and shared baselines fail the same way, with Duplicate dependency name: <name> or Two dependencies share the baseline <path>.

A service cannot be inspected (exit 3). The dependency is listed with ERROR (inspection) and the run exits 3. A network failure, timeout, or server error can be downgraded to a warning with --on-error warn (or "onError": "warn" in the file). Configuration, credential and unexpected internal errors always fail, whatever on-error says.