UIGraph CLI

uigraph-cli is a repository-driven sync tool for keeping UIGraph aligned with the artifacts already stored in source control.

The CLI is intentionally small:

one config file: .uigraph.yaml
one required secret: UIGRAPH_TOKEN
one required target: the gateway (--enterprise, UIGRAPH_GATEWAY_URL, or --api-url)

What the CLI syncs

From one config file, the CLI can sync:

Service metadata (service)
API specs (apis)
Service dependencies (dependencies)
Mermaid architecture diagrams (architectureDiagrams)
Test packs and test cases (testPacks, with optional external testCasesPath and reference screenshots)
Database schemas (databases)
Saved queries (queries, with optional external queryFiles)
Documentation files (docs)
Maps, frames, and focal points (maps)
Cloud cost attribution rules (costTags)
Timeline events scanned from ADRs, postmortems, and a changelog (timeline)
ML models and experiments pulled from MLflow (ml)

Installation

Install the CLI with Go:

go install github.com/uigraph-oss/uigraph-cli@latest

This installs a binary named uigraph-cli, which is what every example in these docs uses.

Command surface

Two commands:

uigraph-cli sync      # reconcile everything in .uigraph.yaml
uigraph-cli release   # record one release on the service timeline

sync is the command you run on every push. release is for a tag-triggered CI job and writes a single timeline event — see Timeline and Releases.

Flags supported by sync:

--config (default: .uigraph.yaml)
--dry-run (prints payloads without sending)
--api-url (gateway URL, overrides UIGRAPH_GATEWAY_URL)
--enterprise (sync to hosted UIGraph, --enterprise=DEV for the development environment)
--verbose (logs every MLflow and gateway request with how long it took)

release supports those five plus --version, --date, --notes, --notes-file, --changelog, and --title.

Reach for --verbose when a sync is slow or a request is failing and you want to see which call is responsible.

Required environment variables for both:

UIGRAPH_TOKEN
UIGRAPH_GATEWAY_URL (unless you pass --enterprise or --api-url)

Gateway URL

Every command needs one gateway to sync to. There is no default, so a command with none of the three options below exits with code 1.

Hosted UIGraph

Pass --enterprise and the CLI resolves the URL itself, so there is nothing to set:

uigraph-cli sync --enterprise

Add =DEV to reach the development environment instead:

uigraph-cli sync --enterprise=DEV

Self-hosted gateway

Set the URL with UIGRAPH_GATEWAY_URL, or pass --api-url to override it for one command:

export UIGRAPH_GATEWAY_URL=https://gateway.your-org.com

Use the host where you expose uigraph-gateway. In the bundled Docker Compose stack it listens on port 8081.

Pick one

--api-url and --enterprise cannot be passed together. When both --enterprise and UIGRAPH_GATEWAY_URL are set, the flag wins.

Quick start

Create .uigraph.yaml in your repository root.
Add referenced files such as OpenAPI specs, Mermaid diagrams, schema files, or documentation assets listed under docs.
Set UIGRAPH_TOKEN in your shell or CI secret store.
Choose your gateway: set UIGRAPH_GATEWAY_URL, or add --enterprise on hosted UIGraph.
Run a validation pass with dry run.
Run real sync in CI on your main branch.

Example:

export UIGRAPH_TOKEN=your-token
export UIGRAPH_GATEWAY_URL=https://gateway.your-org.com
uigraph-cli sync --dry-run
uigraph-cli sync

The same run against hosted UIGraph needs only the token:

export UIGRAPH_TOKEN=your-token
uigraph-cli sync --enterprise --dry-run
uigraph-cli sync --enterprise

Minimal .uigraph.yaml

version: 1

service:
  name: Booking Service
  category: Backend
  description: Handles booking lifecycle and availability
  repository:
    provider: github
    url: https://github.com/company/booking-service

Supported config sections

Top-level sections currently supported by the CLI:

