Parallel Works
View as Markdown
Share:

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 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 for setup details.

Listing Available Models

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

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:

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:

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:

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:

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

Resuming a Chat

To continue a previous conversation:

pw ai chats resume <id>

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

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

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

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

Managing Chats

Listing Chats

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

pw ai chats get <id>

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

Deleting a Chat

pw ai chats delete <id>

Managing Providers

The CLI also provides commands for managing AI Chat providers:

# 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

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

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

Resume and continue a conversation

# List your chats to find the ID
pw ai chats ls
 
# Resume the conversation
pw ai chats resume abc-123

Related Documentation