Getting Started

Monitor your first source in under five minutes.

Create an account on the website, install the tch CLI, and watch TrackChanges catch a change, diff it, and tell you about it.

01Create an account

Sign up at trackchanges.io/app/signup.html with your email and a password, and accept the Terms of Service and Privacy Policy. We email you a 6-digit code; enter it on the next screen and your account, first workspace, and API key are created.

The code expires after 30 minutes and allows 5 attempts. If the address already has an account, the email says so instead of carrying a code — sign in or reset your password.
Your API key is shown once. Copy it before you leave the page if you want to log the CLI in with it (step 03). If you don't, tch login creates a key for you.

02Install the CLI

The CLI needs Python 3.12 or newer and installs one command, tch.

$ pip install trackchanges-cli
$ tch --help

03Log in

Log in with your email and password. We email a 6-digit login code; the CLI then creates an API key for this machine and saves it to ~/.trackchanges/config.

$ tch login
# email, password, then the 6-digit code from the email

Or use the API key from step 01. The CLI prompts for it, so it never ends up in your shell history.

$ tch login --api-key
$ tch whoami
# your email, account, workspace and role

04Subscribe to a source

Point TrackChanges at any OpenAPI or Swagger spec, JSON or YAML. The first version is stored right away, and polling starts at your workspace's default interval (daily unless you change it).

$ tch subscribe https://api.example.com/openapi.json --alias my-api
# silence is success — no output means it worked
$ tch sources
$ tch poll set-interval my-api 6h
Your plan sets how many sources you can subscribe to — see pricing.

05Versions and diffs

Every change is stored as a new version, and each new version is diffed against the one before it and classified as breaking or non-breaking.

$ tch versions my-api
$ tch view my-api
# the latest stored spec; add a version (e.g. v2) for an older one
$ tch diffs my-api
$ tch diff my-api v1 v2
$ tch show-diff <diff_id>

06Email notifications

Add the people who should hear about changes. By default they're emailed for breaking changes only; any_change sends every change.

$ tch notify add-email my-api alerts@company.com
$ tch notify add-email my-api api-team@company.com --trigger any_change
$ tch notify list-emails my-api
An address that isn't a verified member of your account gets a confirmation email first, and receives notifications only after it confirms. Every notification carries an unsubscribe link.

07Webhooks

Have changes POSTed to your own systems — a CI job, Slack, an agent. Webhook URLs must be public https addresses. Adding and testing webhooks needs the admin role (account owners have it).

$ tch poll add-webhook my-api https://hooks.example.com/trackchanges --alias ci
$ tch poll test-webhook my-api
$ tch poll list-webhooks my-api

The payload is described in Webhooks.

08Invite a teammate

Invite someone to your workspace with a role: admin, member or readonly.

$ tch invite send amy@company.com --role member
$ tch invite list

The invite email has a link to accept it in the browser, plus a token for the CLI. In the CLI, tch accept-invite shows the workspace, role and invited address, then asks for one password: the existing one if your teammate already has a TrackChanges account, otherwise a new one:

$ pip install trackchanges-cli
$ tch accept-invite <token>

Once they've joined, they show up in your member list:

$ tch members list
Your plan sets how many members an account can have; pending invites count toward it.