README.ko.md

task-pipeliner

조건 기반 실행과 아름다운 CLI 출력을 제공하는 강력한 워크플로우 오케스트레이션 도구

버전: 0.3.16

task-pipeliner는 간단한 YAML 또는 JSON 파일로 복잡한 워크플로우를 정의, 조율, 실행할 수 있는 현대적인 워크플로우 오케스트레이션 도구입니다. 조건부 실행, 병렬 작업, 대화형 프롬프트, 그리고 아름다운 터미널 출력을 제공하여 빌드 스크립트, 배포 워크플로우, CI/CD 파이프라인에 완벽합니다. 아직 베타 버전이라 인터페이스가 조금씩 수정될 수 있습니다.

README-Language-Map KR [한국어 버전] / EN [English Version]

📖 자세한 내용은 공식 문서를 참조하세요!
이 README는 빠른 시작과 기본 사용법을 제공합니다. DSL 문법, 고급 기능, 예제 등 자세한 내용은 문서 사이트에서 확인할 수 있습니다.

리소스

문서 및 도구

• 📖 공식 문서 - 완전한 DSL 참조, 가이드, 예제 및 모든 기능 설명 ⭐
• 🎨 워크플로우 생성기 - 브라우저에서 시각적으로 워크플로우 생성

저장소 및 패키지 관리자

• 💻 GitHub - 소스 코드 및 이슈 추적
• 📦 npm - npm 레지스트리 패키지
• 🍺 Homebrew - macOS/Linux용 Homebrew 탭
• 🪟 Scoop - Windows용 Scoop 버킷

✨ 주요 기능

💡 각 기능에 대한 자세한 설명과 예제는 DSL 참조 문서를 확인하세요.

• 조건 기반 실행 - 파일 존재 여부, 사용자 선택, 환경 변수 등을 기반으로 단계 실행

• 병렬 실행 - 여러 작업을 동시에 병렬로 실행

• 대화형 프롬프트 - 실행 중 사용자에게 입력과 선택을 요청

• YAML & JSON 지원 - 선언적인 파이프라이닝을 YAML & JSON 형식으로 제공

• 변수 치환 - 워크플로우 전반에서 {{variables}} 사용

• Stdout 캡쳐 - 다양한 캡쳐 전략(정규식, JSON/YAML, 키-값 등)을 사용하여 명령 출력에서 값을 추출하여 변수로 저장

• 프로필 - 미리 정의한 변수로 비대화형 실행 (tp run --profile <name>); 프로필에 설정된 변수에 대해서는 choose/prompt 단계 생략

• 실행 히스토리 - 상세한 단계별 기록으로 과거 워크플로우 실행 추적 및 검토

• 워크플로우 스케줄링 - cron 표현식을 사용하여 지정된 시간에 워크플로우 자동 실행

CLI 명령어

💡 CLI 명령어에 대한 자세한 설명은 CLI 참조 문서를 확인하세요.

프로젝트 셋업 (신규 프로젝트 권장):

tp setup   # tp/, tp/workflows, tp/schedules 생성 및 예시 워크플로우 2개·예시 스케줄 2개 추가 (echo 기반; choose, when, profiles, prompt 포함)

프로젝트 루트에서 실행. tp/workflows/, tp/schedules/를 만들고, choose·when·profiles·prompt를 쓴 예시 워크플로우와 cron·프로필을 쓴 예시 스케줄을 넣습니다. 이미 있는 파일은 덮어쓰지 않습니다.

워크플로우 실행:

tp run workflow.yaml        # 워크플로우 실행
tp run                      # 가장 가까운 tp/workflows 디렉토리에서 워크플로우 선택하여 실행
tp run workflow.yaml --profile Test   # 프로필로 실행 (프로필에 설정된 변수는 choose/prompt 생략)
tp run workflow.yaml -p Test         # 프로필 짧은 형식
tp run workflow.yaml --silent  # 사일런트 모드로 실행 (모든 콘솔 출력 억제)
tp run workflow.yaml -s     # 사일런트 모드 짧은 형식

리소스 열기:

tp open generator  # 시각적 생성기 열기
tp open docs       # 문서 열기

히스토리 관리:

tp history         # 워크플로우 실행 히스토리 보기
tp history show    # 특정 히스토리 선택하여 보기
tp history remove   # 특정 히스토리 삭제
tp history remove-all # 모든 히스토리 삭제

워크플로우 스케줄링:

