n8n-cli 운영 스킬

n8n-cli 운영 스킬은(는) 무엇을 하나요?

n8n-cli(TypeScript/Bun)를 사용한 워크플로우 관리를 지원하는 스킬입니다.

세션 초기화 (중요)

새로운 세션에서는 항상 다음 명령을 먼저 실행하여 n8n-cli가 최신 상태인지 확인하세요.

우선순위 1: 로컬 소스에서 빌드 (개발 환경)

n8n-cli 소스 저장소가 add-dir(예: /path/to/n8n-cli/Makefile 존재)을 통해 제공되는 경우, 릴리스 대신 로컬 소스에서 빌드하세요. 이렇게 하면 최신 개발 변경 사항이 즉시 반영됩니다.

# add-dir을 통해 n8n-cli 저장소가 보이는 경우
N8N_CLI_REPO="/path/to/n8n-cli"  # add-dir 경로로 대체
if [ -f "$N8N_CLI_REPO/Makefile" ]; then
  echo "로컬 소스에서 n8n-cli 빌드 중: $N8N_CLI_REPO"
  cd "$N8N_CLI_REPO" && bun install && make build
  cp "$N8N_CLI_REPO/n8n-cli" /path/to/target/n8n-cli
  cd /path/to/target
  echo "로컬 소스에서 빌드됨: $(./n8n-cli version 2>/dev/null | head -1)"
fi

우선순위 2: GitHub 릴리스에서 자동 업데이트 (권장)

사전 빌드된 바이너리는 GitHub 릴리스에서 제공됩니다. 소스에서 빌드하는 것보다 빠르며 공식 릴리스를 실행할 수 있습니다.

# 1. 최신 릴리스 버전 확인
LATEST_TAG=$(gh release view --repo ubie-oss/n8n-cli --json tagName -q '.tagName' 2>/dev/null)

# 2. 현재 로컬 버전 확인 (바이너리가 존재하는 경우)
CURRENT_VERSION=""
if [ -x ./n8n-cli ]; then
  CURRENT_VERSION=$(./n8n-cli version 2>/dev/null | head -1 | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' || echo "")
fi

# 3. 비교 후 필요시 다운로드
if [ -z "$CURRENT_VERSION" ] || [ "$CURRENT_VERSION" != "$LATEST_TAG" ]; then
  echo "n8n-cli 업데이트 중: ${CURRENT_VERSION:-없음} -> ${LATEST_TAG}"

  # 플랫폼 감지
  ARCH=$(uname -m)
  OS=$(uname -s | tr '[:upper:]' '[:lower:]')
  case "$ARCH" in
    arm64|aarch64) ASSET_NAME="n8n-cli-${OS}-arm64" ;;
    x86_64)        ASSET_NAME="n8n-cli-${OS}-x64" ;;
    *)             echo "지원하지 않는 아키텍처: $ARCH"; exit 1 ;;
  esac

  # 바이너리 다운로드
  gh release download "$LATEST_TAG" --repo ubie-oss/n8n-cli --pattern "$ASSET_NAME" --output n8n-cli --clobber
  chmod +x ./n8n-cli
  echo "업데이트 완료: $(./n8n-cli version 2>/dev/null | head -1)"
else
  echo "n8n-cli가 최신 상태입니다: $CURRENT_VERSION"
fi

대체 방법: 소스에서 빌드

gh CLI를 사용할 수 없거나 개발 빌드가 필요한 경우:

# 의존성 설치 + CLI 빌드
bun install && make build

빌드 확인:

./n8n-cli version

환경 설정

.env 파일 확인

프로젝트 루트에 .env가 존재하면 n8n-cli를 매개변수 없이 사용할 수 있습니다. 파일 내용을 읽지 마세요.

# .env 존재 여부만 확인 (내용 읽지 않음)
test -f .env && echo ".env exists - n8n-cli can be used without parameters"

.env가 존재하는 경우:

• N8N_API_URL 및 N8N_API_KEY가 이미 설정되어 있음
• ./n8n-cli를 매개변수 없이 실행 가능

.env가 존재하지 않는 경우:

