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 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)

Installation​

Install the CLI with Go:

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

Command surface​

Main command:

uigraph 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, or schema files.
  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 sync --dry-run
uigraph 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

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: 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

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

What happens during sync​

When you run uigraph 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 API groups
  5. Sync architecture diagrams
  6. Sync test packs and then test cases
  7. Sync databases

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 and database config before rollout

Notes for platform teams​

  • The CLI validates referenced files for APIs, architecture diagrams, and databases 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​