tp schedule        # 모든 스케줄 보기 (tp schedule list와 동일)
tp schedule list   # 스케줄 목록 및 데몬 상태 (각 스케줄을 카드로 표시: cron, 언제 실행되는지 설명, 다음 실행 시각 등)
tp schedule add schedules.yaml  # 스케줄 파일에서 추가; 파일 경로 생략 시 가장 가까운 tp/schedules에서 선택
tp schedule add    # 가장 가까운 tp/schedules 디렉토리에서 스케줄 파일 선택
tp schedule remove # 스케줄 삭제; 삭제 후 삭제된 스케줄을 list와 동일한 카드 형식으로 표시
tp schedule remove-all # 모든 스케줄 삭제
tp schedule toggle # 스케줄 활성화/비활성화; 토글 후 ENABLED/DISABLED를 굵게·색상으로 강조하고 스케줄 카드 표시
tp schedule start  # 포그라운드 모드로 스케줄러 시작
tp schedule start -d  # 백그라운드 데몬 모드로 스케줄러 시작
tp schedule stop   # 스케줄러 데몬 종료
tp schedule status # 데몬·스케줄 상태 확인 (실시간 모드; Ctrl+C는 화면만 종료, 데몬은 계속 실행)

tp schedule add, toggle, remove 후에는 해당 스케줄이 tp schedule list와 같은 카드 레이아웃(크론, 언제 실행되는지 설명, 다음 실행, 활성 여부)으로 표시됩니다. 토글 후에는 ENABLED/DISABLED가 강조되어 새 상태를 한눈에 알 수 있습니다.

스케줄 상태 (실시간 뷰) — tp schedule status로 데몬과 모든 스케줄을 스크롤 가능한 실시간 화면으로 확인할 수 있습니다. Cron 시간에는 타임존(UTC 또는 local)이 함께 표시됩니다. 스케줄이 많을 때는 ↑/↓ 또는 PgUp/PgDn으로 스크롤할 수 있습니다.

데이터 및 업그레이드:

tp clean   # ~/.pipeliner 전체 삭제 (스케줄, 데몬 상태, 워크플로우 히스토리)

버전 업그레이드 후 호환이 맞지 않을 때(스케줄/데몬 오류 등)는 tp clean으로 로컬 데이터를 초기화하면 됩니다. 실행 중인 데몬이 있으면 먼저 종료된 뒤 삭제됩니다.

🚀 빠른 시작

설치

Homebrew (macOS/Linux)

macOS와 Linux에서 가장 쉬운 설치 방법은 Homebrew를 사용하는 것입니다:

# 탭(저장소) 추가
brew tap racgoo/task-pipeliner

# task-pipeliner 설치
brew install task-pipeliner

설치 후 다음 명령으로 실행할 수 있습니다:

task-pipeliner run workflow.yaml
# 또는 짧은 별칭 사용
tp run workflow.yaml

설치 확인:

task-pipeliner --version
# 또는
tp --version

업데이트:

# 먼저 Homebrew의 패키지 레지스트리를 업데이트합니다
brew update

# 그 다음 task-pipeliner를 업그레이드합니다
brew upgrade task-pipeliner

업그레이드 후 호환 문제(스케줄/데몬 오류 등)가 있으면 tp clean으로 ~/.pipeliner 데이터(스케줄, 데몬 상태, 히스토리)를 초기화하세요.

Scoop (Windows)

Windows에서 Scoop을 사용하여 설치:

# 버킷(저장소) 추가
scoop bucket add task-pipeliner https://github.com/racgoo/scoop-task-pipeliner

# task-pipeliner 설치
scoop install task-pipeliner

설치 후 다음 명령으로 실행할 수 있습니다:

task-pipeliner run workflow.yaml
# 또는 짧은 별칭 사용
tp run workflow.yaml

설치 확인:

task-pipeliner --version
# 또는
tp --version

업데이트: 버킷을 먼저 갱신한 뒤 앱을 업데이트하세요.

scoop update
scoop update task-pipeliner

업그레이드 후 문제가 있으면 tp clean으로 ~/.pipeliner 데이터를 초기화하세요.

전역 설치 (npm)

npm을 사용하여 전역으로 설치하면 task-pipeliner 또는 tp 명령을 직접 사용할 수 있습니다:

npm install -g task-pipeliner
# 또는
pnpm add -g task-pipeliner

전역 설치 후 다음 명령으로 실행할 수 있습니다:

task-pipeliner run workflow.yaml
# 또는 짧은 별칭 사용
tp run workflow.yaml

설치 확인:

task-pipeliner --version
# 또는
tp --version

프로젝트 설치 (개발 모드)

프로젝트에 devDependency로 설치하면 npx로 사용할 수 있습니다:

npm install -D task-pipeliner
# 또는
pnpm add -D task-pipeliner

프로젝트 설치 후 다음 명령으로 실행할 수 있습니다:

npx task-pipeliner run workflow.yaml
# 또는 짧은 별칭 사용
npx tp run workflow.yaml

기본 사용법

💡 더 많은 예제와 고급 사용법은 시작하기 가이드와 예제 문서를 참조하세요.

workflow.yaml 또는 workflow.json 파일을 생성하세요:

YAML 형식 (workflow.yaml):

name: My Workflow

