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

Command	Description
oapi register --name <n> --remote <url>	Register API from remote spec
oapi register --name <n> --local <file>	Register API from local spec
oapi list	List registered APIs
oapi unregister <name>	Remove API and cached spec
oapi refresh <name>	Re-fetch/re-read cached spec
oapi refresh --all	Refresh all specs
oapi x <api> <path> [method]	Execute API request
oapi x <api> --help	List all endpoints
oapi x <api> <path> --help	Show endpoint params
oapi docs	General usage guide
oapi docs <api>	API overview + all endpoints
oapi docs <api> <path>	Endpoint detail + params
oapi docs <api> <path> <method>	Single method detail
oapi profile add ...	Create auth profile
oapi profile list	List profiles
oapi profile rm <name>	Remove profile
oapi profile set-default <api> <profile>	Set default auth for API

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:

Input	Becomes
123	integer
3.14	float
true / false	boolean
null	null
'{"a":1}' or '[1,2]'	parsed JSON
@file.json	file contents (auto-parsed if JSON)

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

Flag	Description
-F key=value	Typed field (auto-parses numbers, booleans, JSON, @file)
-f key=value	Raw string field (no type conversion)
-H Key:Value	Custom header
--input <file>	Request body from file (- for stdin)
--raw	Compact JSON output (no pretty-printing)
--no-validate	Skip JSON Schema validation
--dry-run	Print equivalent curl command instead of executing
--verbose	Show request/response headers on stderr
--jq <expr>	Filter output with jq (requires system jq)
--profile <name>	Use a specific auth profile
--help	Contextual help (endpoint list or param details)

Auth Profiles

Profile Types

Type	Header Sent
header	Custom header (default: Authorization, customizable with --header-name)
bearer	Authorization: Bearer <value>
basic	Authorization: Basic <base64(value)>
query	Appends ?param=value to URL (requires --query-param)

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

Issue	Solution
API not found	Run oapi list to check registered APIs, or oapi register to add it
Spec outdated	Run oapi refresh <name> to re-fetch
Validation failed	Check field types with oapi docs <api> <path>, or use --no-validate
Method not available	Check oapi docs <api> <path> for available methods
Auth errors	Verify profile with oapi profile list, check set-default mapping
jq not working	Install jq: brew install jq
Wrong base URL	Re-register with --base-url override
Command not found	Install: npm install -g @desplega.ai/oapi