n8n CLI와 Source Control로 만드는 GitOps 기반 Workflow 자동화 운영

아래처럼 소개 → 시작 → 활용 → 응용 → 보안/운영 포인트 순서로 보면 이해가 가장 쉽습니다. 이 문서의 핵심은, n8n CLI가 실행 중인 n8n 인스턴스에 API key로 접속하는 가벼운 명령줄 도구라는 점입니다. 어떤 머신에서든 네트워크만 되면 사용할 수 있고, 문서상 beta이므로 실험·로컬 개발·개인 프로젝트용으로 쓰는 것을 권장합니다.

n8n CLI란 무엇인가

n8n CLI는 n8n의 API를 명령줄에서 다루는 도구입니다. 문서 기준으로 이 도구는 워크플로 목록 조회/상세 확인, JSON으로 워크플로 생성, 최근 실행 내역 확인, credential 생성, project 관리 같은 작업에 쓰입니다. 또한 이 CLI는 사용자 권한과 API key 스코프를 존중합니다. 반대로, 같은 문서에서 서버 CLI는 백업·라이선스 관리·비상 리셋처럼 인스턴스 운영자용 작업을 위해 설계된 별도 도구라고 구분합니다.

즉, 실무 관점에서 보면 n8n CLI는 “n8n을 원격에서 자동화/관리하는 운영용 클라이언트”에 가깝고, 서버 CLI는 “n8n 서버 자체를 직접 만지는 관리자 도구”에 가깝습니다. n8n CLI는 n8n이 실행 중이어야 하며, 서버 CLI는 문서상 대부분의 작업에서 n8n이 실행 중일 필요가 없습니다.

언제 쓰면 좋은가

대표 용도는 다음입니다. 워크플로를 확인하고 수정, JSON 파일에서 워크플로 생성, 실행 실패 내역 점검, credential 생성, project 정리입니다. 특히 개발자, 자동화 통합, AI 에이전트가 n8n을 조작할 때 잘 맞습니다.

보안/운영 관점에서는, UI에서 일일이 클릭하는 대신 반복 작업을 스크립트로 묶어 표준화할 수 있다는 점이 큽니다. 예를 들어 특정 프로젝트의 워크플로를 일괄 점검하거나, 실패한 execution만 추려서 재시도/정리하는 작업을 자동화할 수 있습니다.

설치와 연결 방법

가장 간단한 시작은 npx로 바로 실행하는 방식입니다. 예시는 npx @n8n/cli workflow list입니다. 전역 설치도 가능하며, 예시는 npm install -g @n8n/cli입니다.

인스턴스 연결은 두 단계입니다. 먼저 URL을 넣고, 다음에 API key를 넣습니다.

n8n-cli config set-url https://your-instance.n8n.cloud
n8n-cli config set-api-key YOUR_API_KEY
n8n-cli config show

이 설정은 기본적으로 ~/.n8n-cli/config.json에 저장되고, 파일 권한은 0600으로 제한됩니다. API key는 n8n의 Settings > n8n API에서 받을 수 있습니다. 환경변수도 지원하며 예시는 N8N_URL, N8N_API_KEY입니다.

또한 명령행 플래그가 가장 우선이고, 그다음이 환경변수, 마지막이 설정 파일입니다. 즉 --url, --api-key를 주면 그 값이 최우선으로 적용됩니다.

주요 명령 체계

문서의 명령 구조는 크게 다음 토픽으로 나뉩니다.

workflow: list, get, create, update, delete, activate, deactivate, tags, transfer
execution: list, get, retry, stop, delete
credential: list, get, schema, create, delete, transfer
project: list, get, create, update, delete, members, add-member, remove-member
tag: list, create, update, delete
variable: list, create, update, delete
data-table: list, get, create, delete, rows, add-rows, update-rows, upsert-rows, delete-rows
user: list, get
config: set-url, set-api-key, show
source-control: pull
skill: install
audit
login / logout

이 구조를 보면, n8n CLI는 단순 조회 도구가 아니라 워크플로 생명주기 관리, 실행 관리, 자격 증명 관리, 프로젝트/테넌트 성격의 정리, 소스 제어 연동, 감사(audit) 까지 커버합니다. 즉 “n8n을 스크립트로 조작하는 콘솔”에 가깝습니다.

출력 형식과 자동화 친화성

