n8n CLI 시작하기
n8n v2.42요약
n8n CLI는 실행 중인 n8n 인스턴스와 n8n API를 통해 통신하는 경량 명령줄 클라이언트입니다. API CLI를 사용해 다음을 수행할 수 있습니다. 모든 작업은 사용자의 권한과 API 키의 범위를 따릅니다. 이 섹션의 상세 내용은 n8n 공식 문서를 참조하세요.
n8n CLI는 실행 중인 n8n 인스턴스와 n8n API를 통해 통신하는 경량 명령줄 클라이언트입니다. 네트워크에 접근할 수 있는 모든 머신에서 실행할 수 있으며 API 키로 인증합니다.
API CLI를 사용해 다음을 수행할 수 있습니다.
- 워크플로 목록 조회 및 확인
- JSON에서 워크플로 생성
- 최근 실행 확인
- 자격 증명 생성
- 프로젝트 관리
모든 작업은 사용자의 권한과 API 키의 범위를 따릅니다.
이 섹션의 상세 내용은 n8n 공식 문서를 참조하세요.
n8n CLI와 서버 CLI 비교#
n8n 인스턴스를 관리(백업, 라이선스 관리, 긴급 초기화)해야 하는 경우, n8n과 동일한 머신에서 실행되는 내장 도구인 서버 CLI를 참고하세요.
| 항목 | n8n CLI | 서버 CLI |
|---|---|---|
| 실행 위치 | 네트워크에 접근할 수 있는 모든 머신 | n8n과 동일한 머신 |
| 인증 | API 키 | 직접 데이터베이스 접근 |
| n8n 실행 필요 여부 | 예 | 아니요(대부분의 작업에서 필요하지 않음) |
| 적합한 대상 | 개발자, 통합, AI 에이전트 | 인스턴스 운영자, 백업, 긴급 상황 |
| 권한 | 사용자 역할 및 API 키 범위를 따름 | 접근 제어를 우회함 |
n8n-cli 설치#
# Use directly with npx (zero install)
npx @n8n/cli workflow list
# Or install globally
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 |
package (preview) |
export, import |
skill |
install |
audit |
(최상위) |
login / logout |
(최상위) |
출력 형식#
모든 명령어는 --format을 통해 세 가지 출력 형식을 지원합니다.
| 형식 | 플래그 | 사용 시점 |
|---|---|---|
| Table | --format=table(기본값) |
사람이 읽기 쉬운 터미널 출력을 원할 때 |
| JSON | --format=json |
jq로 파이핑하거나 프로그래밍 방식으로 사용할 때 |
| ID-only | --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>
패키지 내보내기 및 가져오기#
Preview 상태
package 명령어는 Preview 상태이며 이후 릴리즈에서 변경될 수 있습니다.
n8n-cli package export --workflow-id=<workflow-id> --output=export.n8np
n8n-cli package export --project-id=<project-id> --output=project.n8np
n8n-cli package import --file=export.n8np --workflow-conflict-policy=fail
n8n-cli package import --file=export.n8np --project-id=<project-id> --workflow-conflict-policy=skip
n8n-cli package import --file=export.n8np --project-id=<project-id> --data-table-schema-conflict-policy=overwrite-non-destructive
패키지 구성 요소는 n8n 패키지를, 사용 가능한 모든 플래그는 패키지 가져오기를 참고하세요.