Skip to content

README.md

Latest commit

 

History

History
667 lines (451 loc) · 19.8 KB

README.md

File metadata and controls

667 lines (451 loc) · 19.8 KB
Raw

DevPortal CLI Reference

This guide covers the DevPortal-related commands currently implemented under cli/src/cmd/devportal.

Available command groups:

  • ap devportal
  • ap devportal rest-api
  • ap devportal org
  • ap devportal api-key
  • ap devportal application
  • ap devportal subscription
  • ap devportal sub-plan

Prerequisites

  • Add at least one DevPortal configuration before using commands that contact a DevPortal server.
  • DevPortal configurations are stored in the CLI config file managed by ap devportal add.
  • Commands that use an active DevPortal resolve the platform first, then the active DevPortal under that platform.

Authentication

Supported DevPortal auth types:

  • basic
  • oauth
  • api-key

Environment variables override credentials stored in the CLI config.

Auth type Environment variables
basic WSO2AP_DEVPORTAL_USERNAME, WSO2AP_DEVPORTAL_PASSWORD
oauth WSO2AP_DEVPORTAL_TOKEN
api-key WSO2AP_DEVPORTAL_API_KEY

Connection Notes

  • Commands that call the DevPortal API support --insecure when certificate verification must be skipped for local or self-signed HTTPS endpoints.
  • When a command accepts --display-name and --platform, it resolves the DevPortal explicitly.
  • When --display-name is provided without --platform, the command looks in the default platform.
  • When --display-name is not provided, the command uses the active DevPortal in the resolved platform.

Commands

ap devportal add

Adds a DevPortal configuration to the CLI config file.

ap devportal add --display-name <name> --server <server-url> --auth <basic|oauth|api-key> [--platform <platform>] [--no-interactive]

Examples:

ap devportal add
ap devportal add --display-name my-portal --server https://devportal.example.com --auth basic
ap devportal add --display-name my-portal --server https://devportal.example.com --auth oauth
ap devportal add --display-name my-portal --server https://devportal.example.com --auth api-key
ap devportal add --display-name my-portal --platform eu --server https://devportal.example.com --auth api-key --no-interactive

Notes:

  • Interactive mode prompts for missing values.
  • Supplying credentials as flags is supported, but interactive mode or environment variables are preferred.
  • If credentials are omitted, runtime commands expect the corresponding environment variables.

ap devportal list

Lists DevPortal configurations for a platform.

ap devportal list [--platform <platform>]

Example:

ap devportal list
ap devportal list --platform eu

Notes:

  • If --platform is omitted, the current platform is used.
  • The active DevPortal is marked in the output table.

ap devportal remove

Removes a DevPortal configuration from a platform.

ap devportal remove --display-name <name> [--platform <platform>]

Example:

ap devportal remove --display-name my-portal

ap devportal use

Sets the active DevPortal for a platform.

ap devportal use --display-name <name> [--platform <platform>]

Example:

ap devportal use --display-name my-portal
ap devportal use --display-name my-portal --platform eu

Notes:

  • If --platform is omitted, the current platform is used.
  • The command reports whether credentials will come from environment variables or the stored config.

ap devportal current

Shows the active DevPortal for a platform.

ap devportal current [--platform <platform>]

Example:

ap devportal current

ap devportal health

Calls the DevPortal health endpoint using the active DevPortal for the resolved platform.

ap devportal health [--platform <platform>]

Example:

ap devportal health
ap devportal health --platform eu

ap devportal build

Builds DevPortal deployment artifacts from an API project.

ap devportal build [-f <api-project-directory>]

Examples:

ap devportal build
ap devportal build -f /path/to/project

Behavior:

  • If -f is omitted, the current directory is treated as the API project root.
  • The command expects an API project with a .api-platform/config.yaml.
  • If devportals configuration is missing in the API project config, a default devportal/ structure is created and added to the config.
  • The build/ directory is cleaned before new artifacts are written.
  • One zip is generated per configured DevPortal entry.

Generated artifact names:

  • default DevPortal config: build/devportal.zip
  • named DevPortal config: build/devportal_<name>.zip

Apply Command

ap devportal apply

Creates or updates a DevPortal resource from a single file, aligning with ap gateway apply and ap ai-workspace apply. Because a project can contain multiple DevPortal resources, you point -f at the exact file — a YAML CR or a built REST API artifact zip — not at the project directory.

ap devportal apply -f <file> [--display-name <devportal-name>] [--platform <platform>] [--insecure]

