docs(CLI): generate CLI v2 code samples from the spec

.github/workflows/lint.yml

@@ -21,6 +21,7 @@ jobs:
           node-version: "24.14.1"
       - run: npm install
       - run: npx swagger-cli bundle -t json -w 300 main.yaml > doc/compiled_new.json
+      - run: node scripts/inject-cli-examples.js doc/compiled_new.json
       - run: diff doc/compiled.json doc/compiled_new.json
 
   compile-go:

Makefile

@@ -1,3 +1,5 @@
+.PHONY: run lint bundle examples watch_bundle ruby go typescript python java php cli
+
 run:
 	make lint
 	make bundle
@@ -16,6 +18,15 @@ lint:
 bundle:
 	npx swagger-cli bundle -t json -w 300 main.yaml > doc/compiled.json
 	npx swagger-cli bundle -t yaml -w 300 main.yaml > tmp/compiled.yaml
+	node scripts/inject-cli-examples.js doc/compiled.json tmp/compiled.yaml
+
+# Regenerate examples/cli.yaml from the bundled spec (examples-only, no client build).
+# Needs Java/openapi-generator, so it is part of client generation (see `cli`),
+# not `bundle`. Run this manually after changing an endpoint's parameters or
+# x-cli-command, then re-run `make bundle` to inject the refreshed examples.
+# Requires tmp/compiled.yaml to exist (produced by `make bundle`).
+examples:
+	npx openapi-generator-cli generate -i tmp/compiled.yaml -g go -o tmp/cli-examples -c ./openapi-generator/cli_examples_lang.yaml -e handlebars
 watch_bundle:
 	make lint
 	npx swagger-cli bundle -t json -w 300 main.yaml > doc/compiled.json
@@ -41,3 +52,5 @@ cli:
 	go install golang.org/x/tools/cmd/goimports@v0.24.0
 	goimports -w clients/cli
 	cd clients/cli && go mod tidy
+	make examples
+	make bundle

README.md

@@ -29,10 +29,26 @@ The `change_type` is one of the following:
 You added an endpoint in Phrase Strings. In this project you do the following:
 
 1. Add newly added schema (if any) to `/schemas/` directory and to `schemas.yaml`
-2. Add new endpoints to `/paths/` directory and reference it in `paths.yaml`
+2. Add new endpoints to `/paths/` directory and reference it in `paths.yaml`. Each
+   path file must include an `x-cli-command` field with the CLI command for the
+   endpoint, e.g. `x-cli-command: screenshots create` (the parent command plus the
+   subcommand). This drives the auto-generated CLI code sample.
 3. `npm start` to re-build the clients
 4. Open a PR with an informative title (e.g. `feat(API): Add an API endpoint for cat pics`)
 
+### CLI code samples
+
+The `CLI v2` entries in `x-code-samples` are **generated**, not hand-written. They
+are produced into `examples/cli.yaml` from each endpoint's `x-cli-command` and
+parameters (during `make cli` / `npm start`, which needs Java) and injected into
+the compiled spec (`doc/compiled.json`) during `make bundle` (Node only). Do not
+add `CLI v2` samples to path files by hand — only the hand-written `Curl` sample
+and the `x-cli-command` field belong there.
+
+`examples/cli.yaml` is committed and kept in sync by `npm start`. If you change an
+endpoint's parameters or `x-cli-command` without a full rebuild, run `make examples`
+then `make bundle` to refresh it.
+
 ## Workflow
 
 The following repositories are generated upon pushing to this one: