Endpoints CLI

The praisonai endpoints CLI provides a unified interface for interacting with all PraisonAI server types.

Overview

The Endpoints CLI is a universal client tool that allows you to:

List available endpoints from any server type
Describe endpoint details and schemas
Invoke endpoints with input data
Check server health
Discover server capabilities
Filter by provider type

Supported Provider Types

Type	Description
`recipe`	Recipe runner endpoints
`agents-api`	Single/multi-agent HTTP API
`mcp`	MCP server (stdio, http, sse)
`tools-mcp`	Tools exposed as MCP server
`a2a`	Agent-to-agent protocol
`a2u`	Agent-to-user event stream
`openai-compat`	OpenAI-compatible HTTP API (`/v1/chat/completions`, `/v1/completions`, `/v1/models`, `/v1/tools/invoke`)

Commands

List Endpoints

List all available endpoints from the server.

# Basic list
praisonai endpoints list

# JSON output
praisonai endpoints list --format json

# Filter by provider type
praisonai endpoints list --type agents-api

# Filter by tags
praisonai endpoints list --tags audio,video

# Custom server URL
praisonai endpoints list --url http://localhost:8000

Describe Endpoint

Get detailed information about a specific endpoint.

# Basic describe
praisonai endpoints describe my-recipe

# Show schema only
praisonai endpoints describe my-recipe --schema

# Custom server URL
praisonai endpoints describe my-recipe --url http://localhost:8000

Invoke Endpoint

Call an endpoint with input data.

# With file input
praisonai endpoints invoke my-recipe --input ./data.json

# With JSON input
praisonai endpoints invoke my-recipe --input-json '{"text": "hello"}'

# With config overrides
praisonai endpoints invoke my-recipe --input ./data.json --config model=gpt-4

# JSON output
praisonai endpoints invoke my-recipe --input ./data.json --json

# Streaming output
praisonai endpoints invoke my-recipe --input ./data.json --stream

# Dry run (validate without executing)
praisonai endpoints invoke my-recipe --input ./data.json --dry-run

# With API key authentication
praisonai endpoints invoke my-recipe --input ./data.json --api-key your-key

Health Check

Check if the endpoint server is healthy.

# Default URL
praisonai endpoints health

# Custom URL
praisonai endpoints health --url http://localhost:8000

List Provider Types

List all supported provider types.

# Human-readable output
praisonai endpoints types

# JSON output
praisonai endpoints types --format json

praisonai endpoints types now includes plugin-contributed types alongside built-ins. Each plugin type is shown with the description Plugin provider and capability invoke, so types and invoke --type agree.

Discovery Document

Get the unified discovery document from the server.

# Get discovery document
praisonai endpoints discovery

# JSON output
praisonai endpoints discovery --format json

# Custom URL
praisonai endpoints discovery --url http://localhost:8000

Options Reference

Global Options

Option	Description	Default
`--url`	Server URL	`http://localhost:8765`

List Options

Option	Description
`--format json`	Output as JSON
`--type <type>`	Filter by provider type
`--tags <a,b>`	Filter by tags (comma-separated)

Describe Options

Option	Description
`--schema`	Show input/output schema only

Invoke Options

Option	Description
`--type <type>`	Provider type to invoke with. Defaults to `recipe` when omitted. An unregistered value is a validation error (exit 2).
`--input <path>`	Input file path
`--input-json <json>`	Input as JSON string
`--config k=v`	Config override (repeatable)
`--json`	Output as JSON
`--stream`	Stream output events (SSE)
`--dry-run`	Validate without executing
`--api-key <key>`	API key for authentication

Environment Variables

Variable	Description
`PRAISONAI_ENDPOINTS_URL`	Default server URL
`PRAISONAI_ENDPOINTS_API_KEY`	API key for authentication

Exit Codes

Code	Meaning
0	Success
1	General error
2	Validation error
3	Runtime error
4	Authentication error
7	Not found
8	Connection error

Examples

Basic Workflow

# Start the server (in another terminal)
praisonai serve recipe --port 8765

# Check health
praisonai endpoints health

# List available endpoints
praisonai endpoints list

# Get endpoint details
praisonai endpoints describe my-recipe

# Invoke endpoint
praisonai endpoints invoke my-recipe --input-json '{"query": "Hello"}'

With Authentication

# Start server with auth
praisonai serve recipe --auth api-key --api-key my-secret-key

# Invoke with API key
praisonai endpoints invoke my-recipe \
  --input-json '{"query": "Hello"}' \
  --api-key my-secret-key

# Or use environment variable
export PRAISONAI_ENDPOINTS_API_KEY=my-secret-key
praisonai endpoints invoke my-recipe --input-json '{"query": "Hello"}'

Streaming Output

# Stream events as they occur
praisonai endpoints invoke my-recipe \
  --input-json '{"query": "Generate a story"}' \
  --stream

# Output:
#   Started: run-abc123
#   [loading] Loading recipe...
#   [executing] Running workflow...
#   ✓ Completed: success

JSON Output for Scripting

# Get JSON output for parsing
result=$(praisonai endpoints invoke my-recipe \
  --input-json '{"query": "Hello"}' \
  --json)

# Parse with jq
echo $result | jq '.output'

Troubleshooting

Connection Refused

Error: Connection error: [Errno 61] Connection refused

Solution: Ensure the recipe server is running:

praisonai serve recipe

Authentication Error

Error: Authentication required. Use --api-key or set PRAISONAI_ENDPOINTS_API_KEY

Solution: Provide API key:

praisonai endpoints invoke my-recipe --api-key your-key
# Or
export PRAISONAI_ENDPOINTS_API_KEY=your-key

Endpoint Not Found

Error: Endpoint not found: my-recipe

Solution: Check available endpoints:

praisonai endpoints list

Unknown Provider Type

Error: Unknown provider type: my-plugin. Registered types: a2a, a2u, agents-api, mcp, openai-compat, recipe, tools-mcp

An unregistered --type is a validation error (exit code 2) — it no longer silently falls back to recipe. Omitting --type still defaults to recipe. Solution: The type isn’t registered. Check what is:

praisonai endpoints types

If it’s your own plugin, confirm your pyproject.toml publishes it under praisonai.endpoint_providers and that the package is installed in the same environment as praisonai.

​Endpoints CLI

​Overview

​Supported Provider Types

​Commands

​List Endpoints

​Describe Endpoint

​Invoke Endpoint

​Health Check

​List Provider Types

​Discovery Document

​Options Reference

​Global Options

​List Options

​Describe Options

​Invoke Options

​Environment Variables

​Exit Codes

​Examples

​Basic Workflow

​With Authentication

​Streaming Output

​JSON Output for Scripting

​Troubleshooting

​Connection Refused

​Authentication Error

​Endpoint Not Found

​Unknown Provider Type

Endpoints CLI

Overview

Supported Provider Types

Commands

List Endpoints

Describe Endpoint

Invoke Endpoint

Health Check

List Provider Types

Discovery Document

Options Reference

Global Options

List Options

Describe Options

Invoke Options

Environment Variables

Exit Codes

Examples

Basic Workflow

With Authentication

Streaming Output

JSON Output for Scripting

Troubleshooting

Connection Refused

Authentication Error

Endpoint Not Found

Unknown Provider Type