• 사용자에게 .env 파일 생성을 요청
• 또는 --api-url 및 --api-key 플래그 사용

.env 생성 (필요한 경우에만)

cp .env.example .env
# 사용자에게 편집 요청

일반 명령어

1. 원격 워크플로우 상태 확인

특정 워크플로우 확인:

# ID로 워크플로우 정보 가져오기
./n8n-cli workflow get <workflow-id>

# 표 형식으로 표시 (가독성 향상)
./n8n-cli -o table workflow get <workflow-id>

# 파일로 저장 (diff 비교에 유용)
./n8n-cli workflow get <workflow-id> > /tmp/remote-workflow.json

워크플로우 목록:

# 모든 워크플로우
./n8n-cli workflow list

# 표 형식
./n8n-cli -o table workflow list

# 활성 워크플로우만
./n8n-cli workflow list --active

2. 워크플로우 가져오기 (원격 -> 로컬)

가져오기 전 로컬 형식 확인

원격 콘텐츠를 로컬로 가져올 때는 다음 단계를 항상 따르세요.

1. 로컬 파일 형식 확인

   # 파일 존재 여부 및 형식 확인
   ls -la definitions/*<workflow-id>* definitions/**/*<workflow-id>*
   

2. 형식에 따라 적절한 가져오기 옵션 사용

   • .json 파일: --ids만 사용
   • .yaml/.yml 파일: --ids와 --yaml 모두 사용

특정 워크플로우 가져오기:

# JSON 형식 워크플로우
./n8n-cli import --ids=<workflow-id>

# YAML 형식 워크플로우
./n8n-cli import --ids=<workflow-id> --yaml

# 사용자 지정 디렉토리로
./n8n-cli import --ids=<workflow-id> -d ./my-dir

여러 워크플로우 가져오기:

# 쉼표로 구분된 목록
./n8n-cli import --ids=abc123,def456,ghi789

모든 워크플로우 가져오기:

./n8n-cli import

추가 옵션:

옵션	설명
--include-archived	보관된 워크플로우 포함
--cleanup-orphans	일치하는 ID가 없는 고아 파일 삭제
-t, --threshold <int>	외부 파일 추출을 위한 최소 줄 수 (기본값: 0, CLAUDE.md에서 설정 가능)
--dry-run	미리보기만 (파일 변경 없음)
--tags <tags>	쉼표로 구분된 태그 이름으로 필터링 (AND 조건)

3. 드라이 런 (변경 미리보기)

적용 전에 항상 드라이 런으로 확인하세요:

# 모든 워크플로우 변경 미리보기
./n8n-cli apply --dry-run

# 특정 워크플로우만 (ID 기준)
./n8n-cli apply --dry-run --ids=<workflow-id>

# 특정 파일만
./n8n-cli apply --dry-run -d definitions/path/to/workflow.json

출력 예시:

=== 생성 (1 워크플로우) ===
  + new-workflow.json (이름: "New Automation")

=== 업데이트 (2 워크플로우) ===
  ~ existing.json (ID: R2cTI0LDzCJSnvNG)
    - 이름: "Old Name" -> "New Name"
    - 노드: 3 -> 5개

=== 건너뜀 (1 워크플로우) ===
  = unchanged.json (변경 없음)

요약 (드라이 런): 생성 1개, 업데이트 2개, 변경 없음 1개

4. 적용 (배포)

AI 어시스턴트는 항상 --ids를 사용해야 합니다

# 특정 워크플로우만 적용 (권장)
./n8n-cli apply --ids=<workflow-id>

# 특정 파일만 적용
./n8n-cli apply -d definitions/path/to/workflow.json

# 강제 적용 (원격 변경 사항 덮어쓰기)
./n8n-cli apply --ids=<workflow-id> --force

금지: 전체 디렉토리 적용

# AI는 다음 명령을 실행해서는 안 됨
./n8n-cli apply -d definitions/
./n8n-cli apply

추가 옵션:

옵션	설명
--from-git-changes <spec>	Git diff에서 변경된 파일만 적용
--yaml / --no-yaml	YAML 처리 활성화/비활성화
--allow-duplicates	업스트림 중복 이름 검사 건너뛰기 (기본값: 켜짐; 경고를 무시하려면 --force 사용)
--no-auto-tag	자동 태깅 비활성화 (managed-as-code)
-p, --project <id>	대상 프로젝트 ID 지정

