runprompt

단일 파일 Python 스크립트를 사용하여 셸(shell)에서 LLM .prompt 파일을 실행하세요.

.prompt 파일은 프롬프트와 메타데이터(model, schema, config)를 단일 파일에 포함합니다. 이를 사용하여 셸에서 LLM 프롬프트를 실행하고 구조화된 응답을 얻을 수 있습니다. AI 워크플로우를 자동화하거나 자체 하네스(harness)를 구축하는 데 사용할 수 있습니다. 프롬프트를 일급 공민(first-class artifacts)으로 만드세요. AI 챗봇에 임시 요청(ad-hoc requests)을 하는 대신, 레포지토리(repo)에 포함하고 명령줄에서 실행하세요.

Quick start | Examples | Tools | Template syntax | Configuration | Providers | Caching | Spec compliance

Quick start

단일 파일 스크립트를 다운로드하세요:

curl -O https://raw.githubusercontent.com/chr15m/runprompt/main/runprompt
chmod +x runprompt

또는 uvx를 사용하여 설치 없이 직접 실행할 수 있습니다:

uvx --from git+https://github.com/chr15m/runprompt runprompt hello.prompt

또는 라이브러리로 사용하기 위해 pip 또는 uv를 통해 설치할 수 있습니다:

# uv 사용 (권장)
uv pip install git+https://github.com/chr15m/runprompt

...

hello.prompt 파일을 생성하세요:

---
model: anthropic/claude-sonnet-4-20250514
---
...

실행하세요:

export ANTHROPIC_API_KEY="your-key"
./runprompt hello.prompt '{"name": "World"}'
# 대안으로 STDIN을 통해 데이터를 전달할 수 있습니다.
...

