API Platform CTL Design

[piyumaldk]

Find Below Proposed CLI Commands

---

1. Add a Gateway

CLI Command

ap gateway add --display-name <name> --server <server>

Sample Command

ap gateway add --display-name dev --server http://localhost:9090

Sample Response

Gateway in <url> added as <name>
Configuration saved to: ~/.apipctl/config.yaml

---

2. List Gateways

CLI Command

ap gateway list

Sample Command

ap gateway list

Sample Response

dev: http://localhost:9090 (insecure)
prod: https://api.example.com (secure)

---

3. Remove a Gateway

CLI Command

ap gateway remove --display-name <name>

Sample Command

ap gateway remove --display-name dev

Sample Response

Gateway removed successfully.

---

4. Change the Gateway

CLI Command

ap gateway use --display-name <name>

Sample Command

ap gateway use --display-name <name>

Sample Response

Gateway set to <name>.

---

5. Check the current Gateway

CLI Command

ap gateway current

Sample Command

ap gateway current

Sample Response

Current gateway: prod - https://api.example.com (secure)

---

6. Returns the health status of the Gateway

CLI Command

ap gateway health

Sample Command

ap gateway health

Sample Response

Gateway Status: healthy
Timestamp: 2025-12-08T09:25:17Z
Gateway is healthy.

---

7. Apply a Resource

CLI Command

ap gateway apply --file <path>

Sample Command

ap gateway apply--file petstore-api.yaml

Sample Response

Status: success
Message: API applied successfully
ID: petstore-v1
Created At: 2025-12-08T09:30:00Z

---

8. List all APIs

CLI Command

ap gateway api list

Sample Command

ap gateway api list

Sample Response

API 1:
  ID: sample-1
  Name: PetStore API
  Version: v1.0
  Context: /petstore
  Status: deployed
  Created At: 2025-12-08T09:30:00Z

API 2:
  ID:sample-2
  Name: Weather API
  Version: v1.0
  Context: /weather
  Status: deployed
  Created At: 2025-12-08T09:35:00Z

---

9. Get a specific API by name and version or id

CLI Command

ap gateway api get --display-name <name> --version <version> --format <json|yaml>
ap gateway api get --id <id> --format <json|yaml>

Sample Command

ap gateway api get --display-name "PetStore API" --version v1.0 --format yaml
ap gateway api get --id sample-1 --format yaml

Sample Response

<file>

---

10. Delete an API

CLI Command

ap gateway api delete --id <id> 

Sample Command

ap gateway api delete --id <id>

Sample Response

API deleted successfully.

---

11. Build a gateway

CLI Command

ap gateway image build \
  [--name <gateway-name>] \
  [--path <gateway-project-dir>]
  [--repository <image-repository>] \
  [--version <gateway-version>] \
  [--gateway-builder <gateway-builder-image>] \
  [--gateway-controller-base-image <gateway-controller-base-image>] \
  [--router-base-image <router-base-image>] \
  [--push] \
  [--no-cache] \
  [--platform <platform>] \
  [--offline] \
  [--output-dir <output_dir>]

Sample Command

ap gateway build

Sample Response

ghcr.io/wso2/api-platform/ai-gateway-gateway-controller:0.2.0
ghcr.io/wso2/api-platform/ai-gateway-router:0.2.0
ghcr.io/wso2/api-platform/ai-gateway-policy-engine:0.2.0

---

12. List all MCPs

CLI Command

ap gateway mcp list

Sample Command

ap gateway mcp list

Sample Response

MCP 1:
  ID: sample-1
  Name: MCP1
  Version: v1.0
  Context: /petstore
  Status: deployed
  Created At: 2025-12-08T09:30:00Z

MCP 2:
  ID:  sample-2
  Name: MCP2
  Version: v1.0
  Context: /weather
  Status: deployed
  Created At: 2025-12-08T09:35:00Z

---

13. Retrieves a specific MCP

CLI Command

ap gateway mcp get --display-name <name> --version <version> --format <json|yaml>
ap gateway mcp get --id <id> --format <json|yaml>

Sample Command

ap gateway mcp get --display-name my-mcp --version 1.0.0 --format json
ap gateway mcp get --id sample-id --format json

Sample Response

<file>

---

14. Permanently deletes a MCP

CLI Command

