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.

bash

# 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.

bash

# 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.

bash

# 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.

bash

# Default URL
praisonai endpoints health

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

List Provider Types

List all supported provider types.

bash

# Human-readable output
praisonai endpoints types

# JSON output
praisonai endpoints types --format json

Discovery Document

Get the unified discovery document from the server.

bash

# 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

bash

# 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

bash

# 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

bash

# 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

bash

# 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:

bash

praisonai serve recipe

Authentication Error

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

Solution: Provide API key:

bash

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:

bash

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:

bash

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.