The target endpoint is selected from the resource kind. For a YAML CR the top-level kind is read directly; for a .zip the kind is read from the artifact's devportal.yaml. The target organization is resolved server-side from the DevPortal credentials, so there is no --org flag.

For kinds that are addressable by their handle (metadata.name) and expose a PUT — Organization and RestApi — apply first checks whether the resource exists (GET {resource}/{handle}, like ap gateway apply) and then updates it (PUT, reported as updated) or creates it (POST, reported as applied). Subscription plans have no per-plan PUT — their publish endpoint upserts, and SubscriptionPolicyList is a bulk upload — so they are always POSTed.

Kind (source) Input Create / update
Organization (YAML CR) .yaml GET /api/v0.9/organizations/{name} → PUT /api/v0.9/organizations/{name} or POST /api/v0.9/organizations
SubscriptionPolicy / SubscriptionPolicyList (YAML CR) .yaml POST /api/v0.9/subscription-plans (server upsert)
RestApi (artifact devportal.yaml) .zip GET /api/v0.9/apis/{name} → PUT /api/v0.9/apis/{name} or POST /api/v0.9/apis

Examples:

# Subscription plan(s) — single (kind: SubscriptionPolicy) or bulk (kind: SubscriptionPolicyList)
ap devportal apply -f sub_plan.yaml

# REST API from a built artifact zip (kind: RestApi read from devportal.yaml)
ap devportal apply -f build/devportal.zip

Notes:

  • --file is required and must be an exact file (a .yaml/.yml CR or a .zip artifact), not a directory.
  • A RestApi must be supplied as a built .zip (from ap devportal build); a CR must be supplied as YAML.
  • On success it prints a Status/Message/ID summary — the message reports applied (created) or updated — followed by the server response body.
  • This replaces the former ap devportal org add, ap devportal sub-plan publish, and ap devportal rest-api publish commands (which were create/publish-only).

Application Commands

These commands manage DevPortal applications using the /api/v0.9/applications endpoints. The organization is resolved from the DevPortal credentials.

ap devportal application create

Creates an application. Only --name and --type are required; --description is optional.

ap devportal application create --name <name> --type <type> [--description <description>] [--display-name <devportal-name>] [--platform <platform>] [--insecure]

Examples:

ap devportal application create --name "Weather App" --type WEB
ap devportal application create --name "Weather App" --type WEB --description "Calls the Weather APIs"
ap devportal application create --name "Weather App" --type WEB --display-name my-portal --platform eu

Expected payload shape (description is omitted when --description is not provided):

{
  "name": "Weather App",
  "type": "WEB",
  "description": "Calls the Weather APIs"
}

ap devportal application get

Lists applications in an organization, or retrieves a single application when --app-id is provided.

ap devportal application get [--app-id <app-id>] [--display-name <devportal-name>] [--platform <platform>] [--insecure]

Examples:

ap devportal application get
ap devportal application get --app-id app_1
ap devportal application get --app-id app_1 --display-name my-portal --platform eu

ap devportal application update

Updates an existing application. --name and --type are required in the body; --description is optional. (edit is accepted as an alias.)

ap devportal application update --app-id <app-id> --name <name> --type <type> [--description <description>] [--display-name <devportal-name>] [--platform <platform>] [--insecure]

Examples:

ap devportal application update --app-id app_1 --name "Weather App" --type WEB
ap devportal application update --app-id app_1 --name "Weather App" --type WEB --description "Calls the Weather APIs"

ap devportal application delete

Deletes an application by its application ID.

ap devportal application delete --app-id <app-id> [--display-name <devportal-name>] [--platform <platform>] [--insecure]

Examples:

ap devportal application delete --app-id app_1
ap devportal application delete --app-id app_1 --display-name my-portal --platform eu

Subscription Commands

These commands manage DevPortal platform subscriptions using the /api/v0.9/subscriptions endpoints. The organization is resolved from the DevPortal credentials.

ap devportal subscription create

Creates a platform subscription. Only the API ID is required; the subscription plan is optional.

ap devportal subscription create --api-id <api-id> [--subscription-plan <plan-name>] [--display-name <devportal-name>] [--platform <platform>] [--insecure]

Examples:

ap devportal subscription create --api-id api_1
ap devportal subscription create --api-id api_1 --subscription-plan gold
ap devportal subscription create --api-id api_1 --subscription-plan gold --display-name my-portal --platform eu

Expected payload shape (subscriptionPlanName is omitted when --subscription-plan is not provided):