steps:
  - run: 'echo "Hello, World!"'
  
  - choose:
      message: "무엇을 하시겠습니까?"
      options:
        - id: build
          label: "프로젝트 빌드"
        - id: test
          label: "테스트 실행"
      as: action
  
  - when:
      var:
        action: build
    run: 'npm run build'
  
  - when:
      var:
        action: test
    run: 'npm test'
  
  # 명령 출력에서 값 추출
  - run: 'cat package.json'
    captures:
      - json: "$.version"
        as: version
  - run: 'echo "Version: {{version}}"'

JSON 형식 (workflow.json):

{
  "name": "My Workflow",
  "steps": [
    {
      "run": "echo \"Hello, World!\""
    },
    {
      "choose": {
        "message": "무엇을 하시겠습니까?",
        "options": [
          {
            "id": "build",
            "label": "프로젝트 빌드"
          },
          {
            "id": "test",
            "label": "테스트 실행"
          }
        ],
        "as": "action"
      }
    },
    {
      "when": {
        "var": {
          "action": "build"
        }
      },
      "run": "npm run build"
    },
    {
      "when": {
        "var": {
          "action": "test"
        }
      },
      "run": "npm test"
    }
  ]
}

실행:

task-pipeliner run workflow.yaml
# 또는
task-pipeliner run workflow.json
# 또는 짧은 별칭 사용
tp run workflow.yaml
tp run workflow.json

# 사일런트 모드로 실행 (모든 콘솔 출력 억제)
tp run workflow.yaml --silent
# 또는 짧은 형식 사용
tp run workflow.yaml -s

tp 디렉토리 사용하기 (권장):

권장 프로젝트 구조는 tp 디렉토리 아래에 두 개의 하위 디렉토리를 두는 방식입니다.

• tp/workflows/ – 워크플로우 파일(YAML 또는 JSON). 파일 없이 tp run을 실행하면 task-pipeliner가 가장 가까운 tp 디렉토리를 찾고, tp/workflows/ 안에서 실행할 워크플로우를 선택할 수 있게 합니다.
• tp/schedules/ – 스케줄 파일(YAML 또는 JSON). tp schedule add 실행 시 파일 경로를 주지 않으면 가장 가까운 tp/schedules/ 안에서 스케줄 파일을 선택할 수 있습니다.

빠른 셋업: 프로젝트 루트에서 tp setup을 실행하면 tp/, tp/workflows/, tp/schedules/가 생성되고, 예시 워크플로우 2개와 예시 스케줄 파일 2개(echo 기반, choose·when·profiles·prompt 및 스케줄 프로필 사용 예시 포함)가 추가됩니다. 이미 있는 파일은 덮어쓰지 않습니다.

# 방법 1: tp setup 사용 (tp/workflows, tp/schedules + 예시 생성)
tp setup

# 방법 2: 수동으로 구조 만들기
mkdir -p tp/workflows tp/schedules
mv workflow.yaml tp/workflows/

# 파일 없이 실행 - tp/workflows에서 대화형 선택
tp run

파일을 지정하지 않고 tp run을 실행하면:

1. 가장 가까운 tp 디렉토리를 찾습니다 (현재 디렉토리 또는 상위).
2. tp/workflows/ 안의 모든 워크플로우 파일 (.yaml, .yml, .json)을 나열합니다.
3. 타이핑으로 필터, 화살표(↑↓)로 이동, Enter로 선택·실행하는 대화형 검색 메뉴를 띄웁니다.

메뉴에는 파일 이름과 워크플로우의 name(YAML/JSON)이 함께 표시되어 구분하기 쉽습니다.

사일런트 모드: --silent (또는 -s) 플래그는 워크플로우 실행 중 모든 콘솔 출력을 억제합니다. 다음 경우에 유용합니다:

• 종료 코드만 필요한 CI/CD 파이프라인
• 상세한 출력이 필요 없는 자동화 스크립트
• 로그의 노이즈 감소

참고: 사일런트 모드는 명령 출력, 단계 헤더, 에러 메시지를 포함한 모든 출력을 억제합니다. 워크플로우는 정상적으로 실행되며 적절한 종료 코드를 반환합니다.

📚 더 알아보기

이 README는 기본적인 사용법만 다룹니다. 더 자세한 내용은 다음 문서를 참조하세요:

• 시작하기 - 설치부터 첫 워크플로우까지
• DSL 참조 - 완전한 문법 가이드
  • 워크플로우 구조
  • 단계 타입
  • 조건
  • 변수
  • 프로필
• CLI 참조 - 모든 CLI 명령어 상세 설명
• 예제 - 실제 사용 사례와 예제
• 실행 히스토리 - 과거 실행 기록 관리
• 워크플로우 스케줄링 - cron을 사용한 자동 실행

기여하기

기여를 환영합니다! ISSUE를 남겨주세요.

라이선스

Copyright (c) 2026 racgoo

문의 및 연락

문의 사항은 lhsung98@naver.com 으로 메일 보내주세요!