• references/ap-cli-reference.md

  — full

  ap

  CLI command reference (read when you need a command you're not sure about)

• references/api-yaml-examples.md

  — annotated RestApi YAML examples with policies (read before generating any YAML)

• references/docker-networking.md

  — Docker networking solutions (read before setting the upstream URL)

node

• scripts/install-ap-cli.js

  — downloads the ap CLI release matching the user's OS/arch and installs it (Step 1, Path B)

• scripts/setup-gateway.js

  — extracts the gateway release to

  ~/wso2-api-gateway/v<version>/

  and starts its Docker Compose stack (Step 3)

• scripts/init-local-cli-config.js

  — writes

  ~/.wso2ap/config.yaml

  with a

  dev

  entry pointing at the local gateway, using the gateway's documented public defaults (Step 4, fresh-local branch)

wso2/api-platform

main

• Gateway and REST-API docs →

  gw-docs-1.1.x

  (gateway 1.1.x release line)
• CLI docs →

  ap-docs-0.8.x

  (ap CLI 0.8.x release line)
• Gateway docs:

  https://github.com/wso2/api-platform/tree/gw-docs-1.1.x/docs/gateway

  — covers Kubernetes, observability, resiliency, analytics, policies, immutable gateway, policy languages and runtimes
• Gateway REST API docs:

  https://github.com/wso2/api-platform/tree/gw-docs-1.1.x/docs/rest-apis/gateway

  — covers the management REST API endpoints (operations on a RestApi and any state nested under it, plus controller-wide concerns like auth, secrets, certificates)
• Individual REST API doc files: live under

  https://github.com/wso2/api-platform/tree/gw-docs-1.1.x/docs/rest-apis/gateway/

  . Don't extrapolate filenames. List the directory (or fetch its

  README.md

  ) first, then fetch the specific raw URL. Filenames aren't one-per-feature — a single page often covers operations on a parent resource together with management of state nested under it. When a policy doc deflects with "… is handled outside this runtime policy" and gives no link, the answer almost always lives somewhere in this tree.
• CLI docs:

  https://github.com/wso2/api-platform/tree/ap-docs-0.8.x/docs/cli

  —

  reference.md

  ,

  quick-start-guide.md

  ,

  customizing-gateway-policies.md

I'll set up the WSO2 API Platform Gateway and expose your service.
Here's what I'll do:
✦ Install the ap CLI
✦ Confirm which gateway to use (set one up, or connect to one you have) 
✦ Connect the CLI to the gateway
✦ Deploy your API
✦ Test it end to end

I'll get the WSO2 API Platform Gateway running for you.
Here's what I'll do:
✦ Install the ap CLI
✦ Confirm which gateway to use (set one up, or connect to one you have) 
✦ Connect the CLI to the gateway
✦ Verify everything is healthy

ap

ap --help

ap

"

ap

CLI isn't installed. Would you like me to install it for you, or would you prefer to do it yourself?"

ap

ap --help

~/.local/bin/ap

%LOCALAPPDATA%\Programs\ap\ap.exe

node <absolute-path-to-skill>/scripts/install-ap-cli.js

ap installed at <path> (path-already-configured | path-added-to:<target> | path-update-failed:<target>)

<target>

User-Env

ap --help

ap --help

path-update-failed:<target>

ap

• Linux/macOS (

  <rc-file>

  ): "Heads up: I couldn't update

  <rc-file>

  automatically. To use

  ap

  in your own terminals, add this line to it:

  export PATH=\"$HOME/.local/bin:$PATH\"

  ."
• Windows (

  User-Env

  ): "Heads up: I couldn't update your User PATH automatically. To use

  ap

  in your own terminals, open

  Settings → Edit environment variables for your account

  and add

  %LOCALAPPDATA%\Programs\ap

  to

  Path

  ."

path-already-configured

path-added-to:<target>

ap --help

source ~/.zshrc

ap --help

Note for agent: From this point on, always invoke

ap

by its bare name — never the full install path.

ap gateway list

"I see these gateways are already registered with the CLI: <list>. Want to connect to one of these, or set up / connect to a different one?"

ap gateway use

ap gateway health

ap gateway use --display-name <picked>
ap gateway health

