Quick start

Get Homogenic running in your GitHub repo in under 5 minutes. You'll need an OpenAPI spec (YAML or JSON) and a Homogenic account — the Free plan is enough to start.

1. Install the CLI

Install globally via npm or brew:

npm install -g @homogenic/cli
# or
brew install homogenic-io/tap/homogenic

Verify the install:

homogenic --version
2.4.0

2. Initialize in your project

Run homogenic init in your repo root. It will walk you through connecting your OpenAPI spec and linking your GitHub repo.

cd your-project
homogenic init

✔ Found openapi.yaml in project root
✔ Authenticated with GitHub (your-org/your-repo)
✔ Connected to Homogenic project "my-api"
✔ Wrote .homogenic.yaml config file

Run "homogenic check" to validate your spec.

3. Run your first check

homogenic check --spec ./openapi.yaml

Checking openapi.yaml against last known good (2026-05-14T09:41:22Z)...

✓ No schema drift detected
✓ 247 endpoints validated
✓ 0 breaking changes
✓ 0 non-breaking changes

4. Add to GitHub Actions

Add the Homogenic action to your pull request workflow. It will block PRs that introduce breaking schema changes.

# .github/workflows/homogenic.yml
name: Schema Check
on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: homogenic-io/action@v2
        with:
          spec: ./openapi.yaml
          token: ${{ secrets.HOMOGENIC_TOKEN }}

Add your Homogenic token to GitHub repo secrets as HOMOGENIC_TOKEN. Find your token in the Homogenic dashboard → Settings → API tokens.

CLI reference

homogenic check

Validate a spec for drift against the last known baseline.

Flag	Description
--spec <path>	Path to OpenAPI YAML/JSON or JSON Schema file
--format [text|json|sarif]	Output format. Default: text
--fail-on [breaking|any|none]	When to exit with non-zero. Default: breaking
--baseline <sha>	Compare against a specific git SHA

homogenic diff

Compare two spec versions directly.

homogenic diff --from ./openapi-v1.yaml --to ./openapi-v2.yaml

homogenic watch

Monitor a running API server in real time. Alerts on drift as responses change.

homogenic watch --spec ./openapi.yaml --base-url http://localhost:3000

homogenic report

Generate a drift report for a time range. Useful for weekly reviews.

homogenic report --since 7d --format json > drift-report.json