Artifacts agent
uigraph-agents artifacts init # generate the first config and artifacts
uigraph-agents artifacts sync # update the artifacts your code outgrew
uigraph-agents artifacts fix "<text>" # repair what a chunk of text says is wrong
The artifacts agent writes and maintains the artifacts declared in .uigraph.yaml, such as OpenAPI specs, Mermaid diagrams, SQL schemas, saved queries, and docs.
Running uigraph-agents artifacts with no command prints the help and stops.
New to it? Start with Setup.
What it can change
The agent can edit the artifacts you listed in .uigraph.yaml, plus the config file itself. It refuses to write anywhere else.
The agent reads your code to understand what changed. The only files it can modify are your UIGraph artifacts.
The agent needs internet access on each run.
init
Run init once, in a repository that is not onboarded yet. It reads the whole repository and writes .uigraph.yaml and the artifacts under .uigraph/.
uigraph-agents artifacts init
init does not need a UIGraph token.
Starting from a config you already seeded
If you already have a minimal .uigraph.yaml holding your identity values, add --seeded:
uigraph-agents artifacts init --seeded
The agent keeps those values as written and fills in the artifacts around them. Seed the file with the project name, service name, repository provider and URL, and owning team. This is what the GitHub onboarding workflow uses.
If a run crashes or you interrupt it, --seeded puts your seed file back and removes the files that run created, so you can start again cleanly.
sync
Run sync on every push. It compares what changed in your repository against your declared artifacts and updates the ones that no longer match.
uigraph-agents artifacts sync --previous commit
Choosing what to check
| Flag | Use it when |
|---|---|
--previous commit | You run it on every push and want to check what the latest commit changed. |
--previous tag | You run it at release time and want everything that changed since the last release. |
--target <ref> | You want to compare against a specific commit or tag yourself. |
Pass one or the other, not both. With no flag at all, the agent checks uncommitted work.
fix
fix repairs what you describe and nothing else. Give it one chunk of raw text as its argument:
uigraph-agents artifacts fix "$(uigraph-cli sync --dry-run 2>&1)"
uigraph-agents artifacts fix "the payments dependency should be soft, not hard"
The text is used as given. A whole dry-run transcript, a single error, or a plain sentence all work. When nothing in the text is actually wrong, the agent changes nothing and tells you so.
fix is required to have context. Running it with an empty argument is an error.
Repairing a failed run
init and sync check their own work against the same rules uigraph-cli sync applies, and repair themselves until the result is clean. If a run still has errors when it stops, it keeps its files on disk and exits 1, so you can see what is left and repair it:
uigraph-agents artifacts init
PREVIOUS=""
while :; do
OUTPUT=$(uigraph-cli sync --dry-run 2>&1) && break
[ "$OUTPUT" = "$PREVIOUS" ] && break
PREVIOUS="$OUTPUT"
uigraph-agents artifacts fix "$OUTPUT"
done
The dry run is the gate. fix exits 0 whenever it completes, including when it changed nothing, so a non-zero exit means the run itself failed. The loop ends when the dry run passes, or when a round produces the same output as the round before it.
Options
These apply to init, sync, and fix unless noted.
| Flag | Description |
|---|---|
--cwd [path] | Directory to run in. Defaults to the current directory. |
--config [path] | Agent config file. Defaults to the standard lookup. |
--uigraphConfig [path] | Path to .uigraph.yaml. Defaults to .uigraph.yaml. |
--model [id] | Model identifier. Same as AI_PROVIDER_MODEL. |
--npm [pkg] | Provider package. Same as AI_PROVIDER_NPM. |
--apiUrl [url] | Provider base URL. |
--enterprise [DEV] | Record the run on hosted UIGraph instead of setting UIGRAPH_API_URL. Add DEV for the development environment. |
--report [path] | Write the report to a file instead of stdout. See below. |
--verbose | Show what the agent is doing as it works. |
--seeded | init only. Keep the identity values from an existing minimal config. |
--target [ref] | sync only. Git commit or tag to compare against. |
--previous [commit|tag] | sync only. Compare against the previous commit or tag. |
--dryRun | sync only. Report drift without writing any file. |
Where the report can go
For sync and fix, --report must stay inside the repository.
For init, the report goes to stdout by default. If you pass --report, it must be an absolute path, outside the repository, and must not already exist. A runner temporary directory is the usual choice.
Output
Each change is printed as it is applied:
edit: .uigraph/openapi/booking-api.yaml
write: .uigraph/diagrams/booking-flow/booking-flow.mmd
Under --dryRun the same lines are suffixed (dry run) and nothing is written. Anything the agent could not resolve is printed as unresolved: <error>. The full report follows on stdout, or goes to --report if you passed it.
Example
# Onboard a repository for the first time
uigraph-agents artifacts init --verbose
# See what a push would change, without touching anything
uigraph-agents artifacts sync --previous commit --dryRun --verbose
# Apply the updates and save the report
uigraph-agents artifacts sync --previous commit --report artifacts-report.md
To have CI commit the results, see CI/CD.