Onboard with a Coding Agent

Use this guide from the repository root with a coding agent that supports skills, such as Claude Code, Cursor, or Codex.

The agent will inspect the repository, generate .uigraph.yaml and the artifacts under .uigraph/, validate them, and sync them to UIGraph. It must not change application code. Nothing is sent to UIGraph until the sync command runs.

Before running the UIGraph skill, the agent must select a CLI runner and configure access to the target UIGraph workspace. It should inspect the machine and repository first. It should ask only when missing information would affect the artifacts or prevent the sync. The engineer must provide any required credentials and have permission to create a service in the target UIGraph workspace.

1. Select a CLI runner

Select the first available runner in this order:

1. If uigraph-cli exists, select it.
2. Otherwise, if Go exists, select go run github.com/uigraph-oss/uigraph-cli@latest.
3. Otherwise, if Docker is running, select Docker.
4. Otherwise, stop. Discuss how to proceed with the engineer.

Do not install the CLI, Go, or Docker. Do not change PATH or ask the engineer to restart their shell. Keep the selected runner for every command in this guide.

Dry-run examples:

For Docker, run the complete command from the repository root:

docker run --rm \
  -e UIGRAPH_TOKEN \
  -e UIGRAPH_GATEWAY_URL \
  -v "$(pwd):/workspace" -w /workspace \
  uigraph/uigraph-cli:latest sync --dry-run

Use ${PWD}:/workspace for the mount in Windows PowerShell. Add --network host if a self-hosted gateway runs on localhost.

2. Set up authentication

Use an existing UIGRAPH_TOKEN if one is available. Never print it or write it to the repository.

If a token is not available, a workspace admin must create one:

1. In UIGraph, open Settings, then Service Accounts.
2. Select Create Service Account and name it, for example Coding Agent.
3. Grant read and write access to Services, Diagrams, Docs, Maps, and Timeline.
4. Open the account, select Create Token, and copy the token immediately. UIGraph shows it only once.

Export it in the shell that will run the sync:

export UIGRAPH_TOKEN="uig_your_token_here"

Choose the destination

Choose the destination that matches the UIGraph workspace:

For a self-hosted workspace:

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

The CLI does not use UIGRAPH_API_URL. The token and, for a self-hosted workspace, the gateway URL must be available in the shell that runs the sync. A dry run needs neither because it does not send data.

3. Install the UIGraph skill

npx skills add uigraph-oss/skills

The skill does not require the UIGraph MCP server. Install UIGraph MCP only if the agent needs to read existing data from UIGraph.

If the skill is not available in the current session after installation, locate and read its installed SKILL.md, then follow its instructions manually. All artifacts must be generated through the skill or its manually loaded instructions.

4. Generate artifacts with the skill

Use the installed UIGraph skill to generate the artifacts.

The skill follows this required workflow:

1. Inspect the repository for API specifications, routes, migrations, schemas, documentation, diagrams, tests, deployment configuration, service metadata, and calls to other services or datastores.
2. Ask the engineer which supported categories to generate: APIs, service dependencies, database schemas, architecture diagrams, docs, test packs, maps, and optional helper scripts. Offer cost tags and timeline only when the repository contains evidence for them.
3. Resolve ownership, service boundaries, naming, and repository metadata from project evidence. Ask only when an unresolved detail would materially affect the output.
4. Present a final plan that lists the files to create or update, detected sources, assumptions, validation steps, and any helper scripts under .uigraph/scripts/.
5. Wait for an approval message containing Generate. Generate the artifacts is valid. Go ahead and Yes are not.
6. Generate only the approved files under .uigraph/ and create .uigraph.yaml at the repository root.
7. Validate the generated files and fix only files created during this run.

5. Validate the artifacts

Run the dry-run command for the selected runner from step 1. It validates .uigraph.yaml, checks every referenced file, and shows what the sync would send without uploading it.

An ml: configuration still reads from MLflow during a dry run so the CLI can list its models and experiments.

6. Sync and verify

After the dry run passes, run the same command without --dry-run.

Add --enterprise for hosted UIGraph. With Docker, use the container command from step 1. Then open Services in UIGraph and verify the service and its artifacts.

To keep the artifacts current, run the same sync from CI. See CI/CD Setup.

Workflow

Related guides

• CLI overview