Catalog Sync CLI

Use the rootly-catalog-sync CLI to keep services, teams, and metadata in your Rootly Catalog continuously synced from GitHub, Backstage, APIs, and more.

rootly-catalog-sync is a standalone CLI tool that reconciles external sources of truth into Rootly’s Catalog. It pulls data from your existing systems — GitHub repos, Backstage, internal APIs, CSV files, or any command — and syncs it one-way into Rootly, keeping services, teams, and metadata up to date automatically.

Why use Catalog Sync?

• Single source of truth — your service catalog lives in GitHub, Backstage, or a database. Rootly mirrors it automatically.
• No manual data entry — add a service to your repo, it appears in Rootly on the next sync.
• Safe by default — deletes are opt-in, empty sources abort, prune ratio thresholds prevent mass deletion.
• Terraform-style workflow — plan to preview, apply to execute, status to check drift.

Install

# Homebrew
brew install rootlyhq/tap/rootly-catalog-sync

# Go
go install github.com/rootlyhq/rootly-catalog-sync/cmd/rootly-catalog-sync@latest

# Docker (mount your config + catalog data)
docker run --rm -e ROOTLY_API_KEY \
  -v $PWD/rootly-catalog-sync.yaml:/config.yaml:ro \
  -v $PWD/catalog:/catalog:ro \
  rootlyhub/rootly-catalog-sync sync --config=/config.yaml

# Helm (Kubernetes)
helm repo add rootly https://rootlyhq.github.io/helm-charts
helm install catalog-sync rootly/rootly-catalog-sync \
  --set rootly.apiKey=$ROOTLY_API_KEY \
  --set-file configYaml=rootly-catalog-sync.yaml

Quick start

export ROOTLY_API_KEY=rootly_...

# Option 1: Scaffold a complete working example (recommended)
rootly-catalog-sync init --demo

# Option 2: Create a minimal config to customize
# rootly-catalog-sync init

# Then run:
rootly-catalog-sync doctor   # verify auth + connectivity
rootly-catalog-sync plan     # preview changes
rootly-catalog-sync sync     # apply

Authentication

Two methods are supported, in priority order:

API key (CI / non-interactive)

export ROOTLY_API_KEY=rootly_...

Create an API key at Settings → API Keys in your Rootly dashboard.

OAuth 2.0 (interactive)

# Login via browser (Authorization Code + PKCE)
rootly-catalog-sync login

# Tokens saved to ~/.rootly-catalog-sync/config.yaml
# Auto-refreshed transparently on expiry

# Clear stored tokens
rootly-catalog-sync logout

If ROOTLY_API_KEY is set, it always takes precedence over OAuth tokens.

Configuration

The sync tool uses a declarative config file (v2 format) that defines sync entries — each entry connects a source to a catalog or native resource target.

YAML

version: 2
sync:
  - from:
      local:
        files: ["catalog/*.yaml"]
    to: Services
    map:
      external_id: "{{ .id }}"
      name: "{{ .name }}"
      owner: "{{ .owner }}"
      tier: "{{ .tier }}"

version: 1
sync_id: services
pipelines:
  - sources:
      - local:
          files: ["catalog/*.yaml"]
    outputs:
      - catalog: "Services"
        external_id: "{{ .id }}"
        name: "{{ .name }}"
        fields:
          owner: "{{ .owner }}"
          tier: "{{ .tier }}"

{
  version: 2,
  sync: [
    {
      from: {
        "local": {
          files: ["catalog/*.yaml"],
        },
      },
      to: "Services",
      map: {
        external_id: "{{ .id }}",
        name: "{{ .name }}",
        owner: "{{ .owner }}",
        tier: "{{ .tier }}",
      },
    },
  ],
}

version = 2

sync {
  from {
    local {
      files = ["catalog/*.yaml"]
    }
  }
  to = "Services"
  map = {
    external_id = "{{ .id }}"
    name        = "{{ .name }}"
    owner       = "{{ .owner }}"
    tier        = "{{ .tier }}"
  }
}

Config files are detected by extension: .yaml (default), .jsonnet, or .hcl. Credentials use $(ENV_VAR) substitution.

Sources

Source	Description
inline	Entries defined directly in config
local	YAML/JSON files from disk (glob patterns)
github	Files from GitHub repositories (supports ** patterns)
exec	Run a command, parse stdout as JSON/YAML
backstage	Backstage catalog API with pagination
graphql	Arbitrary GraphQL endpoint with cursor/offset pagination
csv	CSV files with header row
url	Fetch YAML/JSON from remote URLs
http	Generic REST API with JSONPath extraction

Inline source

from:
  inline:
    entries:
      - id: payments
        name: Payments Service
        owner: platform-team
        tier: critical
      - id: auth
        name: Auth Service
        owner: security-team
        tier: critical

Local source

from:
  local:
    files: ["catalog/*.yaml", "services/**/*.json"]