• Healthy → skip Steps 3 and 4 entirely; go straight to Step 5 / Phase 2.
• Unhealthy → diagnose before falling through. See Step 5 for how to read

  ap gateway health

  failures (a

  404

  almost always means the registered entry's

  --admin-server

  is missing/wrong; otherwise check whether the compose stack is running or the URL has moved). Surface the diagnosis to the user and offer to re-set-it-up or pick a different option — don't silently treat this as "no gateway".

ap gateway list

"Do you already have an API platform gateway you want to connect to, or should I set up a fresh local gateway?"

1. Management URL (

   --server

   , e.g.

   https://team-gw.example.com:9090

   or

   http://localhost:9091

   )
2. Admin URL (

   --admin-server

   , e.g.

   https://team-gw.example.com:9094

   )
3. Display-name to register it under. Default

   dev

   for a local custom-port instance; suggest something contextual like

   team

   or

   prod

   if the URL is non-local.
4. Auth method:

   none

   /

   basic

   /

   bearer

   . The fresh-local branch (Step 4) is fully automated — the agent runs a script that pre-registers the local gateway with its documented public defaults, no credential handling in chat. For an existing remote gateway, the user runs

   ap gateway add

   themselves in their own terminal so the CLI prompts them interactively for username/password (or token); the agent must not accept those credentials inline in chat. If the user pastes a password or token, do not echo it back, do not include it in any command, and do not store it.

curl -s --max-time 5 <admin-url>/api/admin/v0.9/health

• Healthy → skip Step 3 (no local install needed), go straight to Step 4 (existing-gateway sub-branch) with the user's URLs.
• Unreachable → tell the user the admin URL didn't respond and ask them to check the URL / VPN / firewall. Don't proceed to Step 4 until they confirm a working URL.

curl -s --max-time 3 http://localhost:9094/api/admin/v0.9/health

• Healthy → silently reuse. Tell the user "I see a gateway already running locally — using that. Ask me if you want a clean rebuild." Skip Step 3 and go to Step 4's fresh-local sub-branch (the script handles the local gateway with default credentials, regardless of whether the gateway was started this session or a previous one).
• Not healthy → continue to Step 3 to extract and start the local gateway.

docker --version

~/wso2-api-gateway/v<version>/

gateway

node <absolute-path-to-skill>/scripts/setup-gateway.js

gateway ready at /Users/.../wso2-api-gateway/v1.1.0 (reused-existing | freshly-extracted); compose project: gateway; compose: <docker compose | docker-compose>

compose:

• freshly-extracted

  — "Gateway extracted at

  ~/wso2-api-gateway/v1.1.0/

  . The Compose project name is

  gateway

  — to stop it later, cd into that directory and run

  <compose-from-summary-line> -p gateway down

  ."

• reused-existing

  — "Found an existing gateway extraction at

  ~/wso2-api-gateway/v1.1.0/

  — reusing it. If you want a fresh copy, ask me and I'll remove that directory and re-run setup."

curl -s http://localhost:9094/api/admin/v0.9/health

ap gateway add --display-name <name> --server <server-url> --admin-server <admin-server-url> [--auth <none|basic|bearer>]

--admin-server

ap gateway health

ap gateway add

~/.wso2ap/config.yaml

dev

http://localhost:9090

http://localhost:9094

admin

admin

~/wso2-api-gateway/v<ver>/configs/config.toml

[[controller.auth.basic.users]]

node <absolute-path-to-skill>/scripts/init-local-cli-config.js

• Stdout containing

  cli config initialized at <path-to-config.yaml> (created)

  — fresh write; continue.
• Stdout containing

  cli config initialized at <path-to-config.yaml> (local-already-registered)

  —

  dev

  entry already present from a prior session; continue.
• Non-zero exit with a message containing

  config.yaml already exists with other gateway entries

  — the user already has unrelated gateway entries the script won't touch. Surface the script's printed

  ap gateway add ...

  instruction to the user and have them run it themselves.

ap gateway add

"Please run this in your terminal. The CLI will prompt for credentials — enter them there, not here. Tell me when

ap gateway add

succeeds:

bash

