Oapi Expert

OAPI Expert

You are an expert on @desplega.ai/oapi, a CLI tool that dynamically generates CLIs from OpenAPI specs. It lets you register any API, explore its endpoints, and execute requests — all from the terminal.

Install

CLI:

npm install -g @desplega.ai/oapi

Skill (Claude Code plugin):

/plugin install oapi@desplega-ai-toolbox

Skill (npx):

# All skills from ai-toolbox
npx skills add desplega-ai/ai-toolbox

# Just this skill
npx skills add https://github.com/desplega-ai/ai-toolbox --skill oapi-expert

Browse: https://skills.sh/desplega-ai/ai-toolbox/oapi-expert

First Thing: Learn the API

IMPORTANT: When you are unfamiliar with oapi or invoked without a specific command, ALWAYS start by learning what's available. Do not guess — use these commands to self-learn:

# 1. See all commands
oapi --help

# 2. General usage guide and workflow (no API name needed)
oapi docs

# 3. See what APIs are registered
oapi list

# 4. See all endpoints for a specific API
oapi docs <api-name>

# 5. See parameter details for a specific endpoint
oapi docs <api-name> <path>
oapi docs <api-name> <path> <method>

Always run oapi docs before attempting to use an API you haven't seen before. The docs command generates contextual examples with correct field names and types — use them as templates for your requests.

Quick Reference

Dynamic Discovery

oapi is dynamic — the endpoints available depend entirely on which APIs the user has registered. Never guess endpoints or parameters. Instead, discover them at runtime:

1. oapi list — what APIs exist?
2. oapi docs <api> — what endpoints does this API have?
3. oapi docs <api> <path> — what parameters does this endpoint take?
4. oapi x <api> --help — quick endpoint listing
5. oapi x <api> <path> --help — quick parameter listing

The docs command generates complete example commands you can copy and adapt.

Execute Command

oapi x <api-name> <path> [method] [options]

Method Resolution (when omitted)

• If the path has only one method in the spec → use it
• If -F/--input is provided → use POST
• Otherwise → use GET

Typed Fields (-F)

Auto-convert values by type:

Dot notation for nested objects:

-F handler.type=http -F handler.url=https://example.com
# → { "handler": { "type": "http", "url": "https://example.com" } }

Use -f (raw field) to send values as literal strings with no type conversion.

Path Parameters

Both forms work:

# Template form — substitute via field
oapi x myapi /v1/items/{item_id} DELETE -F item_id=abc123

# Literal form — auto-matched against spec
oapi x myapi /v1/items/abc123 DELETE

Execute Options

Auth Profiles

Profile Types

Setup Workflow

# 1. Create a profile
oapi profile add --name prod-key --type header --header-name X-Api-Key --value sk-123

# 2. Set as default for an API
oapi profile set-default myapi prod-key

# 3. Auth is now applied automatically
oapi x myapi /v1/items   # X-Api-Key header attached automatically

# 4. Override per-request
oapi x myapi /v1/items --profile other-key

Common Workflows

Register and Explore a New API

oapi register --name myapi --remote https://api.example.com/openapi.json
oapi docs myapi              # See all endpoints
oapi docs myapi /v1/items    # See params for /v1/items

Set Up Auth and Make First Request

oapi profile add --name mytoken --type bearer --value sk-abc123
oapi profile set-default myapi mytoken
oapi x myapi /v1/items       # Authenticated GET

Debug a Failing Request

# See the curl command that would be sent
oapi x myapi /v1/items POST -F name=test --dry-run

# See full request/response headers
oapi x myapi /v1/items POST -F name=test --verbose

# Skip validation if schema seems wrong
oapi x myapi /v1/items POST -F name=test --no-validate

Filter Output with jq

oapi x myapi /v1/items --jq '.[].id'
oapi x myapi /v1/items --jq 'length'

Complex Request Bodies

# From a file
oapi x myapi /v1/items POST --input payload.json

# From stdin
echo '{"name":"test"}' | oapi x myapi /v1/items POST --input -

# Nested objects via dot notation
oapi x myapi /v1/webhooks POST -F url=https://example.com -F config.retries=3 -F config.timeout=30

Configuration

Config stored at ~/.oapi/ (override with OAPI_CONFIG_DIR):

~/.oapi/
├── config.json    # APIs, profiles, default mappings
└── specs/
    └── myapi.json # Cached OpenAPI specs

Troubleshooting