{
  "apiId": "api_1",
  "subscriptionPlanName": "gold"
}

ap devportal subscription edit

Updates a platform subscription status with flags.

ap devportal subscription edit --sub-id <subscription-id> --status <status> [--display-name <devportal-name>] [--platform <platform>] [--insecure]

Examples:

ap devportal subscription edit --sub-id sub_1 --status ACTIVE
ap devportal subscription edit --sub-id sub_1 --status ACTIVE --display-name my-portal --platform eu

Expected payload shape:

{
  "status": "ACTIVE"
}

ap devportal subscription get

Gets all platform subscriptions in an organization, or a single subscription when --sub-id is provided.

ap devportal subscription get [--sub-id <subscription-id>] [--display-name <devportal-name>] [--platform <platform>] [--insecure]

Examples:

ap devportal subscription get
ap devportal subscription get --sub-id sub_1
ap devportal subscription get --sub-id sub_1 --display-name my-portal --platform eu

ap devportal subscription delete

Deletes a platform subscription by ID.

ap devportal subscription delete --sub-id <subscription-id> [--display-name <devportal-name>] [--platform <platform>] [--insecure]

Examples:

ap devportal subscription delete --sub-id sub_1
ap devportal subscription delete --sub-id sub_1 --display-name my-portal --platform eu

REST API Commands

These commands manage API artifacts in a DevPortal organization.

ap devportal rest-api list

Lists APIs in a DevPortal organization.

ap devportal rest-api list [--display-name <devportal-name>] [--platform <platform>] [--insecure]

Examples:

ap devportal rest-api list
ap devportal rest-api list --display-name my-portal --platform eu

Behavior:

  • Prints a table with API_ID, API_HANDLE, API_NAME, and API_VERSION.
  • Use the API_ID value from the table with ap devportal rest-api get.

ap devportal rest-api get

Gets a single API artifact from a DevPortal organization.

ap devportal rest-api get --id <api-id> [--display-name <devportal-name>] [--platform <platform>] [--insecure]

Examples:

ap devportal rest-api get --id api_1
ap devportal rest-api get --id api_1 --display-name my-portal --platform eu

Publishing a REST API

A built REST API artifact zip is published with the unified ap devportal apply command — apply reads kind: RestApi from the zip's devportal.yaml and routes it to the organization's apis endpoint:

ap devportal apply -f build/devportal.zip

Build the zip first with ap devportal build. Use ap devportal rest-api get/list/edit/delete (below) to manage an already-published API.

ap devportal rest-api edit

Updates an existing API artifact in a DevPortal organization.

ap devportal rest-api edit [--file <zip-path>] --id <api-id> [--display-name <devportal-name>] [--platform <platform>] [--insecure]

Examples:

ap devportal rest-api edit --id api_1
ap devportal rest-api edit -f fooapi/build/devportal.zip --id api_1
ap devportal rest-api edit -f fooapi/build/devportal.zip --id api_1 --display-name my-portal --platform eu

Behavior:

  • If --file is omitted, the command looks for ./devportal.zip in the current directory.
  • If neither --file nor ./devportal.zip is available, the command returns an error.

ap devportal rest-api delete

Deletes an API artifact from a DevPortal organization.

ap devportal rest-api delete --id <api-id> [--display-name <devportal-name>] [--platform <platform>] [--insecure]

Examples:

ap devportal rest-api delete --id api_1
ap devportal rest-api delete --id api_1 --display-name my-portal --platform eu

Current status:

  • The command exists in the CLI surface, but the apply flow is not implemented yet.

API Key Commands

These commands manage API keys using the /api/v0.9/api-keys endpoints. The organization is resolved from the DevPortal credentials.

ap devportal api-key generate

Generates an API key for an API. The plaintext secret is returned once in the response and is never persisted. Run without the required flags to be prompted interactively.

ap devportal api-key generate --api-id <api-id> --name <key-name> [--expires-at <expiry>] [--display-name <devportal-name>] [--platform <platform>] [--insecure]

Examples:

# Provide everything via flags
ap devportal api-key generate --api-id api_1 --name weather_prod_key

# Add an expiry (ISO-8601 with timezone, epoch seconds, or epoch milliseconds)
ap devportal api-key generate --api-id api_1 --name weather_prod_key --expires-at 2026-12-31T23:59:59Z

# Interactive mode (prompts for any missing org/api-id/name/expiry)
ap devportal api-key generate

# Skip prompts and fail if a required flag is missing
ap devportal api-key generate --api-id api_1 --name weather_prod_key --no-interactive

