> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Default URL
praisonai endpoints health

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

### List Provider Types

List all supported provider types.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Human-readable output
praisonai endpoints types

# JSON output
praisonai endpoints types --format json
```

<Note>
  `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.
</Note>

### Discovery Document

Get the unified discovery document from the server.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai serve recipe
```

### Authentication Error

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

**Solution**: Provide API key:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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`.