# Using the CLI

> Source: https://parallelworks.com/docs/ai/ai-chat/using-the-cli

# Using the CLI

You can interact with AI Chat directly from your terminal using the PW CLI. The CLI provides an interactive TUI chat session with markdown rendering and streaming responses, as well as commands for managing chats, providers, and models.

## Prerequisites

Before using AI Chat from the CLI, ensure:

- The **PW CLI** is installed and available on your system. See [CLI Installation](/docs/cli) for setup instructions.
- You are **authenticated** with the CLI (`pw auth login`).
- At least one **AI Chat provider** is configured and accessible to you. See [AI Chat Providers](/docs/ai/ai-chat-providers) for setup details.

## Listing Available Models

Before starting a chat, you can see which models are available to you:

```bash
pw ai models ls
```

This displays a table of all models across your configured providers. Each model is identified by a human-friendly identifier in the format `owner:provider-name/model-name` (for example, `me:my-azure-provider/gpt-4o`).

## Starting a New Chat

To start an interactive chat session, run:

```bash
pw ai chats new
```

This opens a full-screen interactive TUI. If no model is specified, an interactive model picker is displayed so you can choose from your available models. You can also specify a model directly to skip the picker:

```bash
pw ai chats new me:my-azure-provider/gpt-4o
```

### Non-Interactive Mode

To send a single prompt and print the response without entering the interactive TUI, use the `--prompt` flag. A model argument is required in non-interactive mode:

```bash
pw ai chats new -p "What is the capital of France?" me:my-azure-provider/gpt-4o
```

By default, non-interactive chats are not saved. To persist the conversation, add the `--save` flag:

```bash
pw ai chats new -p "Summarize TCP vs UDP" --save me:my-azure-provider/gpt-4o
```

## Resuming a Chat

To continue a previous conversation:

```bash
pw ai chats resume <id>
```

The model is automatically detected from the conversation history. You can override it with the `--model` flag:

```bash
pw ai chats resume -m me:my-azure-provider/gpt-4o abc-123
```

You can also send a single prompt to an existing chat:

```bash
pw ai chats resume -p "Summarize our conversation" abc-123
```

## Managing Chats

### Listing Chats

```bash
pw ai chats ls
```

Lists your recent chats in a table, sorted with the most recent at the bottom. Use `--limit` and `--offset` for pagination, and `-o json` for JSON output.

### Viewing a Chat

```bash
pw ai chats get <id>
```

Displays the full message history of a chat. Use `-o json` for JSON output.

### Deleting a Chat

```bash
pw ai chats delete <id>
```

## Managing Providers

The CLI also provides commands for managing AI Chat providers:

```bash
# List all providers
pw ai providers ls

# Get details of a specific provider
pw ai providers get my-provider

# List models available for a provider
pw ai providers models my-provider

# Create a custom provider
pw ai providers create --name my-provider --csp custom --endpoint https://api.example.com --api-key sk-xxx

# Create an Azure provider
pw ai providers create --name my-azure --csp azure --region eastus --model gpt-4 --group my-group --network my-network

# Delete a provider
pw ai providers delete my-provider
```

## Interactive Session

Once the TUI starts, you can type messages and press **Enter** to send them. Responses stream in real time with markdown formatting.

### Ending a Session

- Press **Ctrl+C** to quit the interactive session.

## Examples

### Basic question and answer

```bash
pw ai chats new me:my-azure-provider/gpt-4o
```

```
> Explain the difference between TCP and UDP in two sentences.

TCP is a connection-oriented protocol that guarantees reliable, ordered
delivery of data through acknowledgments and retransmissions. UDP is a
connectionless protocol that sends data without establishing a connection
or guaranteeing delivery, making it faster but less reliable.
```

### Single prompt from a script

```bash
pw ai chats new -p "List three sorting algorithms" me:my-provider/gpt-4o
```

### Resume and continue a conversation

```bash
# List your chats to find the ID
pw ai chats ls

# Resume the conversation
pw ai chats resume abc-123
```

## Related Documentation

- [Getting Started with AI Chat](/docs/ai/ai-chat/getting-started) - Web-based chat walkthrough
- [AI Chat Providers](/docs/ai/ai-chat-providers) - Configure and manage providers
- [CLI Reference: pw ai](/docs/cli/pw/ai) - Full CLI command reference
- [CLI Reference: pw ai chats new](/docs/cli/pw/ai/chats/new) - New chat command reference
- [CLI Reference: pw ai chats resume](/docs/cli/pw/ai/chats/resume) - Resume chat command reference