모든 명령은 --format으로 출력 형식을 바꿀 수 있습니다. 문서상 지원 형식은 table(기본), json, id-only입니다. 사람이 보기엔 table, 스크립트 파이프라인에는 json, xargs 같은 조합에는 id-only가 적합합니다.

300x250

실전에서는 이 차이가 꽤 중요합니다.

# 사람이 보기 좋은 목록
n8n-cli workflow list

# jq로 필터링하기 좋은 JSON
n8n-cli workflow list --format=json | jq '.[] | select(.active) | .id'

# ID만 뽑아 다른 명령으로 넘기기
n8n-cli workflow list --format=id-only | xargs -I{} n8n-cli workflow deactivate {}

이런 패턴 덕분에 n8n CLI는 배치 자동화, 감사 점검, 표준 운영 스크립트에 잘 맞습니다.

바로 써볼 수 있는 활용 예시

문서 예시 중 가장 실용적인 것은 다음입니다.

n8n-cli workflow list
n8n-cli workflow get <id>
cat workflow.json | n8n-cli workflow create --stdin
n8n-cli execution list --status=error --limit=10
n8n-cli credential schema gmailOAuth2
n8n-cli credential create --type=gmailOAuth2 --name='My Gmail' --file=cred.json
n8n-cli project create --name="My Project"
n8n-cli workflow transfer <id> --project=<projectId>

각 명령의 의미를 풀어보면, workflow list/get은 자산 점검, workflow create --stdin은 Git 저장소나 생성 스크립트와 연결, execution list --status=error는 장애 추적, credential schema는 필요한 입력값 사전 확인, project create/transfer는 워크플로 운영구조 정리에 해당합니다.

응용 시나리오

배포 전 점검 자동화

Git으로 관리하는 workflow.json을 CLI로 올리고, 바로 workflow list와 execution list --status=error를 함께 확인하면, 배포 직후의 이상 징후를 빠르게 볼 수 있습니다. 문서가 제공하는 create --stdin, execution list, --format=json 조합이 이 용도에 잘 맞습니다.

운영 헬스 체크

정기적으로 workflow list --format=json를 돌려 활성 워크플로를 확인하고, execution list --status=error --limit=10로 최근 실패만 모니터링하면 됩니다. 이 방식은 대시보드 확인보다 훨씬 가볍고, 파이프라인에 넣기 쉽습니다.

credential 준비 상태 검증

credential을 만들기 전에 credential schema <type>으로 먼저 필수 필드를 확인할 수 있습니다. 예시로는 gmailOAuth2가 나오며, 이 흐름은 “먼저 스키마 확인 → 그다음 JSON 파일로 생성” 순서로 운영하기 좋습니다.

프로젝트 단위 분리 운영

project create, project members, workflow transfer를 조합하면 팀별/서비스별 워크플로를 묶어 운영하기 좋습니다. 멀티팀 환경에서는 워크플로가 섞이는 순간 관리가 급격히 어려워지므로, CLI로 프로젝트 경계를 유지하는 방식이 유용합니다.

Claude Code와의 연동

n8n-cli skill install --global 뒤에 Claude Code에서 /n8n-cli를 불러 쓰면, MCP 없이도 워크플로 생성·수정·관리를 맡길 수 있습니다. 즉, n8n CLI는 AI 코딩 에이전트와 결합하기 위한 브리지로도 설계되어 있습니다.

보안 관점에서 꼭 볼 점

API key 권한과 사용자 역할을 존중한다는 점은 장점이자 통제 포인트입니다. 즉, CLI를 발급할 때는 최소 권한 원칙으로 스코프를 제한하고, 불필요한 관리자 권한을 주지 않는 편이 좋습니다. 문서가 “permissions respect user roles and API key scopes”라고 명시합니다.

설정 파일이 ~/.n8n-cli/config.json에 저장되고 권한이 0600으로 제한된다는 점은 좋지만, 실제 운영에서는 여전히 공유 계정 사용 금지, 키 회전, CI/CD 비밀관리 연동이 필요합니다. 특히 --api-key를 셸 히스토리에 남기지 않도록 주의하는 편이 좋습니다.

실무에서의 추천 사용 순서

가장 무난한 흐름은 다음입니다.

npx @n8n/cli workflow list로 즉시 동작 확인
config set-url, config set-api-key로 연결 고정
workflow list/get, execution list, credential schema를 점검용으로 사용
JSON 기반 생성/변경은 Git과 묶어서 자동화
운영 반영 전에는 beta 한계를 감안해 테스트 환경에서 검증

n8n CLI 실무에서 자주 쓰는 명령 20선

아래 내용은 단순 명령 나열이 아니라, 실제 운영/개발/보안 관점에서 “왜 쓰는지”, “언제 유용한지”, “무엇을 주의해야 하는지”까지 포함해 정리했습니다.

현재 연결 상태 확인

n8n-cli config show

활용

현재 연결된 n8n URL 확인
API Key 설정 여부 확인
CI/CD 환경 디버깅

운영 포인트

운영 서버와 개발 서버가 섞이면 위험합니다.

dev에 넣어야 할 workflow를 prod에 등록
운영 credential 삭제 사고

따라서 아래처럼 환경별 alias 사용을 권장합니다.

alias n8n-dev='N8N_URL=https://dev-n8n.example.com n8n-cli'
alias n8n-prod='N8N_URL=https://prod-n8n.example.com n8n-cli'

전체 Workflow 목록 조회

n8n-cli workflow list

활용

현재 운영 중인 workflow 자산 점검
활성/비활성 workflow 확인
정리 대상 workflow 파악

JSON 출력 활용

n8n-cli workflow list --format=json

응용

jq와 함께 사용

n8n-cli workflow list --format=json | jq .

활성 Workflow만 조회

n8n-cli workflow list --format=json | jq '.[] | select(.active==true)'

활용

실제 동작 중인 workflow만 확인
운영 대상만 필터링
불필요 workflow 제거 후보 확인

보안 포인트

비활성화된 오래된 workflow에도

API key
credential
webhook
DB 연결정보

가 남아있을 수 있습니다.

즉 “안 쓰는 workflow”도 공격 표면입니다.

특정 Workflow 상세 확인

n8n-cli workflow get 123

활용

workflow 구조 확인
node 연결 검토
webhook endpoint 확인

실무 팁

JSON 저장

n8n-cli workflow get 123 > workflow.json

Git 관리 가능

변경 추적
코드 리뷰
백업
복구

Workflow 백업

n8n-cli workflow get 123 > backup-workflow.json

활용

배포 전 백업
장애 복구
Git 버전관리

Workflow 생성 (JSON 기반)

cat workflow.json | n8n-cli workflow create --stdin

활용

IaC 스타일 운영
GitOps
템플릿 배포

중요 개념

UI 기반 운영

사람이 클릭
변경 추적 어려움

CLI 기반 운영

선언형 관리
자동화 가능
변경 이력 관리 가능

Workflow 비활성화

n8n-cli workflow deactivate 123

활용

장애 workflow 긴급 차단
악성 webhook 차단
테스트 workflow 정리

보안 활용

보안 사고 발생 시

webhook 악용
API loop
무한 execution

발생 workflow를 즉시 차단 가능

Workflow 활성화

n8n-cli workflow activate 123

활용

배포 후 활성화
점검 종료 후 재오픈

최근 실패 Execution 조회

n8n-cli execution list --status=error --limit=10

활용

장애 확인
실패 workflow 탐지
자동 헬스체크

운영 자동화 예시

#!/bin/bash

ERRORS=$(n8n-cli execution list --status=error --limit=5 --format=json)

if [ "$ERRORS" != "[]" ]; then
    echo "n8n execution error detected"
fi

특정 Execution 상세 확인

n8n-cli execution get 999

활용

어떤 node에서 실패했는지 확인
payload 분석
API 응답 오류 확인

보안 포인트

execution 데이터에는

토큰
이메일
개인정보
API 응답

이 남을 수 있습니다.

retention 정책
접근권한
masking

검토 필요

실패 Execution 재시도

n8n-cli execution retry 999

활용

일시 장애 재처리
API timeout 복구
queue 장애 복구

주의

중복 실행 가능성 존재

중복 메일
중복 결제
중복 티켓 생성

따라서

idempotency 설계
중복 체크 로직

필수

Execution 중지

n8n-cli execution stop 999

활용

무한 loop 차단
대량 API 호출 차단
runaway workflow 종료

매우 중요

실무에서 종종

recursive webhook
while loop 오류
queue 폭주

가 발생합니다.

CLI stop은 긴급 대응 수단입니다.

Credential 타입 스키마 확인

n8n-cli credential schema gmailOAuth2

활용

필요한 입력 필드 확인
자동 생성 스크립트 작성
credential 템플릿 생성