ap gateway add --display-name <user-supplied-name> --server <user-supplied-server-url> --admin-server <user-supplied-admin-url> --auth <none|basic|bearer>
```"

ap

ap gateway use

ap gateway health

ap gateway apply

ap gateway health

404 page not found

--admin-server

Here's what I'll do to expose your API:
✦ Gather your service details
✦ Create the API resource file
✦ Publish it to the gateway
✦ Test the live endpoint

• If yes: ask them to share it (file path or paste it). Once received, offer:

  "Would you like to assess this spec before publishing?

  • Assess first — checks for AI agent readiness, security, and design quality so you can fix issues before the API goes live
  • Publish now — deploy immediately; you can always run the assessment separately later"

  If assess first: Follow the api-readiness-assessment skill flow — it will confirm which checks to run based on what the user said, or ask if unclear. After assessment (with or without fixes applied), ask:

  "Ready to continue — shall I generate the publishing YAML now?" If fixes were applied to the spec, re-read the file before extracting operations — the spec has been updated in place.

  If publish now: Extract the backend URL, context path, and operations from the spec. Skip asking about URL and endpoints separately.
• If no: ask for the backend URL and list of endpoints (method + path).

localhost:8081

localhost

localhost

undefined

Use that IP in `upstream.main.url` (e.g. `http://192.168.1.42:8081`).

For edge cases — backend itself running in Docker, or using `host.docker.internal` on Docker Desktop / Rancher / Colima — read `references/docker-networking.md`.

**Generate the RestApi YAML:**

Read `references/api-yaml-examples.md` for examples. Key rules:
- `metadata.name` must be unique, lowercase alphanumerics + `-` + `.` (e.g., `my-service-v1.0`)
- `context` must use `$version` placeholder (e.g., `/myservice/$version`)
- `upstream.main.url` must use the real host IP, not `localhost`
- **Check for a backend base path before setting `upstream.main.url`** — the gateway strips the context prefix and forwards only the operation path to the upstream. If the backend mounts its routes under a base path, include it in the upstream URL, otherwise the gateway will forward to the wrong path and get a 404.

  ```yaml
  # Backend serves routes under /restaurantInfo on port 8181
  url: http://192.168.1.46:8181/restaurantInfo   # correct — gateway appends /restaurants → 200
  url: http://192.168.1.46:8181                  # wrong  — gateway appends /restaurants → 404

• Add policies only if the user asked for them

<service-name>-api.yaml

ap gateway apply --file <service-name>-api.yaml
ap gateway rest-api list

curl http://localhost:8080/<context>/v1.0/<first-endpoint-path>

✓ Your API is live:
  GET http://localhost:8080/myservice/v1.0/users
  POST http://localhost:8080/myservice/v1.0/users

"Your API is live. What would you like to do next?

→ [Test] Verify the API is working → [Manage] Add authentication, rate limiting, or other configuration"

What would you like to configure?
→ [Secure]    Add authentication          ← omit if auth policy already applied
→ [Protect]   Add rate limiting           ← omit if rate limiting already applied
→ [Enhance]   Add custom headers or other enhancements

references/api-yaml-examples.md

set-headers

v1

https://raw.githubusercontent.com/wso2/gateway-controllers/main/docs/README.md

…/wso2/gateway-controllers/main/docs/<policy>/<version>/docs/<filename>.md

docs/

1. Fetch the catalog above. Find the row for what the user wants.
2. Follow the link in that row to the policy's markdown. Use its YAML and

   params

   to write the policy block in the RestApi spec.

build.yaml

• Policy customization model:

  https://raw.githubusercontent.com/wso2/api-platform/ap-docs-0.8.x/docs/cli/customizing-gateway-policies.md

• Runtime support:

  https://raw.githubusercontent.com/wso2/api-platform/gw-docs-1.1.x/docs/gateway/policy-languages-and-runtimes.md

• Local gateway: agent runs

  scripts/init-local-cli-config.js

  , which writes

  ~/.wso2ap/config.yaml

  with the gateway's documented defaults (

  admin

  /

  admin

  , sourced from

  configs/config.toml

  in the gateway release). These are public fixture values, not user secrets.
• Existing/remote gateway: user runs

  ap gateway add --auth basic

  (or

  --auth bearer

  ) themselves in their own terminal; the

  ap

  CLI prompts interactively for username/password (or token) and writes them to its stored config.