Kiro 핸드북

테마

헤드리스 실행 ​

목표 ​

IDE 없이 CLI나 CI/CD 파이프라인에서 Kiro의 AI 기능을 실행하는 헤드리스 모드의 개념과 활용법을 이해합니다.

개념 ​

IDE를 열지 않고 CLI 또는 CI/CD 파이프라인에서 Kiro의 AI 기능을 실행하는 방식입니다.

활용 사례 ​

시나리오설명
CI/CD 통합빌드 시 자동 코드 리뷰
배치 처리여러 파일을 일괄 변환
스케줄링정기적 코드 품질 체크
서버 환경GUI 없는 환경에서 실행

예시 (Kiro CLI) ​

bash
# CLI에서 특정 작업 실행
kiro-cli chat --prompt "프로젝트의 README.md를 최신 상태로 업데이트해줘"

사전 준비 ​

해볼 것 ​

1단계: 프로젝트 폴더에서 실행하기 ​

터미널에서 대상 프로젝트 폴더로 이동한 뒤 다음 명령을 실행합니다:

bash
kiro-cli chat --prompt "README.md를 최신 상태로 업데이트해줘"

2단계: 출력과 파일 확인하기 ​

터미널에 작업 결과가 출력되는지 확인합니다. 명령이 끝나면 README.md를 열어 요청한 변경이 반영되었는지 검토합니다.

3단계: 종료 상태 확인하기 ​

명령 실행이 끝난 뒤 셸에서 종료 코드를 확인합니다:

bash
echo $?

정상 완료 시 성공 종료 코드를 확인하고, 실패했다면 터미널에 출력된 인증·경로·명령 오류를 먼저 해결합니다.

4단계: CI에서 실패 처리하기 ​

CI 스크립트에서는 같은 명령을 실행하고 비영점 종료 코드를 실패로 처리하는 최소 형태로 시작할 수 있습니다:

bash
kiro-cli chat --prompt "README.md를 최신 상태로 업데이트해줘" || exit $?

CI 서비스별 인증과 비밀 정보 설정은 환경마다 다릅니다. 먼저 로컬 프로젝트에서 명령과 종료 상태를 검증한 뒤 사용하는 CI 환경에 맞게 연결하세요.

기대 결과 ​

  • IDE를 열지 않고 프로젝트 폴더에서 프롬프트를 실행함
  • 터미널 출력과 변경된 README.md로 작업 결과를 확인함
  • 종료 코드를 사용해 자동화 성공과 실패를 구분함
0 / 5항목을 클릭해 체크 · 진행 상태는 이 브라우저에 저장됩니다

다른 기능과의 조합 ​

커스텀 에이전트와 조합하면 전문화된 에이전트를 자동화 파이프라인에서 실행할 수 있습니다. Checkpoints가 안전망 역할을 하므로, 헤드리스 실행 중 문제가 생겨도 이전 상태로 복원할 수 있습니다. 세 기능을 함께 사용하면 완전 자동화된 AI 개발 파이프라인을 구축할 수 있습니다.

컨텍스트 설계의 전체 그림은 Context Engineering에서 확인하세요.

🚨 문제 해결

  • kiro-cli 명령을 찾을 수 없음: Kiro CLI 설치 여부와 실행 파일이 PATH에 포함되어 있는지 확인하세요.
  • 인증 오류가 발생함: Kiro CLI 로그인 절차를 다시 확인하고 로그인 상태를 갱신하세요.

✅ 핵심 요약

헤드리스 = GUI 없이 CLI/CI에서 AI 기능 실행. 커스텀 에이전트와 조합하면 완전 자동화 가능

© 2026 Kiro 핸드북 · 비공식 자료이며 AWS와 무관합니다.