n8n CLI 시작하기
n8n v2.29n8n CLI는 실행 중인 n8n 인스턴스와 n8n API를 통해 통신하는 경량 명령줄 클라이언트입니다. 프로덕션 워크플로가 아닌 실험, 로컬 개발, 개인 프로젝트 용도로만 사용하세요. API CLI를 사용해 다음을 수행할 수 있습니다.
n8n CLI는 실행 중인 n8n 인스턴스와 n8n API를 통해 통신하는 경량 명령줄 클라이언트입니다. 네트워크에 접근할 수 있는 모든 머신에서 실행할 수 있으며 API 키로 인증합니다.
n8n CLI는 베타 버전입니다
프로덕션 워크플로가 아닌 실험, 로컬 개발, 개인 프로젝트 용도로만 사용하세요.
API CLI를 사용해 다음을 수행할 수 있습니다.
- 워크플로 목록 조회 및 확인
- JSON에서 워크플로 생성
- 최근 실행 확인
- 자격 증명 생성
- 프로젝트 관리
모든 작업은 사용자의 권한과 API 키의 범위를 따릅니다.
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 (베타) |
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>
패키지 내보내기 및 가져오기#
베타
package 명령어는 아직 베타 버전입니다. 호환성이 깨지는 변경이 발생할 수 있습니다.
n8n-cli package export --workflow-id=<workflow-id> --output=export.n8np
n8n-cli package import --file=export.n8np --conflict-policy=fail
n8n-cli package import --file=export.n8np --project=<project-id> --workflow-id-policy=source --conflict-policy=skip
사용 가능한 플래그와 패키지 구성 요소에 대한 자세한 개요는 n8n 패키지를 참고하세요.