Parallel Works
View as Markdown
Share:

Using the CLI

You can start an AI session directly from your terminal with the PW CLI. The main entry point is pw code, an interactive AI agent that runs in your terminal with streaming responses and markdown rendering. By default it can read, write, and edit files in your workspace to carry out tasks, and it asks for your approval before making changes. You can also run it as a plain conversational chat with tool calling turned off.

The CLI also includes commands for managing the chats saved to your account, listing models, and configuring providers.

Prerequisites

Before starting an AI session 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 provider is configured and accessible to you. See AI Providers for setup details.

Listing Available Models

Before starting a session, 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 Session

To start an interactive session, run:

pw code

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 code me:my-azure-provider/gpt-4o

The agent can use tools to act on your workspace — for example, reading and editing files — and prompts you for approval before making changes.

Chat-Only Mode

To use pw code as a plain conversational chat without file access or other tools, pass --no-tools:

pw code --no-tools me:my-azure-provider/gpt-4o

Controlling Permissions

By default, the agent asks before taking actions such as editing files. Use --permission-mode to change this behavior:

# Never modify files (read and answer only)
pw code --permission-mode read-only me:my-azure-provider/gpt-4o
 
# Apply edits without prompting for each one
pw code --permission-mode accept-edits me:my-azure-provider/gpt-4o

The available modes are read-only, accept-edits, plan, and bypass-permissions.

Non-Interactive Mode

To send a single prompt and print the response without entering the interactive TUI, use the --prompt flag:

pw code -p "What is the capital of France?" me:my-azure-provider/gpt-4o

For automation, add -o json to receive structured output:

pw code -p "list Go files" -o json me:my-azure-provider/gpt-4o

Resuming a Session

pw code sessions are stored locally on your machine. To continue a previous session:

# Resume the most recent session
pw code -r latest
 
# Resume a specific session by ID
pw code -r 20260101-120000-a1b2
 
# Choose a session from a list
pw code --resume

Managing Your Saved Chats

The pw ai chats commands work with the chats saved to your account, such as conversations you started in the web app. (These are separate from the local sessions created by pw code.)

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 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 code 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 code -p "List three sorting algorithms" me:my-provider/gpt-4o

Resume your most recent session

pw code -r latest

Related Documentation