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

# Structured Output CLI

> Generate structured JSON output from the command line

Generate type-safe structured JSON output using the PraisonAI CLI.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    User([User]) --> CLI[CLI]
    CLI --> JSON([JSON])

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff

    class JSON agent
    class CLI,User tool
    classDef agent fill:#8B0000,color:#fff
    classDef tool fill:#189AB4,color:#fff
```

## Quick Start

<Steps>
  <Step title="Simple Usage">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai-ts llm json "Extract person info" --schema '{"type":"object"}'
    ```
  </Step>

  <Step title="With Configuration">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai-ts llm json "Analyze" --schema-file ./schema.json
    ```
  </Step>
</Steps>

***

## Commands

### Generate Structured Output

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Basic structured output with inline schema
praisonai-ts llm json "Extract person info from: John is 30 years old" \
  --schema '{"type":"object","properties":{"name":{"type":"string"},"age":{"type":"number"}}}'

# Using a schema file
praisonai-ts llm json "Analyze this text" --schema-file ./schemas/analysis.json

# With specific model
praisonai-ts llm json "Extract data" --model openai/gpt-4o -m ./schema.json
```

### Schema File Format

Create a JSON schema file:

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "type": "object",
  "properties": {
    "title": { "type": "string" },
    "summary": { "type": "string" },
    "tags": {
      "type": "array",
      "items": { "type": "string" }
    },
    "sentiment": {
      "type": "string",
      "enum": ["positive", "negative", "neutral"]
    }
  },
  "required": ["title", "summary"]
}
```

## Options

| Option          | Short | Description                             |
| --------------- | ----- | --------------------------------------- |
| `--model`       | `-m`  | Model to use (e.g., openai/gpt-4o-mini) |
| `--schema`      |       | Inline JSON schema                      |
| `--schema-file` | `-f`  | Path to JSON schema file                |
| `--temperature` | `-t`  | Temperature (0-1, default: 0.1)         |
| `--max-tokens`  |       | Maximum output tokens                   |
| `--timeout`     |       | Request timeout in ms                   |
| `--json`        |       | Output raw JSON                         |
| `--verbose`     | `-v`  | Verbose output                          |

## Examples

### Data Extraction

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
$ praisonai-ts llm json "Extract: Apple Inc CEO Tim Cook announced new products" \
  --schema '{"type":"object","properties":{"company":{"type":"string"},"person":{"type":"string"},"role":{"type":"string"},"action":{"type":"string"}}}'
```

Output:

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "company": "Apple Inc",
  "person": "Tim Cook",
  "role": "CEO",
  "action": "announced new products"
}
```

### Classification

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
$ praisonai-ts llm json "Classify: You won a million dollars! Click here!" \
  --schema '{"type":"object","properties":{"category":{"type":"string","enum":["spam","ham"]},"confidence":{"type":"number"},"reason":{"type":"string"}}}'
```

Output:

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "category": "spam",
  "confidence": 0.95,
  "reason": "Contains typical spam indicators: prize claim, urgency, call to action"
}
```

### Sentiment Analysis

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
$ praisonai-ts llm json "Analyze sentiment: I love this product! Best purchase ever." \
  --schema-file ./schemas/sentiment.json
```

Where `sentiment.json`:

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "type": "object",
  "properties": {
    "sentiment": { "type": "string", "enum": ["positive", "negative", "neutral"] },
    "score": { "type": "number", "minimum": -1, "maximum": 1 },
    "keywords": { "type": "array", "items": { "type": "string" } }
  }
}
```

### Complex Nested Output

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
$ praisonai-ts llm json "Parse this order: 2 pizzas ($15 each), 1 salad ($8), delivery to 123 Main St" \
  --schema-file ./schemas/order.json --json
```

Where `order.json`:

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "quantity": { "type": "number" },
          "price": { "type": "number" }
        }
      }
    },
    "total": { "type": "number" },
    "delivery": {
      "type": "object",
      "properties": {
        "address": { "type": "string" }
      }
    }
  }
}
```

Output:

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "items": [
    { "name": "pizza", "quantity": 2, "price": 15 },
    { "name": "salad", "quantity": 1, "price": 8 }
  ],
  "total": 38,
  "delivery": {
    "address": "123 Main St"
  }
}
```

### Using Different Providers

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# OpenAI
praisonai-ts llm json "Extract data" --model openai/gpt-4o --schema '...'

# Anthropic
praisonai-ts llm json "Extract data" --model anthropic/claude-3-sonnet --schema '...'

# Google
praisonai-ts llm json "Extract data" --model google/gemini-pro --schema '...'
```

## Piping and Scripting

### Pipe Input

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Pipe text content
cat document.txt | praisonai-ts llm json --schema-file ./schema.json

# Process multiple files
for f in *.txt; do
  praisonai-ts llm json "$(cat $f)" --schema-file ./schema.json --json >> results.jsonl
done
```

### Use in Scripts

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
#!/bin/bash
# extract-entities.sh

SCHEMA='{"type":"object","properties":{"entities":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"}}}}}}'

result=$(praisonai-ts llm json "$1" --schema "$SCHEMA" --json)
echo "$result" | jq '.entities'
```

### JSON Lines Output

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Process batch and output JSONL
while read -r line; do
  praisonai-ts llm json "$line" --schema-file ./schema.json --json
done < inputs.txt > outputs.jsonl
```

## Error Handling

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Check exit code
praisonai-ts llm json "Extract data" --schema '...'
if [ $? -ne 0 ]; then
  echo "Extraction failed"
fi

# Capture errors
result=$(praisonai-ts llm json "Extract data" --schema '...' --json 2>&1)
if echo "$result" | jq -e '.success == false' > /dev/null; then
  echo "Error: $(echo "$result" | jq -r '.error.message')"
fi
```

## Environment Variables

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Required: API key for provider
export OPENAI_API_KEY=sk-...

# Optional: Default model
export PRAISONAI_MODEL=openai/gpt-4o-mini

# Optional: Default temperature for structured output
export PRAISONAI_STRUCTURED_TEMP=0.1
```

## Exit Codes

| Code | Description             |
| ---- | ----------------------- |
| 0    | Success                 |
| 1    | General error           |
| 2    | Invalid arguments       |
| 3    | Schema validation error |
| 4    | API error               |

## Best Practices

<AccordionGroup>
  <Accordion title="Guidelines">
    1. **Use schema files** for complex schemas
    2. **Set low temperature** (0.1) for consistent output
    3. **Validate output** with `jq` or similar tools
    4. **Handle errors** in scripts
    5. **Use `--json`** flag for machine-readable output
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Structured Output" icon="brackets-curly" href="/docs/js/structured-output">Structured output SDK</Card>
  <Card title="Agent CLI" icon="terminal" href="/docs/js/agent-cli">Agent commands</Card>
</CardGroup>