GitHub source

from:
  github:
    token: "$(GITHUB_TOKEN)"
    owner: acme
    repos: ["payments", "auth", "gateway"]
    files: ["**/catalog.yaml"]
    ref: main

Omit repos to scan all repositories in the org. Set archived: true to include archived repos.

Backstage source

from:
  backstage:
    url: https://backstage.internal.com
    token: "$(BACKSTAGE_TOKEN)"
    kind: Component
    filter: "kind=Component,metadata.annotations.rootly.com/sync=true"

Exec source

from:
  exec:
    command: bq
    args: ["query", "--format=json", "SELECT id, name, owner FROM dataset.services"]

GraphQL source

from:
  graphql:
    url: https://api.internal.com/graphql
    headers:
      Authorization: "Bearer $(API_TOKEN)"
    query: |
      query($cursor: String) {
        services(after: $cursor) {
          nodes { id name owner tier }
          pageInfo { hasNextPage endCursor }
        }
      }
    result: data.services.nodes
    paginate:
      cursor: data.services.pageInfo.endCursor
      has_next: data.services.pageInfo.hasNextPage

CSV source

from:
  csv:
    files: ["data/services.csv"]
    delimiter: ","

The first row is used as field names. Each subsequent row becomes an entry.

URL source

from:
  url:
    urls:
      - https://internal.company.com/catalog/services.yaml
      - https://internal.company.com/catalog/teams.json
    headers:
      Authorization: "Bearer $(API_TOKEN)"

HTTP source

from:
  http:
    url: https://api.internal.com/v1/services
    method: GET
    headers:
      Authorization: "Bearer $(API_TOKEN)"
    result: data.services

Output targets

Each sync entry uses to: to specify the target. The value of to: determines whether entries go to a custom catalog or a native Rootly resource.

• Native resource: use a lowercase type name — to: service, to: team, to: functionality, to: environment
• Custom catalog: use the catalog display name — to: "Services", to: "Tiers"

Custom catalog

Creates entities in a named Rootly catalog with arbitrary fields.

sync:
  - from:
      local:
        files: ["catalog/*.yaml"]
    to: "Services"
    map:
      external_id: "{{ .id }}"
      name: "{{ .name }}"
      owner: "{{ .owner }}"
      tier: "{{ .tier }}"

Native resources

Sync directly to built-in Rootly resource types.

Type	Description
service	Rootly services
functionality	Rootly functionalities
environment	Rootly environments
team	Rootly teams

sync:
  - from:
      local:
        files: ["catalog/services.yaml"]
    to: service
    map:
      external_id: "{{ .id }}"
      name: "{{ .name }}"
      description: "{{ .description }}"
      pagerduty_id: "{{ .pagerduty_id }}"
      github_repository_name: "{{ .repo }}"

sync:
  - from:
      local:
        files: ["catalog/teams.yaml"]
    to: team
    map:
      external_id: "{{ .id }}"
      name: "{{ .name }}"
      description: "{{ .description }}"
      opsgenie_id: "{{ .opsgenie_id }}"
      slack_channel: "{{ .slack_channel }}"

For native resources, known attributes (like description, pagerduty_id, github_repository_name) are set directly on the resource. Custom properties are auto-created on first sync for SDK-supported kinds (text, boolean, group, service, etc.). Reference properties are auto-created when the referenced catalog exists.

Custom properties

Native resources (services, teams, functionalities, environments) support custom properties that extend the built-in attributes. These properties are managed automatically during sync.

Auto-created properties

Text properties are auto-created on first sync. Simply include them in your map: and they will appear on the resource:

sync:
  - from:
      local:
        files: ["catalog/services.yaml"]
    to: service
    map:
      external_id: "{{ .id }}"
      name: "{{ .name }}"
      description: "{{ .description }}"
      cost_center: "{{ .cost_center }}"       # Auto-created as text property
      documentation_url: "{{ .docs_url }}"    # Auto-created as text property

Reference properties

Reference properties link native resources to catalog entities. To use them, first sync the referenced catalog, then reference it in the native resource mapping.

For example, to link services to a “Tiers” catalog:

tiers.yaml

- id: critical
  name: Critical
  sla: 99.99%
- id: standard
  name: Standard
  sla: 99.9%

rootly-catalog-sync.yaml

version: 2
sync:
  - from:
      local:
        files: ["tiers.yaml"]
    to: "Tiers"
    map:
      external_id: "{{ .id }}"
      name: "{{ .name }}"
      sla: "{{ .sla }}"

  - from:
      local:
        files: ["catalog/services.yaml"]
    to: service
    map:
      external_id: "{{ .id }}"
      name: "{{ .name }}"
      tier:
        value: "{{ .tier }}"
        reference: Tiers

