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

# Agent CLI

> Command-line interface for single Agent chat and run operations

# Agent CLI

The PraisonAI TypeScript CLI provides commands for chatting with and running agents directly from the command line.

## Commands Overview

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Chat with an agent
praisonai-ts chat "Your message here"

# Run an agent with a task
praisonai-ts run "Your task" --agent my-agent.yaml
```

## chat

Interactive chat with an agent.

### Basic Usage

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai-ts chat "Hello, how are you?"
```

### With Model Selection

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai-ts chat "Hello" --model gpt-4o-mini
```

### With Streaming

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai-ts chat "Write a poem" --stream
```

### Options

| Option            | Description                            | Default        |
| ----------------- | -------------------------------------- | -------------- |
| `--model`, `-m`   | LLM model to use                       | `gpt-4o-mini`  |
| `--stream`, `-s`  | Enable streaming output                | `false`        |
| `--session`       | Session ID for conversation continuity | Auto-generated |
| `--verbose`, `-v` | Enable verbose output                  | `false`        |
| `--json`          | Output as JSON                         | `false`        |

### Examples

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Simple chat
praisonai-ts chat "What is the capital of France?"

# With custom model
praisonai-ts chat "Explain quantum computing" --model gpt-4o

# With session persistence
praisonai-ts chat "My name is Alice" --session user-123
praisonai-ts chat "What's my name?" --session user-123

# JSON output
praisonai-ts chat "Hello" --json

# Streaming output
praisonai-ts chat "Write a story about a robot" --stream
```

### JSON Output Format

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "success": true,
  "data": {
    "response": "Hello! How can I help you today?",
    "sessionId": "550e8400-e29b-41d4-a716-446655440000"
  },
  "meta": {
    "duration_ms": 1234,
    "model": "gpt-4o-mini"
  }
}
```

## run

Run an agent with a specific task.

### Basic Usage

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai-ts run "Analyze this data" --agent my-agent.yaml
```

### Options

| Option            | Description                      | Default |
| ----------------- | -------------------------------- | ------- |
| `--agent`, `-a`   | Agent configuration file or name | -       |
| `--tools`, `-t`   | Comma-separated list of tools    | -       |
| `--verbose`, `-v` | Enable verbose output            | `false` |
| `--json`          | Output as JSON                   | `false` |

### Examples

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Run a task with tools
praisonai-ts run "Search the web for AI news" --tools tavily

# Run with agent config
praisonai-ts run "Summarize the document" --agent researcher.yaml

# JSON output for scripting
praisonai-ts run "Generate 5 random names" --json
```

## Environment Variables

Set these environment variables for API access:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Required - at least one provider key
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export GOOGLE_API_KEY=...

# Optional - default model
export PRAISONAI_MODEL=gpt-4o-mini

# Optional - default database for persistence
export PRAISONAI_DB=sqlite:./data.db
```

## Database Persistence

Use the `--db` flag to persist memory, sessions, and knowledge across CLI invocations.

### Supported Databases

| Database   | URL Format                          |
| ---------- | ----------------------------------- |
| SQLite     | `sqlite:./data.db`                  |
| PostgreSQL | `postgres://user:pass@host:5432/db` |
| Redis      | `redis://localhost:6379`            |

### Memory Persistence

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Add memory that persists
praisonai-ts memory add "User prefers dark mode" --db sqlite:./data.db

# List persisted memories
praisonai-ts memory list --db sqlite:./data.db

# Search memories
praisonai-ts memory search "dark" --db sqlite:./data.db
```

### Session Persistence

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Create a persistent session
praisonai-ts session create my-session --db sqlite:./data.db

# List all sessions
praisonai-ts session list --db sqlite:./data.db

# Get session details
praisonai-ts session get my-session --db sqlite:./data.db
```

### Knowledge Persistence

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Add knowledge from text
praisonai-ts knowledge add "PraisonAI is an AI agent framework" --db sqlite:./data.db

# Add knowledge from file
praisonai-ts knowledge add ./document.txt --db sqlite:./data.db

# Search knowledge base
praisonai-ts knowledge search "agent framework" --db sqlite:./data.db

# List all knowledge entries
praisonai-ts knowledge list --db sqlite:./data.db
```

### Environment Variable

Instead of passing `--db` on every command, set the environment variable:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
export PRAISONAI_DB=sqlite:./data.db

# Now all commands use persistent storage
praisonai-ts memory add "Hello world"
praisonai-ts memory list  # Shows persisted entry
```

## Scripting Examples

### Bash Script

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

# Run agent and capture output
RESULT=$(praisonai-ts chat "What is 2+2?" --json)
ANSWER=$(echo $RESULT | jq -r '.data.response')
echo "Answer: $ANSWER"
```

### Pipeline Usage

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Chain with other commands
praisonai-ts chat "Generate a topic" | \
  xargs -I {} praisonai-ts chat "Write about: {}"
```

## Error Handling

### Missing API Key

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
$ praisonai-ts chat "Hello"
Error: OPENAI_API_KEY environment variable is not set
```

### Invalid Model

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
$ praisonai-ts chat "Hello" --model invalid-model
Error: Model 'invalid-model' is not available
```

## See Also

* [Agent](/docs/js/agent) - Agent class documentation
* [Agents CLI](/docs/js/agents-cli) - Multi-agent CLI commands
* [Workflow CLI](/docs/js/workflows-cli) - Workflow CLI commands