ap gateway mcp delete --id <id> 

Sample Command

ap gateway mcp delete --id sample-id

Sample Response

MCP deleted successfully.

---

15. Generate MCP

CLI Command

ap gateway mcp generate --server <server> --output <path>

Sample Command

ap gateway mcp generate --server http://localhost:3001/mcp --output target

Sample Response

MCP generated successfully.

[piyumaldk]

Please note that LLM related actions are not yet finalised. I will add them later.

[renuka-fernando]

Quote

1. Change the Gateway

CLI Command

apipctl gateway use <url>

Sample Command

apipctl gateway use http://localhost:9090

Sample Response

Gateway set to: http://localhost:9090
Configuration saved to: ~/.apipctl/config.yaml

Suggestion

What if we provide a name to the gateway?

apipctl gateway add <name> --url <url> [--token <token>] [--insecure]
apipctl gateway add dev --url http://localhost:9090 --token <TOKEN>
apipctl gateway use dev

List gateways

apipctl gateway list

NAME      URL                       ACTIVE
dev     http://localhost:9090     *
prod      https://api.example.com

Remove gateway

apipctl gateway remove dev.

These info will be persist in ~/.apipctl/config.yaml

This will be align with other commands.

kubectl config use-context
docker context use

[piyumaldk]

+1

[pubudu538]

Please validate these commands with regards to kubectl.

[piyumaldk]

Sure. Will do.

[piyumaldk]

New CLI commands addressing the requirement were introduced and updated in the discussion description.

[nuwand]

I see certain places where we have to give the name and version of the API. Shouldn't this be given as -n "API Name" -v "API Version" or something similar to that format?

[piyumaldk]

+1. It seems better to use flags for them as well. I will add the flags as –name (n) and –version (v).

[piyumaldk]

These has been updated in the discussion description

[RakhithaRR]

Whats the command hierarchy we are going to follow here?

1. Noun before the verb

ctl gateway apis list

This pattern is used by some CLIs like aws cli

aws s3 cp ...
aws eks update ...

2. Verb before the noun

ctl gateway list apis

This pattern is used by some CLIs like kubectl

kubectl get pods
kubectl edit deployment

Also, since we have two different areas we need to cover with this CLI (gateway and platform API) we could consider using contexts as well instead of defining as a subcommand. This is similar to how kubectl handles multiple connected clusters.

ctl set-context gateway
ctl apis list

[piyumaldk]

We need to choose one from these 2 options. What I this is explained in [1]

Let's discuss this and finalised today so we can start the implementation.

[1] #356 (reply in thread)

[malinthaprasan]

I am also +1 to use nouns before the verb. However, its better not to switch the entire CLI command list when we switch the context and that can cause confusions. Its better to use seperate contexts for main sub commands (apipctl gateway, apipctl cp or apipctl mgt)

[piyumaldk]

We will use gateway, cp, like sub commands for separate contexts

[malinthaprasan]

Command options from existing CLIs:

Option 1: Noun before verb + all parameters are flags

Azure CLI follows this method
eg: https://learn.microsoft.com/en-us/cli/azure/apim/api?view=azure-cli-latest#az-apim-api-show

az apim api create --service-name MyApim -g MyResourceGroup --api-id MyApi --path '/myapi' --display-name 'My API'

Option 2: Noun before verb + main/resource-identification/mandatory parameters are positional, others are flags (hybrid approach)

Google Cloud CLI follows this method
https://docs.cloud.google.com/sdk/gcloud/reference/apigee/apis/describe

To describe an API proxy called proxy-name given that its matching Cloud Platform project has been set in gcloud settings, run:

gcloud apigee apis describe proxy-name

To describe an API proxy called other-proxy-name in another project whose Apigee organization is named org-name, run:

gcloud apigee apis describe other-proxy-name --organization=org-name

Option 3: Verb before noun + main/resource-identification/mandatory parameters are positional, others are flags (hybrid approach)

This is similar to kubectl, git command references.

git push origin
git push origin -f

kubectl get pod mypod
kubectl get pod mypod -n apim

Option 4: Verb before noun + all parameters are flags

Seems to be rare. The closest example found was the windows powershell commands.
eg: https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.management/get-process?view=powershell-7.5

Get-Process -Name pwsh

