Skip to main content

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.

Binary name

Some installation methods name the same tool uigraph instead. If yours did, drop the -cli suffix from every command below — uigraph-cli sync becomes uigraph sync.

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​

  1. Create .uigraph.yaml in your repository root.
  2. Add referenced files such as OpenAPI specs, Mermaid diagrams, schema files, or documentation assets listed under docs.
  3. Set UIGRAPH_TOKEN in your shell or CI secret store.
  4. Choose your gateway: set UIGRAPH_GATEWAY_URL, or add --enterprise on hosted UIGraph.
  5. Run a validation pass with dry run.
  6. 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:

  1. Read UIGRAPH_TOKEN and resolve the gateway URL
  2. Load and validate .uigraph.yaml (merging any queryFiles and testCasesPath files)
  3. Capture best-effort git metadata
  4. Sync the service record
  5. Sync database schemas, then saved queries
  6. Sync API groups
  7. Sync service dependencies
  8. Reconcile cost tags
  9. Sync architecture diagrams
  10. Sync test packs, then test cases — uploading each case's reference screenshots as it goes
  11. Sync documentation files
  12. Scan the repository for timeline events and upsert them
  13. Sync maps, frames, focal points, and components
  14. Pull ML projects from MLflow and sync models, experiments, and runs
  15. 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.

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.

Next guides​