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 command: uigraph-cli sync
  • one config file: .uigraph.yaml
  • one required secret: UIGRAPH_TOKEN

What the CLI syncs​

From one config file, the CLI can sync:

  • Service metadata (project, service)
  • API specs (apis)
  • Mermaid architecture diagrams (architectureDiagrams)
  • Test packs and test cases (testPacks)
  • Database schemas (databases)
  • Documentation files (docs)

Installation​

Install the CLI with Go:

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

Command surface​

Main command:

uigraph-cli sync

Supported flags in the current implementation:

  • --config (default: .uigraph.yaml)
  • --dry-run (prints payloads without sending)

Required environment variable:

  • UIGRAPH_TOKEN

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. Run a validation pass with dry run.
  5. Run real sync in CI on your main branch.

Example:

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

Minimal .uigraph.yaml​

version: 1

project:
  name: my-product

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
  • project
  • service
  • apis
  • architectureDiagrams
  • testPacks
  • databases
  • docs

Example full config​

version: 1

project:
  name: my-product
  environment: production

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: [email protected]
  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

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

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

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

What happens during sync​

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

  1. Load and validate .uigraph.yaml
  2. Capture best-effort git metadata
  3. Sync the service record
  4. Sync database schemas
  5. Sync API groups
  6. Sync architecture diagrams
  7. Sync test packs and then test cases
  8. Sync documentation files

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, and documentation paths before sync.
  • Git metadata is captured when available, but sync can continue without it.
  • The CLI does not currently expose multiple subcommands; sync is the public surface area.
  • For API-linked test cases, apiGroupName and operationId should point to synced API content that UiGraph can resolve.

Next guides​