claude CLI 를 실행하는 TypeScript 라이브러리입니다. npm 에 배포하지 않고 이 저장소의 패키지에서 workspace:* 로 씁니다.
claude CLI 를 설치하고 한 번 실행해 로그인합니다.
import { buildClaudeCommand, ClaudeCli } from "claude-cli";
const command = buildClaudeCommand({
executionMode: "print",
prompt: "이 폴더의 테스트 구조를 요약해 주세요",
tools: ["Read", "Grep", "Glob"],
permissionMode: "dontAsk",
maxBudgetUsd: 1,
});
const { result, sessionId } = await new ClaudeCli("claude", 300_000).run(
command,
"/path/to/project",
);| 이름 | 설명 |
|---|---|
buildClaudeCommand(request) |
요청을 CLI 인자와 stdin 으로 바꿉니다 |
buildWakeCommand(id, prompt) |
멈춘 백그라운드 세션을 같은 ID 로 깨우는 명령을 만듭니다 |
ClaudeCli.run |
-p 로 실행하고 결과를 돌려줍니다 |
ClaudeCli.runCollectingToolCalls |
실제 호출된 도구와 결과를 돌려줍니다. stream-json 필요 |
ClaudeCli.startBackground |
--bg 로 세션을 띄우고 바로 돌아옵니다 |
ClaudeCli.stopBackground |
백그라운드 세션의 프로세스만 멈춥니다 |
listClaudeSessions(options) |
세션 목록을 읽습니다. 살아 있는 세션에만 pid 가 있습니다 |
- 격리: 기본으로 MCP 서버와 사용자 설정을 읽지 않습니다.
shouldInheritUserConfig를 켜면 읽습니다. - 프롬프트: 인자가 아니라 stdin 으로 넘겨서 옵션으로 해석되지 않습니다.
- 비용 상한:
maxBudgetUsd가 0 이면 상한 없이 실행합니다.-p에서만 적용됩니다. - 도구:
tools의*는 전체 내장 도구입니다. - 세션 ID:
sessionId를 넣으면 새 세션을 그 UUID 로 시작합니다.-p에서만 쓸 수 있고resumeSessionId와 같이 쓸 수 없습니다. - 같은 세션 순서:
ClaudeCli.run은--session-id나--resume이 같은 세션을 가리키는 실행을 한 프로세스 안에서 하나씩 순서대로 실행합니다. 동시에 이어 가면 뒤 실행이 앞 실행의 결과를 보지 못하기 때문입니다. 다른 프로세스에서 실행한 것까지는 막지 않습니다. - 추가 인자:
additionalArguments는 맨 뒤에 붙어서 앞의 옵션보다 우선합니다.
모두 ClaudeError 를 상속합니다. CLI 가 시간 초과로 받은 SIGTERM 을 직접 처리해 코드 143 으로 끝나도 ClaudeTimedOutError 입니다.
| 클래스 | 상황 |
|---|---|
InvalidClaudeRequestError |
요청 값이 잘못됨 |
ClaudeFailedError |
CLI 실행 실패 |
ClaudeTimedOutError |
시간 초과 |
ClaudeCancelledError |
취소됨 |