version
service
apis
dependencies
architectureDiagrams
testPacks
databases
queries
queryFiles
docs
maps
costTags
timeline
ml

service is required to sync apis, dependencies, architectureDiagrams, testPacks, databases, queries, docs, costTags, and timeline. A config without a service may only sync maps and their frames.

Example full config

version: 1

service:
  name: Booking Service
  category: Backend
  description: Handles booking lifecycle and availability
  repository:
    provider: github
    url: https://github.com/company/booking-service
  ownership:
    team: platform
    email: platform@company.com
  labels:
    - core
  integrations:
    slack:
      url: https://example.slack.com/archives/C123
    jira:
      url: https://example.atlassian.net/browse/PROJ

apis:
  - name: public-api
    type: openapi
    path: ./openapi.yaml

dependencies:
  - name: payments-charges
    service: Payments Provider
    direction: downstream
    type: http
    criticality: hard
    description: Charges customer cards through the payments provider.

architectureDiagrams:
  - name: System Context
    path: ./diagram.mmd
    contextPath: ./context.json

testPacks:
  - name: checkout-smoke
    type: smoke
    testCases:
      - type: api
        title: create-order returns 201
        order: 1
        apiGroupName: public-api
        operationId: createOrder
        expectedStatusCode: 201
        requestTemplate: '{"amount": 100}'
        isCritical: true
        screenshots:
          - ./.uigraph/tests/screenshots/create-order.png

databases:
  - name: Core PostgreSQL Database
    dbType: PostgreSQL
    dialect: postgres
    schemaPath: ./schema.sql

queries:
  - name: orphaned-orders
    database: Core PostgreSQL Database
    queryText: "SELECT * FROM orders WHERE customer_id IS NULL"
    tags: [data-quality]

queryFiles:
  - ./.uigraph/queries/reporting.yaml

docs:
  - name: README
    path: ./README.md
    fileType: markdown
  - name: API Specification
    path: ./api_spec_detail.html
    fileType: html
  - name: Product overview
    path: ./product-overview.pdf
    fileType: pdf

costTags:
  - key: team
    value: platform
  - key: Service
    value: booking-api

timeline:
  decisions:
    paths:
      - docs/adr/*.md
  incidents:
    paths:
      - docs/postmortems/*.md

What happens during sync

When you run uigraph-cli sync, the CLI currently performs this sequence:

Read UIGRAPH_TOKEN and resolve the gateway URL
Load and validate .uigraph.yaml (merging any queryFiles and testCasesPath files)
Capture best-effort git metadata
Sync the service record
Sync database schemas, then saved queries
Sync API groups
Sync service dependencies
Reconcile cost tags
Sync architecture diagrams
Sync test packs, then test cases — uploading each case's reference screenshots as it goes
Sync documentation files
Scan the repository for timeline events and upsert them
Sync maps, frames, focal points, and components
Pull ML projects from MLflow and sync models, experiments, and runs
Print the summary

Dry run behavior

Use --dry-run when you want to validate config and inspect what the CLI would send without writing anything to UIGraph.

A dry run reaches no gateway, so it needs neither UIGRAPH_TOKEN nor a gateway URL. You can validate a config before you have a token. Configs with an ml: section still read from MLflow, because that is where the models and experiments come from.

Dry run is especially useful for:

pull requests
onboarding a new repository
validating file paths in CI
checking test pack, database, and documentation config before rollout

Notes for platform teams

The CLI validates referenced files for APIs, architecture diagrams, databases, documentation, and test case screenshot paths before sync.
Git metadata is captured when available, but sync can continue without it.
costTags is declarative: when the section is present, the config owns the full set and unlisted rules are deleted.
For API-linked test cases, apiGroupName and operationId should point to synced API content that UIGraph can resolve.
The service-account token needs services:write for the catalog, plus billing:write for costTags and timeline:write for timeline events and uigraph-cli release.