(Anthropic 키는 여기에서 얻을 수 있습니다: https://console.anthropic.com/settings/keys 다른 키는 아래를 참조하세요.)

Examples

다음 외에도 더 많은 예제 .prompt 파일은 tests 폴더를 확인해 보세요.

Basic prompt with stdin

---
model: anthropic/claude-sonnet-4-20250514
---
...

cat article.txt | ./runprompt summarize.prompt

특수 변수 {{STDIN}}은 항상 원본 표준 입력(raw stdin)을 문자열로 포함합니다. {{STDIN}}과 {{ARGS}}는 항상 사용 가능하며, 입력이 JSON인 경우 개별 변수로 파싱됩니다.

인라인 프롬프트 (Inline prompts)

.prompt 파일을 생성하지 않고 명령줄에서 템플릿을 직접 실행하려면 -p 또는 --prompt를 사용합니다:

./runprompt -p "Say hello to {{name}}" --model openai/gpt-4o '{"name": "World""}'

명령줄 인수 (Command line arguments)

인수를 명령줄에 직접 전달합니다:

---
model: anthropic/claude-sonnet-4-20250514
---
...

./runprompt process.prompt Hello world, please summarize this text.

특수 변수 {{ARGS}}는 프롬프트 파일 뒤에 오는 모든 인수를 공백으로 연결하여 포함합니다. {{INPUT}} 변수는 제공된 경우 STDIN을 포함하고, 그렇지 않으면 ARGS를 포함합니다.

구조화된 JSON 출력 (Structured JSON output)

출력 스키마를 사용하여 구조화된 데이터를 추출합니다:

---
model: anthropic/claude-sonnet-4-20250514
input:
...

echo "John is a 30 year old teacher" | ./runprompt extract.prompt
# {"name": "John", "age": 30, "occupation": "teacher"}

스키마는 Picoschema 형식을 사용합니다. ?로 끝나는 필드는 선택 사항입니다. 형식은 field: type, description입니다.

프롬프트 체이닝 (Chaining prompts)

프롬프트 간에 구조화된 출력을 파이프(|)로 연결합니다:

echo "John is 30" | ./runprompt extract.prompt | ./runprompt generate-bio.prompt

첫 번째 프롬프트의 JSON 출력은 두 번째 프롬프트의 템플릿 변수가 됩니다.

사전 프롬프트 셸 명령어 (Pre-prompt shell commands)

동적 컨텍스트를 수집하기 위해 프롬프트가 전송되기 전에 셸 명령어를 실행합니다:

---
model: anthropic/claude-sonnet-4-20250514
before:
...

각 명령어는 구성된 셸($SHELL, 기본값은 /bin/sh)에서 전체 셸 기능(파이프, 리디렉션 등)을 사용하여 실행됩니다. 성공하면 stdout이 캡처되고, 실패하면 stderr이 캡처됩니다. 모든 출력은 개별 변수와 결합된 {{BEFORE}} 변수로 사용 가능합니다.

템플릿 변수(Template variables)는 환경 변수(environment variables)로 셸(shell)에 전달되므로, 이를 참조할 수 있습니다:

---
model: anthropic/claude-sonnet-4-20250514
before:
...

실행 가능한 프롬프트 파일 (Executable prompt files)

.prompt 파일을 shebang을 사용하여 직접 실행 가능하게 만드세요:

#!/usr/bin/env runprompt
---
model: anthropic/claude-sonnet-4-20250514
...

chmod +x hello.prompt
echo '{"name": "World"}' | ./hello.prompt

참고: runprompt가 PATH에 있어야 하거나, shebang에서 상대/절대 경로를 사용해야 합니다 (예: #!/usr/bin/env ./runprompt).

대화형 채팅 모드 (Interactive chat mode)

--chat 플래그, RUNPROMPT_CHAT=1 환경 변수, 또는 프롬프트 프런트매터(frontmatter)의 chat: true를 사용하여 LLM과 대화형으로 상호작용할 수 있습니다. 대화 기록은 턴(turn) 간에 유지됩니다.

초기 컨텍스트나 페르소나를 설정하기 위해 프롬프트 파일로 채팅을 시작하세요:

./runprompt --chat expert.prompt

또는 프롬프트 파일 없이 순수한 채팅으로 시작하려면 (모델 지정 필요):

./runprompt --chat --model anthropic/claude-sonnet-4-20250514

세션 간에 readline 기록을 유지하려면 (chat 모드 및 ask_user 도구의 경우), RUNPROMPT_CHAT_HISTORY=1로 설정하거나 구성에서 chat_history: true를 사용하세요. 기록 파일 위치는 RUNPROMPT_HISTORY_FILE로 사용자 정의할 수 있습니다 (기본값은 .runprompt.history).

채팅 명령어 (Chat commands)

대화형 채팅 세션 중에는 컨텍스트나 도구를 동적으로 수정하기 위해 특별한 명령어를 사용할 수 있습니다:

• /read <경로 또는 URL>: 파일이나 URL을 읽어 그 내용을 채팅 컨텍스트에 추가합니다.
• /edit <경로>: 지정된 파일에 대해 write_file 도구를 LLM에게 동적으로 노출하여, 해당 파일을 작성하거나 편집할 수 있게 합니다.
• /drop <경로>: 지정된 파일에 대한 write_file 도구를 제거합니다.

CLI 오버라이드 (CLI overrides)

명령줄에서 프런트매터 값을 덮어쓰세요:

./runprompt --model anthropic/claude-haiku-4-20250514 hello.prompt
./runprompt --output.format json extract.prompt

중첩된 값에는 점 표기법(dot notation)을 사용하세요 (예: --output.format). 템플릿 변수는 stdin을 통해 전달하거나 JSON 인수로 전달할 수 있습니다:

echo '{"name": "Alice"}' | ./runprompt hello.prompt
./runprompt hello.prompt '{"name": "Alice"}'

모든 옵션은 --help를 참조하세요.

원시 API 응답 (Raw API responses)

표준 출력(standard output)에서는 최종 추출된 텍스트나 JSON만 출력되지만, --save-response를 사용하여 전체 원시 API 엔벨로프(token usage, finish reasons, 정확한 모델 버전 포함)를 저장할 수 있습니다:

./runprompt --save-response api_out.json hello.prompt

파일 첨부 (File attachments)

프롬프트 컨텍스트에 로컬 파일(glob 지원)과 URL을 첨부하세요.

Frontmatter를 통해:

---
model: anthropic/claude-sonnet-4-20250514
files:
...

파일 패턴에서 템플릿 변수(before:` 출력 포함)를 사용할 수 있습니다:

---
model: anthropic/claude-sonnet-4-20250514
before:
...

CLI를 통해 (glob 지원):
--file은 --read의 별칭입니다:

./runprompt --read README.md --read "src/**/*.py" review.prompt
./runprompt --file README.md review.prompt

두 가지를 결합할 수 있습니다: frontmatter의 files: 항목과 모든 --read/--file 플래그가 모두 포함됩니다.

첨부 파일이 로드되면, runprompt는 각 로드된 파일/URL에 대해 stderr로 노란색 메시지를 출력합니다.

도구 (Tools)

도구(Tools)를 사용하면 LLM이 프롬프트 실행 중에 Python 함수를 호출할 수 있습니다. docstring을 가진 Python 함수로 도구를 정의하면, LLM은 파일 읽기, API 호출, 시스템 상호 작용과 같은 작업을 수행하는 데 이를 사용할 수 있습니다.

도구 정의 (Defining tools)

함수가 포함된 Python 파일을 만드세요. docstring이 있는 모든 함수가 도구가 됩니다:

# my_tools.py
def get_weather(city: str):
    """도시의 현재 날씨를 가져옵니다.
... 

프롬프트에서 도구 사용 (Using tools in prompts)

Python import 구문을 사용하여 frontmatter에 도구를 참조하세요:

---
model: anthropic/claude-sonnet-4-20250514
tools:
...

도구 명세 (Tool specifications):

• module.* - module.py에서 docstring이 있는 모든 함수 가져오기
• module.function_name - 특정 함수 가져오기

도구를 사용한 프롬프트 실행

LLM(대규모 언어 모델)이 도구 호출을 원할 때, 확인 메시지가 표시됩니다:

$ ./runprompt weather.prompt

날씨를 확인해 드릴게요.
...

안전한 도구 (Safe tools)

도구를 "안전(safe)"으로 표시하면 --safe-yes 플래그, 환경 변수 RUNPROMPT_SAFE_YES, 또는 설정 safe_yes 사용 시 확인 없이 실행할 수 있습니다:

# my_tools.py
def get_weather(city: str):
    """도시의 현재 날씨를 가져옵니다 (읽기 전용 작업)."""
...

--safe-yes 또는 환경 변수 RUNPROMPT_SAFE_YES나 설정 변수 safe_yes로 실행하면 안전한 도구에 대해 자동 승인됩니다:

./runprompt --safe-yes weather.prompt

--safe-yes 사용 시:

• fn.safe = True로 표시된 도구는 프롬프트 없이 실행됩니다.
• safe 속성이 없는 도구도 여전히 확인을 요청합니다.

이는 특정 읽기 전용 또는 위험도가 낮은 작업을 신뢰하지만, 잠재적으로 위험한 동작에 대해서는 여전히 확인이 필요한 자동화 환경에서 유용합니다.

도구 가져오기 경로 (Tool import paths)

도구는 다음 위치에서 검색됩니다:

1. 현재 작업 디렉토리
2. 프롬프트 파일이 포함된 디렉토리
3. --tool-path 또는 설정 파일을 통한 추가 경로
4. 기본 설정 도구 디렉토리 (존재하는 경우):
   • ./.runprompt/tools
   • $XDG_CONFIG_HOME/runprompt/tools (기본값: ~/.config/runprompt/tools)
   • ~/.runprompt/tools

./runprompt --tool-path ./my_tools --tool-path /shared/tools prompt.prompt

모든 경로는 설정 파일 내의 tool_path 항목 외에 추가로 검색됩니다.

타입 힌트 (Type hints)

함수 매개변수에 대한 타입 힌트는 JSON Schema 유형에 매핑됩니다:

오류 처리 (Error handling)

도구가 예외(exception)를 발생시키면, 이 오류는 LLM에게 다시 전송되며, LLM은 어떻게 진행할지 결정할 수 있습니다:

Tool call: read_file
Arguments: {"path": "missing.txt"}

...

셸 도구 (Shell tools)

프롬프트 내에 간단한 셸 스크립트 도구 정의하기:

---
model: anthropic/claude-sonnet-4-20250514
shell_tools:
...

옵션이 있는 긴 형식:

shell_tools:
  git_log:
    cmd: git log --oneline
...

필드:

• cmd (필수): 실행할 셸 명령어
• safe (선택, 기본값: false): --safe-yes로 자동 승인되도록 안전하다고 표시
• description (선택, 기본값: cmd): LLM에 표시되는 설명

인자(Arguments):

LLM은 다음을 전달할 수 있습니다:

• args (문자열): 명령어 뒤에 추가됨
• 이름 지정된 매개변수로 환경 변수

예시 LLM 호출:

git_log(args="--author=alice -n 5")
search_code(args="TODO", PATH="/src")

셸 도구는 before: 명령어와 동일한 셸 해석기($SHELL, 기본값: /bin/sh)를 사용합니다.

내장 도구 (Builtin tools)

Runprompt에는 외부 Python 파일을 생성할 필요 없이 사용할 수 있는 내장 도구가 포함되어 있습니다:

---
model: anthropic/claude-sonnet-4-20250514
tools:
...

사용 가능한 내장 도구:

매개변수화된 도구 (Parameterized tools)

일부 내장 도구는 인자를 받아 특화된 도구를 생성하는

파일이나 함수 이름이 _로 시작하는 것은 와일드카드 임포트에서 제외됩니다:

# _helpers.py - 이 전체 파일은 와일드카드 임포트에서 제외됩니다
# my_tools.py
def _private_helper():  # 와일드카드 임포트에서 제외됨
...

도구로 노출하고 싶지 않은 헬퍼 함수에는 _ 접두사를 사용하세요.

템플릿 구문 (Template syntax)

템플릿은 Handlebars/Mustache 문법의 유용한 부분 집합을 사용합니다.

특수 변수 (Special variables)

• {{STDIN}} - 원시 stdin 내용 (항상 사용 가능)
• {{ARGS}} - 프롬프트 파일 이후의 명령줄 인수 (항상 사용 가능)
• {{INPUT}} - 제공된 경우 STDIN, 그렇지 않으면 ARGS (항상 사용 가능)
• {{BEFORE}} - 모든 before: 명령어에서 나온 결합 출력
• before: 명령어의 개별 변수 (예: {{latest_commit}})

지원되는 기능 (Supported features)