n8n CLI 시작하기
n8n v2.25요약
n8n CLI는 실행 중인 n8n 인스턴스와 n8n API를 통해 통신하는 경량 명령줄 클라이언트입니다. 실험적 사용, 로컬 개발, 개인 프로젝트에만 사용하고 프로덕션 워크플로에는 사용하지 마세요. API CLI를 다음 용도로 사용할 수 있습니다:
n8n CLI는 실행 중인 n8n 인스턴스와 n8n API를 통해 통신하는 경량 명령줄 클라이언트입니다. 네트워크 접근이 가능한 모든 장치에서 실행할 수 있으며, API 키를 사용하여 인증합니다.
n8n CLI는 베타 버전입니다
실험적 사용, 로컬 개발, 개인 프로젝트에만 사용하고 프로덕션 워크플로에는 사용하지 마세요.
API CLI를 다음 용도로 사용할 수 있습니다:
- 워크플로 목록 조회 및 검사
- JSON으로 워크플로 생성
- 최근 실행 내역 확인
- 자격 증명 생성
- 프로젝트 관리
모든 작업은 사용자의 권한과 API 키 범위를 준수합니다.
n8n CLI vs 서버 CLI#
n8n 인스턴스를 관리해야 하는 경우(백업, 라이선스 관리, 긴급 초기화 등), n8n과 동일한 장치에서 실행되는 내장 도구인 서버 CLI를 참조하세요.
| 항목 | n8n CLI | 서버 CLI |
|---|---|---|
| 실행 위치 | 네트워크 접근이 가능한 모든 장치 | n8n과 동일한 장치 |
| 인증 | API 키 | 직접 데이터베이스(DB) 접근 |
| n8n 실행 필요 여부 | 예 | 아니오 (대부분의 작업에서 불필요) |
| 최적 사용 대상 | 개발자, 연동, AI 에이전트 | 인스턴스 운영자, 백업, 긴급 상황 |
| 권한 | 사용자 역할 및 API 키 범위 준수 | 접근 제어 우회 |
n8n-cli 설치#
# npx로 바로 사용 (설치 불필요)
npx @n8n/cli workflow list
# 또는 전역 설치
npm install -g @n8n/cli
인스턴스에 연결하기#
n8n-cli config set-url https://your-instance.n8n.cloud
n8n-cli config set-api-key YOUR_API_KEY
n8n-cli config show
- 구성 정보는 제한된 파일 권한(
0600)으로~/.n8n-cli/config.json에 저장됩니다. - n8n > Settings > n8n API에서 API 키를 발급받으세요.
또는 구성 파일 대신 환경 변수를 사용할 수 있습니다:
export N8N_URL=https://your-instance.n8n.cloud
export N8N_API_KEY=your_api_key
인라인 플래그#
n8n-cli --url=https://my-n8n.app.n8n.cloud --api-key=n8n_api_xxxxx workflow list
적용 우선순위#
- 명령줄 플래그 (
--url,--api-key) - 환경 변수 (
N8N_URL,N8N_API_KEY) - 구성 파일 (
~/.n8n-cli/config.json)
명령어#
모든 명령어는 자세한 사용법을 위해 --help를 지원합니다.
| 주제 | 명령어 |
|---|---|
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 |
(최상위) |
출력 형식#
모든 명령어는 --format을 통해 세 가지 출력 형식을 지원합니다:
| 형식 | 플래그 | 사용 시기 |
|---|---|---|
| 테이블 | --format=table` (기본값) |
사람이 읽기 쉬운 터미널 출력이 필요할 때 |
| JSON | --format=json |
jq로 파이핑하거나 프로그래밍 방식으로 사용할 때 |
| ID만 출력 | --format=id-only |
xargs로 파이핑하거나 스크립팅할 때 |
예시#
-
사람이 읽기 쉬운 테이블
n8n-cli workflow list -
스크립트용 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 {}
Claude Code에서 스킬로 사용하기#
Claude가 항상 n8n-cli 사용 방법을 알 수 있도록 스킬을 설치합니다:
n8n-cli skill install --global
그런 다음 Claude Code에서 /n8n-cli를 입력하여 스킬을 로드합니다. 이제 Claude는 MCP 없이도 워크플로를 생성, 업데이트, 관리할 수 있습니다.
예시#
워크플로 목록 조회 및 검사#
n8n-cli workflow list
n8n-cli workflow get <id>
JSON으로 워크플로 생성#
cat workflow.json | n8n-cli workflow create --stdin
최근 실행 내역 확인#
n8n-cli execution list --status=error --limit=10
자격 증명 생성#
n8n-cli credential schema gmailOAuth2 # see required fields first
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>