Command Line Interface

Command Line Interface (CLI)

이 문서에서는 Pydantic AI의 CLI인 clai(발음: "clay")를 소개해요. 명령줄에서 바로 다양한 LLM과 채팅하고 빠르게 답을 얻거나, uvicorn 서버를 띄워 브라우저에서 Pydantic AI 에이전트와 채팅할 수 있어요.

출처: 문서

본문

Pydantic AI에는 clai(발음 "clay")라는 CLI가 함께 와요. 명령줄에서 바로 다양한 LLM과 채팅하고 빠르게 답을 얻거나, uvicorn 서버를 띄워 브라우저에서 Pydantic AI 에이전트와 채팅할 수 있어요.

Installation

clai를 uvx로 실행할 수 있어요:

Terminal

uvx clai

또는 clai를 with uv로 전역 설치하세요:

Terminal

uv tool install clai
...
clai

또는 pip로:

Terminal

pip install clai
...
clai

CLI Usage

사용하려는 프로바이더에 따라 환경 변수를 설정해야 해요.

예: OpenAI를 사용한다면 OPENAI_API_KEY 환경 변수를 설정하세요:

Terminal

export OPENAI_API_KEY='your-api-key-here'

그 다음 clai를 실행하면 AI 모델과 채팅할 수 있는 대화형 세션이 시작돼요. 대화형 모드에서 사용 가능한 특수 명령:

• /exit: 세션 종료
• /markdown: 마지막 응답을 markdown 형식으로 표시
• /multiline: 다중 줄 입력 모드 토글(Ctrl+D로 제출)
• /cp: 마지막 응답을 클립보드로 복사
• /usage: 세션의 누적 토큰 사용량 표시(turns, input, output, requests, tool calls). 한 줄 JSON 객체를 원하면 --json 추가

스트리밍(기본값)에서는 에이전트가 호출하는 모든 도구가 실행 중일 때 표시되고 결과가 도착하면 완료로 표시되므로, 터미널을 떠나지 않고 도구 사용 에이전트를 따라갈 수 있어요. 최종 답만 출력하려면 --no-stream을 전달하세요.

CLI Options

Option

Description

prompt

일회성 모드용 AI 프롬프트(위치 인자). 생략하면 대화형 모드 시작.

-m, --model

provider:model 형식의 모델(예: openai:gpt-5.2)

-a, --agent

module:variable 형식의 커스텀 에이전트

-t, --code-theme

구문 강조 테마(dark, light, 또는 pygments 테마)

--no-stream

모델 스트리밍 비활성화

--mcp-config

MCP 서버 구성 파일 경로(JSON, Claude Desktop, Claude Code, Cursor와 같은 mcpServers 형태 사용)

-l, --list-models

사용 가능한 모든 모델 나열 후 종료

--version

버전 표시 후 종료

Choose a model

--model 플래그로 사용할 모델을 지정할 수 있어요:

Terminal

clai --model anthropic:claude-sonnet-4-6

(사용 가능한 전체 모델 목록은 clai --list-models로 출력 가능)

MCP Servers

Claude Desktop, Claude Code, Cursor와 같은 mcpServers 형태를 사용하는 JSON 구성 파일과 함께 --mcp-config 플래그로 MCP 서버에 연결할 수 있어요:

Terminal

clai --mcp-config mcp_servers.json

구성 파일을 신뢰된 입력으로 취급하세요

구성 파일은 하위 프로세스로 실행할 실행 파일을 이름지고 ${VAR} 참조를 전체 프로세스 환경에 대해 확장하므로, 이 파일을 쓸 수 있는 사람은 누구나 임의의 명령을 실행하고 어떤 환경 변수도 읽을 수 있어요. 통제하는 파일에만 --mcp-config를 전달하세요.

mcp_servers.json

{
  "mcpServers": {
    "my-stdio-server": {
      "command": "uvx",
      "args": ["mcp_server"]
    },
    "my-http-server": {
      "url": "http://localhost:8000/sse"
    }
  }
}

Custom Agents

모듈 경로와 변수 이름으로 --agent 플래그로 커스텀 에이전트를 지정할 수 있어요:

custom_agent.py

from pydantic_ai import Agent

agent = Agent('openai:gpt-5.2', instructions='You always respond in Italian.')

그 다음 실행:

Terminal

clai --agent custom_agent:agent "What's the weather today?"

형식은 module:variable이어야 하며, 여기서:

• module은 import 가능한 Python 모듈 경로
• variable은 그 모듈의 Agent 인스턴스 이름