The reference: Tiers shorthand tells the sync tool to resolve the human-readable tier name to the corresponding catalog entity UUID. Matching is case-sensitive and compares the field value against the catalog entity’s name (not external_id). The referenced catalog (“Tiers” in this example) must exist — sync it in an earlier sync entry so it is available when the service entry runs.

Template syntax

Field mappings use Go template syntax to transform source entries into output fields.

Field access

map:
  name: "{{ .name }}"                           # Direct field access
  owner: "{{ get .metadata \"team\" }}"         # Nested map access
  slug: "{{ .org }}/{{ .name }}"                # String concatenation
  tier: "{{ default .tier \"unknown\" }}"       # Fallback for nil/empty values
  region: us-east-1                              # Static value (no template needed)

Conditionals

environment: "{{ if .production }}prod{{ else }}staging{{ end }}"

Templates are compiled with missingkey=error — a missing field in the source data causes an immediate error rather than a silent empty string.

Commands

Command	Description
plan	Preview changes (creates a saved plan file)
apply <plan>	Apply a saved plan (validates freshness first)
sync	Plan + apply in one step
status	Read-only drift check (--fail-on-drift for CI gates)
init	Create a config file (add --interactive for guided wizard, --demo for a complete working example)
init --demo	Scaffold a complete working example with sample data and config
validate	Check config syntax
doctor	Verify API key, connectivity, and permissions
sources inspect	Dump raw source entries before mapping
explain <id>	Trace one entry through source → mapping → diff
adopt	Claim existing UI entries under sync management
import	One-shot seed (no prune, no lock)
watch	Continuous sync loop (--interval=5m)
tui	Interactive terminal UI for selective apply
login	Authenticate via browser OAuth 2.0 (PKCE)
logout	Clear stored OAuth tokens

Safety guarantees

• Deletes are opt-in — --allow-prune required, off by default
• Empty source aborts — never wipes a catalog on a source failure
• Prune ratio threshold — aborts if deletes exceed 20% of live entities (configurable via --prune-threshold)
• Manual entries are safe — only entries with external_id (created by sync) are prunable
• Order: create/update first, delete last — no window where entries are missing
• Plan freshness — apply validates that live state hasn’t changed since the plan was created

CI/CD integration

GitHub Actions

name: Catalog Sync
on:
  push:
    branches: [main]
    paths:
      - "catalog/**"
      - "rootly-catalog-sync.yaml"

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: stable
      - run: |
          go install github.com/rootlyhq/rootly-catalog-sync/cmd/rootly-catalog-sync@latest
          $(go env GOPATH)/bin/rootly-catalog-sync sync
        env:
          ROOTLY_API_KEY: ${{ secrets.ROOTLY_API_KEY }}

Dry-run on PRs

- run: rootly-catalog-sync plan --dry-run --output=json
  env:
    ROOTLY_API_KEY: ${{ secrets.ROOTLY_API_KEY }}

Nightly drift detection

- run: rootly-catalog-sync status --fail-on-drift
  env:
    ROOTLY_API_KEY: ${{ secrets.ROOTLY_API_KEY }}

Kubernetes deployment

Deploy catalog sync to Kubernetes using the official Helm chart:

helm repo add rootly https://rootlyhq.github.io/helm-charts
helm install catalog-sync rootly/rootly-catalog-sync \
  --set rootly.apiKey=$ROOTLY_API_KEY \
  --set-file configYaml=rootly-catalog-sync.yaml

By default the chart creates a CronJob that runs every 30 minutes.

To run in watch mode (continuous sync loop):

helm install catalog-sync rootly/rootly-catalog-sync \
  --set rootly.apiKey=$ROOTLY_API_KEY \
  --set-file configYaml=rootly-catalog-sync.yaml \
  --set mode=watch \
  --set watch.interval=5m

To include local data files referenced by your config, use a values file:

# values.yaml
rootly:
  apiKey: rootly_...
configYaml: |
  version: 2
  sync:
    - from:
        local:
          files: ["/data/services.yaml"]
      to: service
      map:
        external_id: "{{ .id }}"
        name: "{{ .name }}"
dataFiles:
  services.yaml: |
    - id: api-gateway
      name: API Gateway

helm install catalog-sync rootly/rootly-catalog-sync -f values.yaml

Environment variables

Variable	Description	Default
ROOTLY_API_KEY	API key (or use login for OAuth)	—
ROOTLY_API_URL	Override base URL	https://api.rootly.com
ROOTLY_API_PATH	Override API path prefix	/v1

Interactive TUI

The tui command launches a full-screen terminal UI for reviewing and selectively applying changes:

• Browse changes with colored badges (CREATE/UPDATE/DELETE/NOOP)
• Toggle individual changes with space, expand field diffs with enter
• Filter by operation type (c/u/d) or search (/)
• Detail pane shows full entity fields on wide terminals
• Apply only selected changes with A

Resources

• GitHub repository
• Helm chart
• Docker Hub
• Troubleshooting guide
• Template syntax reference
• Working examples