환경 변수:

• APPLY_FILTER_BY_TAGS - 쉼표로 구분된 태그 이름으로 필터링 (AND 조건)

Git diff 모드:

# 기능 브랜치의 변경 사항만 적용
./n8n-cli apply --from-git-changes origin/main..HEAD

# 미리보기
./n8n-cli apply --from-git-changes origin/main..HEAD --dry-run

# 마지막 3개 커밋의 변경 사항
./n8n-cli apply --from-git-changes HEAD~3..HEAD

3방향 충돌 감지: --from-git-changes가 지정되면 Base(기준점), Local(현재), Remote(서버)를 비교하여 실제 충돌만 식별합니다.

5. 린터 (품질 검사)

린터는 CLI에 통합되어 있습니다. 별도 빌드가 필요하지 않습니다.

참고: 위치 인자는 지원되지 않습니다. 항상 파일/디렉토리를 -f 또는 -d로 지정하세요.

# 특정 파일 확인 (-f 필수)
./n8n-cli lint -f definitions/<filename>

# 특정 디렉토리 확인
./n8n-cli lint -d ./definitions/example-project

# 모든 워크플로우 확인
./n8n-cli lint -d ./definitions

# JSON 출력 (CI/CD용)
./n8n-cli lint -d ./definitions -o json

옵션:

옵션	설명
-d, --dir <path>	정의 파일 디렉토리
-f, --file <files...>	특정 파일
-c, --config <path>	설정 파일 경로 (.n8nlintrc.json)
--disable-rule <name>	특정 규칙 비활성화
--list-rules	모든 규칙 나열
-o, --output <format>	출력 형식: text, json (기본값: text)

규칙 (11개):

규칙	심각도	설명
json-syntax	error	JSON 구문 검사
required-fields	error	필수 필드(이름, 노드, 연결) 검사
connection-reference	error	연결 대상 노드 존재 여부 검사
webhook-id-required	error	webhook 및 formTrigger 노드에 webhookId 필드가 있는지 검사
orphaned-node	warning	고립 노드 감지
implicit-json-ref	warning	암시적 $json 참조 감지
expression-mode-prefix	warning	= 접두사 누락 감지
ai-agent-output-ref	warning	AI Agent 출력 잘못된 참조 감지
node-params	warning	노드 매개변수 스키마 검증
node-ref-field-check	warning	참조된 필드 존재 여부 검증
node-ref-cardinality	warning	.item/.first() 사용 검증

설정 파일 (.n8nlintrc.json):

{
  "rules": {
    "json-syntax": "error",
    "required-fields": "error",
    "orphaned-node": "warning",
    "implicit-json-ref": "off"
  }
}

설정 파일 검색 순서:

1. --config 플래그로 지정된 경로
2. 대상 디렉토리의 .n8nlintrc.json / .n8nlintrc
3. 현재 디렉토리의 .n8nlintrc.json / .n8nlintrc

6. 포매터 (자동 서식)

참고: fmt는 파일에 대해 위치 인자를 사용합니다 (-f 옵션 없음).

# 특정 파일 서식 지정 (위치 인자)
./n8n-cli fmt definitions/<filename>

# 여러 파일
./n8n-cli fmt definitions/file1.yaml definitions/file2.yaml

# 전체 디렉토리 서식 지정
./n8n-cli fmt -d ./definitions

# 미리보기만
./n8n-cli fmt -d ./definitions --dry-run

7. 테스트 (실행)

테스트 웹훅을 통해 워크플로우 테스트:

# 기본 테스트
./n8n-cli test <workflow-id>

# 테스트 데이터 포함
./n8n-cli test <workflow-id> -d '{"email": "[email protected]"}'

# 실행 완료까지 대기 (권장)
./n8n-cli test <workflow-id> --wait-execution

# 비활성 워크플로우 자동 활성화
./n8n-cli test <workflow-id> --activate