Notes:

  • --name is the API key name and must match ^[a-z0-9][a-z0-9_-]{0,127}$ (lowercase letters, numbers, _, and -). The CLI validates this before sending the request.
  • --expires-at is optional.
  • generate is the only API key command with interactive mode.

ap devportal api-key get

Lists API keys for an API.

ap devportal api-key get --api-id <api-id> [--display-name <devportal-name>] [--platform <platform>] [--insecure]

Examples:

ap devportal api-key get --api-id api_1
ap devportal api-key get --api-id api_1 --display-name my-portal --platform eu

ap devportal api-key regenerate

Regenerates the secret for an existing API key. The old secret is invalidated at connected gateways and the new plaintext secret is returned once.

ap devportal api-key regenerate --api-key-id <api-key-id> [--display-name <devportal-name>] [--platform <platform>] [--insecure]

Examples:

ap devportal api-key regenerate --api-key-id key_1
ap devportal api-key regenerate --api-key-id key_1 --display-name my-portal --platform eu

ap devportal api-key revoke

Revokes an existing API key. Connected gateways immediately reject requests carrying the revoked key.

ap devportal api-key revoke --api-key-id <api-key-id> [--display-name <devportal-name>] [--platform <platform>] [--insecure]

Examples:

ap devportal api-key revoke --api-key-id key_1
ap devportal api-key revoke --api-key-id key_1 --display-name my-portal --platform eu

Subscription Plan Commands

These commands manage subscription plans using the /api/v0.9/subscription-plans endpoint. The organization is resolved from the DevPortal credentials.

Publishing subscription plans

Subscription plans are published with the unified ap devportal apply command from a YAML CR — either a single plan (kind: SubscriptionPolicy) or a bulk list (kind: SubscriptionPolicyList with an items array).

ap devportal apply -f sub_plan_gold.yaml     # single plan
ap devportal apply -f sub_plans.yaml         # bulk list

The CLI validates the CR locally before upload: kind must be SubscriptionPolicy or SubscriptionPolicyList, and each plan must have metadata.name.

Single plan CR shape (sub_plan_gold.yaml):

apiVersion: devportal.api-platform.wso2.com/v1
kind: SubscriptionPolicy
metadata:
  name: Gold
spec:
  displayName: Gold Plan
  billingPlan: FREE
  type: requestcount
  requestCount: 5000
  description: Allows 5000 requests per minute
  refId: cp-plan-gold           # optional external reference

Multiple plans in one file (sub_plans.yaml):

apiVersion: devportal.api-platform.wso2.com/v1
kind: SubscriptionPolicyList
items:
  - metadata:
      name: Gold
    spec:
      displayName: Gold Plan
      billingPlan: FREE
      type: requestcount
      requestCount: 5000
  - metadata:
      name: Unlimited
    spec:
      displayName: Unlimited
      billingPlan: FREE
      type: requestcount
      requestCount: -1

Notes:

  • type accepts requestcount or eventcount. Use -1 for an unlimited request/event count.

ap devportal sub-plan list

Lists all subscription plans in an organization.

ap devportal sub-plan list [--display-name <devportal-name>] [--platform <platform>] [--insecure]

Examples:

ap devportal sub-plan list
ap devportal sub-plan list --display-name my-portal --platform eu

Notes:

  • Calls GET /api/v0.9/subscription-plans (operationId listSubscriptionPlans).

ap devportal sub-plan get

Gets a single subscription plan by its policy ID.

ap devportal sub-plan get --policy-id <policy-id> [--display-name <devportal-name>] [--platform <platform>] [--insecure]

Examples:

ap devportal sub-plan get --policy-id plan_1
ap devportal sub-plan get --policy-id plan_1 --display-name my-portal --platform eu

Notes:

  • The spec path parameter is policyIdOrName; this command always treats the supplied value as the policy ID.

ap devportal sub-plan delete

Deletes a subscription plan by its policy ID.

ap devportal sub-plan delete --policy-id <policy-id> [--display-name <devportal-name>] [--platform <platform>] [--insecure]

Examples:

ap devportal sub-plan delete --policy-id plan_1
ap devportal sub-plan delete --policy-id plan_1 --display-name my-portal --platform eu

Notes:

  • The spec path parameter is policyIdOrName; this command always treats the supplied value as the policy ID.
  • A successful delete returns 204 No Content.

Related Commands

  • ap platform add
  • ap platform use
  • ap devportal use
  • ap apiproject init