Skip to main content

​
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

TypeDescription
recipeRecipe runner endpoints
agents-apiSingle/multi-agent HTTP API
mcpMCP server (stdio, http, sse)
tools-mcpTools exposed as MCP server
a2aAgent-to-agent protocol
a2uAgent-to-user event stream

​
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

​
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

OptionDescriptionDefault
--urlServer URLhttp://localhost:8765

​
List Options

OptionDescription
--format jsonOutput as JSON
--type <type>Filter by provider type
--tags <a,b>Filter by tags (comma-separated)

​
Describe Options

OptionDescription
--schemaShow input/output schema only

​
Invoke Options

OptionDescription
--input <path>Input file path
--input-json <json>Input as JSON string
--config k=vConfig override (repeatable)
--jsonOutput as JSON
--streamStream output events (SSE)
--dry-runValidate without executing
--api-key <key>API key for authentication

​
Environment Variables

VariableDescription
PRAISONAI_ENDPOINTS_URLDefault server URL
PRAISONAI_ENDPOINTS_API_KEYAPI key for authentication

​
Exit Codes

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

​
Examples

​
Basic Workflow

# Start the server (in another terminal)
praisonai recipe serve --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 recipe serve --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 recipe serve

​
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