# 웹훅 URL만 확인
./n8n-cli test <workflow-id> --dry-run

# 입력 매개변수 확인
./n8n-cli test <workflow-id> --show-inputs

옵션:

옵션	설명
-d, --data <json>	테스트 데이터 (JSON 문자열)
--timeout <duration>	HTTP 타임아웃 (기본값: 30초)
--wait-execution	실행 완료까지 대기하고 결과 표시
--activate	비활성 워크플로우 자동 활성화
--dry-run	웹훅 URL만 확인
--show-inputs	입력 매개변수 표시
-o, --output <fmt>	출력 형식: json, table (기본값: json)

로컬 파일에서 테스트:

# 로컬 JSON/YAML 파일 지정
./n8n-cli test ./definitions/my-workflow.json

8. 실행 (로그 및 오류)

최근 실행 목록:

# 모든 최근 실행 목록
./n8n-cli execution list

# 표 형식 (가독성 향상)
./n8n-cli -o table execution list

# 상태별 필터링
./n8n-cli execution list --status error
./n8n-cli execution list --status success

# 워크플로우별 필터링
./n8n-cli execution list --workflow <workflow-id>

# 결과 제한
./n8n-cli execution list --limit 5

# 결합 필터
./n8n-cli execution list --workflow <workflow-id> --status error --limit 10

실행 세부 정보 가져오기:

# ID로 실행 정보 가져오기
./n8n-cli execution get <execution-id>

# 오류 세부 정보가 포함된 표 형식
./n8n-cli -o table execution get <execution-id>

# 노드 실행 요약 포함
./n8n-cli -o table execution get <execution-id> --show-data

execution list 옵션:

옵션	설명
-w, --workflow <id>	워크플로우 ID로 필터링
-s, --status <status>	상태별 필터링 (success, error, running, waiting)
-l, --limit <n>	최대 실행 수 (기본값: 20)

execution get 옵션:

옵션	설명
--show-data	출력에 노드 실행 요약 포함

표시되는 오류 정보:

필드	설명
오류 노드	오류가 발생한 노드
오류 메시지	오류 메시지
오류 세부 정보	추가 오류 설명 (있는 경우)
마지막 노드	마지막으로 실행된 노드

일반적인 디버깅 워크플로우:

# 1. 최근 오류 나열
./n8n-cli -o table execution list --status error --limit 5

# 2. 특정 실패 실행의 세부 정보 가져오기
./n8n-cli -o table execution get <execution-id> --show-data

# 3. 오류 세부 정보 검토 및 워크플로우 수정

9. 변환 (형식 변환)

워크플로우 파일을 JSON과 YAML 형식 간 변환 (로컬 전용, API 필요 없음):

# 모든 JSON 워크플로우를 YAML로 변환
./n8n-cli convert -d ./definitions --format yaml

# ID로 특정 워크플로우 변환
./n8n-cli convert -d ./definitions --format json --ids <workflow-id>

# 쓰지 않고 미리보기
./n8n-cli convert -d ./definitions --format yaml --dry-run

# 원본 파일 유지
./n8n-cli convert -d ./definitions --format yaml --keep

# 단일 파일 변환
./n8n-cli convert --format yaml definitions/<filename>.json

옵션:

옵션	설명
--format <format>	대상 형식: json, yaml (필수)
-d, --directory <dir>	워크플로우 파일을 검색할 디렉토리
--ids <ids>	변환할 워크플로우 ID (쉼표 구분)
--tags <tags>	태그로 필터링 (쉼표 구분, AND 조건)
-t, --threshold <n>	코드 외부화를 위한 최소 줄 수 (JSON→YAML)
--dry-run	미리보기만
--keep	원본 파일 유지

동작:

• JSON→YAML: YAML + 외부화된 코드가 포함된 _subfiles/ 생성
• YAML→JSON: !include 참조 해결 및 _subfiles/ 제거
• 이미 대상 형식인 파일은 건너뜀
• --keep 옵션이 없으면 변환 후 원본 파일 제거

10. 데이터 테이블

데이터 테이블 및 행 관리:

# 모든 데이터 테이블 나열
./n8n-

…

[번역을 위해 잘림]