Endpoints CLI

Unified client CLI for interacting with all PraisonAI server types

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.