추가로 Agent.to_cli_sync()으로 Agent 인스턴스에서 직접 CLI 모드를 실행할 수 있어요:

agent_to_cli_sync.py

from pydantic_ai import Agent

agent = Agent('openai:gpt-5.2', instructions='You always respond in Italian.')
agent.to_cli_sync()

Agent.to_cli()로 비동기 인터페이스도 사용할 수 있어요:

agent_to_cli.py

from pydantic_ai import Agent

agent = Agent('openai:gpt-5.2', instructions='You always respond in Italian.')

async def main():
    await agent.to_cli()

(이 예시를 실행하려면 asyncio를 import하고 asyncio.run(main())을 추가하세요. 다른 변경은 필요 없어요.)

둘 다 clai와 같은 채팅 인터페이스를 실행하므로, 도구가 있는 에이전트는 CLI Usage에서 설명한 대로 각 호출을 실행 중에 보여주고 결과가 도착하면 완료로 표시해요.

Message History

Agent.to_cli()와 Agent.to_cli_sync() 둘 다 message_history 파라미터를 지원해 기존 대화를 이어가거나 대화 컨텍스트를 제공할 수 있어요:

agent_with_history.py

from pydantic_ai import (
    Agent,
    ModelMessage,
    ModelRequest,
    ModelResponse,
    TextPart,
    UserPromptPart,
)

agent = Agent('openai:gpt-5.2')

# Create some conversation history
message_history: list[ModelMessage] = [
    ModelRequest([UserPromptPart(content='What is 2+2?')]),
    ModelResponse([TextPart(content='2+2 equals 4.')])
]

# Start CLI with existing conversation context
agent.to_cli_sync(message_history=message_history)

CLI는 제공된 대화 히스토리로 시작하므로, 에이전트가 이전 교환을 참조하고 세션 전반에 컨텍스트를 유지할 수 있어요.

Web Chat UI

다음을 실행해 웹 기반 채팅 인터페이스를 실행하세요:

Terminal

clai web -m openai:gpt-5.2

이렇게 하면 채팅 인터페이스가 있는 웹 서버(기본: http://127.0.0.1:7932)가 시작돼요.

기존 에이전트를 서빙할 수도 있어요. 예를 들어 my_agent.py에 정의된 에이전트가 있다면:

from pydantic_ai import Agent

my_agent = Agent('openai:gpt-5.2', instructions='You are a helpful assistant.')

웹 UI를 실행하세요:

Terminal

# With a custom agent
clai web --agent my_module:my_agent

# With specific models (first is default when no --agent)
clai web -m openai:gpt-5.2 -m anthropic:claude-sonnet-4-6

# With native tools
clai web -m openai:gpt-5.2 -t web_search -t code_execution

# Generic agent with system instructions
clai web -m openai:gpt-5.2 -i 'You are a helpful coding assistant'

# Custom agent with extra instructions for each run
clai web --agent my_module:my_agent -i 'Always respond in Spanish'

메모리 도구

memory 네이티브 도구는 -t memory로 활성화할 수 없어요. 에이전트가 메모리가 필요하면 MemoryTool을 에이전트에 직접 구성하고 --agent로 제공하세요.

Web UI Options

Option

Description

--agent, -a

module:variable format으로 서빙할 에이전트

--model, -m

UI에서 옵션으로 나열할 모델(반복 가능)

--tool, -t

UI에서 옵션으로 나열할 네이티브 도구(반복 가능). 사용 가능한 도구 참고.

--instructions, -i

시스템 지침. --agent가 지정되면 에이전트의 기존 지침에 추가돼요.

--host

서버 바인딩 호스트(기본: 127.0.0.1)

--port

서버 바인딩 포트(기본: 7932)

--html-source

채팅 UI HTML의 URL 또는 파일 경로.

--allowed-host

IP 주소와 localhost 외에 응답할 호스트 이름(반복 가능). 호스트 이름으로 UI에 도달하기 참고.

--agent를 사용할 때 에이전트의 구성된 모델이 기본이 돼요. CLI 모델(-m)은 추가 옵션이에요. --agent 없이 -m 모델이 첫 번째로 기본이 돼요.

웹 채팅 UI는 Agent.to_web()로 프로그래matically 실행할 수도 있어요. Web UI 문서 참고.

web 명령을 --help로 실행해 모든 사용 가능한 옵션을 보세요:

Terminal

clai web --help

더 알아보기 (Learn more)

• pydantic-ai 문서