Most YMLs used here are pulled from the source-of-truth openapi repo via a git submodule. In rare cases, the full description of an API is too complex for our codegen tooling to handle; the overrides/ directory contains alternate definitions for paths/schemas that work around these cases. cli.yml ties together all the pieces by linking all routes and schemas used by the CLI.

Updating the API contract

To extend/modify the API contract used by the CLI, first make sure the openapi submodule is cloned and up-to-date:

# Run from the project root.
git submodule update --init --recursive

Then create a new branch to track your work:

git checkout <new-branch-name>

Next, decide if any modifications are needed in the source-of-truth openapi repo. If so, create a branch in the submodule to track changes there:

cd api/contract/openapi && git checkout -b <new-branch-name>

Edit/add to the files under api-contract/ to describe the new API contract. Run the following from the project root test your changes and see the outputs in Go code:

make openapi
# Use `git status` to see new/modified files under `api`

Once you're happy with the new API contract, submit your changes for review & merge. If you added/edited files within openapi, you'll first need to:

Push your submodule branch to GitHub

cd api/contract/openapi && git push <your-branch-name>

Create a PR in openapi, eventually merge to master there

Update your submodule to point at the merge result:

cd api/contract/openapi && git fetch && git checkout master && git pull origin master

Update the submodule reference from the main repo:
```
git add api/contract/openapi
git commit
```