(But in the above command -Name flag is also optional - means Get-Process pwsh also works.

[piyumaldk]

We may need to discuss this further and choose the best option for our use case.

In my opinion, options 1 and 3 are better because they will not confuse users.

Between those two, option 1 seems more suitable, as our CLI already uses subcommands that are nouns. Keeping all nouns at the beginning would provide a clearer and more consistent approach.

However, if we decide to follow the kubectl-style convention, then option 3 would be the appropriate choice. The downside is that it may introduce some confusion, as the command structure would look like this:

apipctl <sub-command-noun> <verb> <noun> --flags parameters

@pubudu538 @nuwand @malinthaprasan WDYT?

[piyumaldk]

Updated the discussion description with CLI commands for below LLM REST calls.

POST /llm-providers/templates
GET /llm-providers/templates
GET /llm-providers/templates/{name}
PUT /llm-providers/templates/{name}
DELETE /llm-providers/templates/{name}
POST /llm-providers
GET /llm-providers
GET /llm-providers/{name}/{version}
PUT /llm-providers/{name}/{version}
DELETE /llm-providers/{name}/{version}

[malinthaprasan]

Discussion notes:

• Attendees: Pubudu Gunatilaka, Thivindu Paranayapa, Nimsara Fernando, Nuwan Dias, Rakhitha Ranathunge, Piyumal Kularathna, Tharsanan Kurukulasingam, Thenujan Nagaratnam, Arshardh Ifthikar, Renuka Fernando, Osura Viduranga, Malintha Amarasinghe

• Notes:

  • Use the Azure CLI format (every parameter will be a flag). But we'll have shorten formats too ( eg: --name vs -n)
  • Every resource will have an identifier and CLI can fetch using that identifier:
    • eg: apipctl gateway api get --id "weather-v1"
  • Have name/version fetch too
    • eg: apipctl gateway api get --name "weather" --version "v1"
  • Have an apply -f “filename” method similar to kubenetes which handles add/update both
  • Make the identifier mandatory in the yaml file.
  • If the identifier is changed then it is no longer connected to the previous API, it will be a different API.

[piyumaldk]

For the 1st iteration, we will implement API, MCP, and LLM deployments support.

1. If we are going for more general (common for all deployments) command template, is it expected to retrieve LLM from it's unique name+version combination?
   cc: @nimsara66 @malinthaprasan

2. Do we need a command for listing or searching resources?
   Ex: List all mcp, api, or llm
   Ex: Search with mcp, api, or llm parameters
   cc: @malinthaprasan

[malinthaprasan]

1. You mean commands like this?

apipctl gateway api get --name <name> --version <version>
apipctl gateway mcp get --name <name> --version <version>
apipctl gateway llm-provider get --name <name>

apipctl gateway api get --id <identifier>
apipctl gateway mcp get --id <identifier>
apipctl gateway llm-provider get --id <identifier>

IMO we should support these consistently.

2. Yes, inidividually. We don't need a command to list all types at once.

apipctl gateway api list [--name <name>] [--version <version>]
apipctl gateway mcp list [--name <name>] [--version <version>]
apipctl gateway llm-provider list [--name <name>]

[piyumaldk]

Regarding 1,

1. So only apply should be common for all resources/deployments and GET should have subcommand api, mcp, or llm-provider to identify which resource/deployment to return?

2. llm-provider is unique by name, hence should be retrievable just by name?

3. For the initial CLI release, Is supporting basic gateway commands (add gateway, list gateways, etc) and MCP, API, and LLM Provider be enough?

Regarding 2,
Ack.

[piyumaldk]

These were sorted after discussed with @malinthaprasan. Update the discussion description with initial (Phase 1) CLI commands.

[piyumaldk]

1. Since we are planning to allow short flags as well, --url can be --u. Since some CLI tools use --u for username, would that be confusing for the user?

2. In Generate MCP YAML command, we can also give --file flag and ask the exact target file since we already have --file flag in othert commands. However other commands use --file as the source and in here this will be the output. Hence, for now, we introduced a new flag called --output. WDYT?

[piyumaldk]

Decided to go with --server and --output in today's syncup.

[piyumaldk]

Refer #516 discussion for gateway build command changes. I have updated the description of this discussion with latest finalised command for build a gateway.

Additionally, due to the architecture group discussion, we changed apipctl to ap`.