Credential 생성

n8n-cli credential create \
  --type=gmailOAuth2 \
  --name="My Gmail" \
  --file=cred.json

활용

자동 credential provisioning
대량 환경 구축
IaC 운영

보안 관점

credential JSON 관리 시

Git 저장 금지
Vault 연동 권장
암호화 저장 필요

Credential 목록 확인

n8n-cli credential list

활용

사용 중 credential 점검
오래된 credential 제거
계정 정리

보안 점검 포인트

확인 항목

퇴사자 계정 사용 여부
오래된 OAuth token
테스트 계정 존재 여부
과도한 관리자 권한 여부

Project 생성

n8n-cli project create --name="Security Team"

활용

팀 단위 분리

보안팀
개발팀
운영팀

장점

권한 분리
workflow 격리
credential 분리

Workflow 프로젝트 이동

n8n-cli workflow transfer 123 --project=456

활용

조직 개편
운영 이관
프로젝트 분리

Variable 관리

n8n-cli variable list

활용

공통 변수 관리

API endpoint
공통 URL
feature flag

Tag 관리

n8n-cli tag list

효과

운영 가시성 증가

Source Control Pull

n8n-cli source-control pull

활용

Git 기반 workflow 동기화

DevOps 관점

이 기능은 사실상

GitOps
CI/CD
IaC

흐름으로 연결됩니다.

실무 추천 운영 구조

Git Repository
    ↓
Workflow JSON
    ↓
CI/CD Pipeline
    ↓
n8n CLI
    ↓
n8n Instance

보안 관점 핵심 체크포인트

API Key 관리

최소권한
주기적 rotation
Vault 저장
CI secret 관리

Execution 데이터 보안

Execution에는 민감정보가 남습니다.

retention 기간
로그 마스킹
접근권한
외부 저장 여부

Credential 감사

미사용 credential 제거
OAuth scope 검토
관리자 계정 사용 금지

Workflow 코드 리뷰

외부 전송
webhook 공개
shell command 실행
code node 악용
SSRF 가능성
internal API 접근

운영 성숙도 관점

n8n CLI는 단순 CLI가 아닙니다.

실제로는

GitOps
IaC
Workflow CI/CD
보안 감사
자동 운영
AI Agent 연계

까지 연결되는 핵심 도구입니다.

특히 앞으로

Claude Code
MCP
AI Agent
Git 기반 운영

흐름과 매우 강하게 연결될 가능성이 큽니다.

728x90

그리드형(광고전용)

저작자표시 비영리 동일조건 (새창열림)

n8n CLI와 Source Control로 만드는 GitOps 기반 Workflow 자동화 운영

n8n CLI와 Source Control로 만드는 GitOps 기반 Workflow 자동화 운영

n8n CLI란 무엇인가

언제 쓰면 좋은가

설치와 연결 방법

주요 명령 체계

출력 형식과 자동화 친화성

바로 써볼 수 있는 활용 예시

응용 시나리오

배포 전 점검 자동화

운영 헬스 체크

credential 준비 상태 검증

프로젝트 단위 분리 운영

Claude Code와의 연동

보안 관점에서 꼭 볼 점

실무에서의 추천 사용 순서

n8n CLI 실무에서 자주 쓰는 명령 20선

현재 연결 상태 확인

활용

운영 포인트

전체 Workflow 목록 조회

활용

JSON 출력 활용

응용

활성 Workflow만 조회

활용

보안 포인트

특정 Workflow 상세 확인

활용

실무 팁

Workflow 백업

활용

추천 운영 방식

Workflow 생성 (JSON 기반)

활용

중요 개념

Workflow 비활성화

활용

보안 활용

Workflow 활성화

활용

추천 전략

최근 실패 Execution 조회

활용

운영 자동화 예시

특정 Execution 상세 확인

활용

보안 포인트

실패 Execution 재시도

활용

주의

Execution 중지

활용

매우 중요

Credential 타입 스키마 확인

활용

Credential 생성

활용

보안 관점

Credential 목록 확인

활용

보안 점검 포인트

Project 생성

활용

장점

Workflow 프로젝트 이동

활용

Variable 관리

활용

Tag 관리

추천 태그 전략

효과

Source Control Pull

활용

DevOps 관점

실무 추천 운영 구조

추천 자동화 시나리오

1. 장애 탐지 자동화

2. Workflow 백업 자동화

3. 보안 감사 자동화