> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/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    |

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

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