n8n 명령줄 사용

n8n 명령줄 사용 (Use the command line)

n8n에 내장된 명령줄 인터페이스인 Server CLI에서 사용할 수 있는 명령을 정리합니다. Server CLI는 n8n 설치와 같은 머신에서 실행되며, 관리 작업을 위한 데이터베이스 직접 접근을 제공하고 n8n이 실행 중이 아니어도 대부분의 명령을 실행할 수 있어요.

출처: 공식문서 - Use the command line

💡 n8n CLI와의 차이: 원격 머신에서 n8n을 프로그래밍 방식으로 다루거나 AI 에이전트와 통합하고 싶다면 n8n CLI를 확인하세요.

Server CLI vs n8n CLI

기능	Server CLI	n8n CLI
실행 위치	n8n과 같은 머신	네트워크 접근이 가능한 모든 머신
인증	데이터베이스 직접 접근	API 키
n8n 실행 필요 여부	아니요 (대부분의 명령)	예
적합한 대상	인스턴스 운영자, 백업, 마이그레이션	프로그래머, AI 에이전트, 원격 관리
보안 모델	접근 제어를 우회	사용자 권한과 API 키 범위 존중
사용 예시	백업/복원, 라이선스 관리, 비상 비밀번호 재설정	워크플로 자동화, 코드를 통한 크레덴셜 관리

CLI 명령 실행하기

셀프호스팅 n8n에서 CLI 명령을 사용할 수 있어요. n8n 설치 방법에 따라 명령 실행 방식이 조금 다릅니다.

npm: n8n 명령을 바로 사용할 수 있습니다. 아래 예시는 이 방식을 사용합니다.
Docker: n8n 명령은 Docker 컨테이너 안에서 사용 가능합니다.
```
docker exec -u node -it <n8n-container-name> <n8n-cli-command>
```

워크플로 시작

CLI로 워크플로를 직접 시작할 수 있어요. 저장된 워크플로를 ID로 실행합니다.

n8n execute --id <ID>

워크플로 발행/발행 취소

CLI로 워크플로를 발행(publish)하거나 발행 취소(unpublish)할 수 있습니다. n8n 2.0에서 이전의 active/inactive 토글이 발행/발행 취소 모델로 바뀌었어요. publish:workflow와 unpublish:workflow를 사용합니다.

💡 재시작 필요: 이 명령들은 n8n 데이터베이스에 작동합니다. n8n이 실행 중일 때 실행하면 변경 사항이 n8n을 재시작할 때까지 적용되지 않습니다.

워크플로 발행

publish:workflow로 ID 기반 워크플로를 발행합니다. 필요하면 versionId를 넘겨 특정 과거 버전을 발행할 수 있어요.

명령 플래그:

Flag	설명
--help	도움말 프롬프트.
--id	발행할 워크플로의 ID. 필수.
--versionId	발행할 버전 ID(선택). 생략하면 현재 초안이 발행됩니다.

💡 --all 플래그 없음: 폐기된 update:workflow 명령과 달리 publish:workflow는 --all을 지원하지 않습니다. 프로덕션 환경에서 워크플로가 실수로 일괄 발행되는 것을 막기 위한 의도입니다. 워크플로는 ID로 하나씩 발행하세요.

ID로 현재 초안 발행:

n8n publish:workflow --id=<ID>

특정 과거 버전 발행:

n8n publish:workflow --id=<ID> --versionId=<VERSION_ID>

워크플로 발행 취소

unpublish:workflow로 ID 기반 워크플로 또는 모든 워크플로를 한 번에 발행 취소합니다.

명령 플래그:

Flag	설명
--help	도움말 프롬프트.
--id	발행 취소할 워크플로의 ID. `--all`과 함께 사용할 수 없음.
--all	모든 워크플로 발행 취소. `--id`와 함께 사용할 수 없음.

ID로 발행 취소:

n8n unpublish:workflow --id=<ID>

모든 워크플로 발행 취소:

n8n unpublish:workflow --all

update:workflow (폐기됨)

⚠️ 기능 가용성: update:workflow 명령은 n8n 2.0부터 폐기되어 제거될 예정입니다. publish:workflow와 unpublish:workflow를 대신 사용하세요. 자세한 내용은 n8n 2.0 breaking changes를 참고하세요.

n8n update:workflow --id=<ID> --active=false
n8n update:workflow --id=<ID> --active=true
n8n update:workflow --all --active=false
n8n update:workflow --all --active=true

엔티티 내보내기

CLI로 n8n 데이터베이스 엔티티를 내보낼 수 있어요. 예를 들어 SQLite에서 내보내 Postgres로 가져오는 식으로, 한 데이터베이스 종류에서 다른 종류로 모든 엔티티 타입을 옮길 수 있습니다.

명령 플래그:

Flag	설명
--help	도움말 프롬프트.
--outputDir	출력 디렉터리 경로
--includeExecutionHistoryDataTables	실행 기록 데이터 테이블 포함. 기본적으로 제외됨(매우 클 수 있음)

n8n export:entities --outputDir=./outputs --includeExecutionHistoryDataTables=true

워크플로와 크레덴셜 내보내기

CLI로 워크플로와 크레덴셜을 내보낼 수 있습니다.

명령 플래그:

Flag	설명
--help	도움말 프롬프트.
--all	모든 워크플로/크레덴셜 내보내기.
--backup	백업용으로 `--all --pretty --separate`를 설정합니다. 선택적으로 `--output`을 설정할 수 있습니다.
--id	내보낼 워크플로의 ID.
--output, -o	출력 파일 이름 또는 separate 파일을 쓸 때 디렉터리.
--pretty	더 읽기 쉬운 형식으로 출력.
--separate	워크플로당 하나의 파일로 내보내기(버저닝에 유용). `--output`으로 디렉터리를 반드시 지정.
--decrypted	크레덴셜을 평문 형식으로 내보내기. (크레덴셜만)
--version	내보낼 특정 과거 버전의 버전 ID. (워크플로만, `--all`이나 `--published`와 함께 사용 불가)
--published	현재 초안 대신 발행/활성 버전 내보내기. `--all`과 함께 쓰면 발행되지 않은 워크플로는 건너뜁니다. (워크플로만, `--version`과 함께 사용 불가)

워크플로

모든 워크플로를 표준 출력(터미널)으로 내보내기:

n8n export:workflow --all

ID로 내보내고 출력 파일 이름 지정:

n8n export:workflow --id=<ID> --output=file.json

특정 디렉터리에 단일 파일로 모두 내보내기:

n8n export:workflow --all --output=backups/latest/file.json

--backup 플래그로 특정 디렉터리에 모두 내보내기:

n8n export:workflow --backup --output=backups/latest/

특정 워크플로 버전 내보내기

--version으로 versionId를 넘겨 특정 과거 버전을 내보낼 수 있습니다.

n8n export:workflow --id=<ID> --version=<VERSION_ID> --output=workflow-v1.json

발행된 워크플로 버전 내보내기

--published로 현재 초안 대신 현재 발행/활성 버전을 내보냅니다.

n8n export:workflow --id=<ID> --published --output=published.json

--published와 --all을 결합하면 모든 워크플로의 발행 버전을 내보낼 수 있습니다. 발행 버전이 없는 워크플로는 건너뜁니다.

n8n export:workflow --all --published --output=workflows.json

💡 버전 메타데이터: 워크플로 내보내기 시 n8n은 해당 버전의 과거 이름과 설명을 담은 versionMetadata 속성을 포함합니다. 가져오기 명령은 이 데이터를 가져올 때 워크플로 히스토리 테이블에 보존합니다. 현재 워크플로의 이름과 설명은 덮어쓰지 않습니다.

크레덴셜

모든 크레덴셜을 표준 출력(터미널)으로 내보내기:

n8n export:credentials --all

ID로 내보내고 출력 파일 이름 지정:

n8n export:credentials --id=<ID> --output=file.json

특정 디렉터리에 단일 파일로 모두 내보내기:

n8n export:credentials --all --output=backups/latest/file.json

--backup 플래그로 특정 디렉터리에 모두 내보내기:

n8n export:credentials --backup --output=backups/latest/

모든 크레덴셜을 평문 형식으로 내보내기. 설정 파일의 시크릿 키가 다른 설치로 마이그레이션할 때 사용할 수 있습니다.

⚠️ 민감 정보: 모든 민감 정보가 파일에 노출됩니다.

n8n export:credentials --all --decrypted --output=backups/decrypted.json

엔티티 가져오기

이전 export:entities 명령의 결과를 이 명령으로 가져올 수 있습니다. 내보낸 데이터베이스 종류와 다른 종류로 가져올 수 있으며, 현재 지원되는 데이터베이스 종류는 SQLite, Postgres입니다.

가져오기 전에 데이터베이스가 비어 있어야 하며, --truncateTables 파라미터로 강제할 수 있습니다.

명령 플래그:

Flag	설명
--help	도움말 프롬프트.
--inputDir	가져올 출력 파일이 들어 있는 입력 디렉터리
--truncateTables	가져오기 전에 테이블 비우기

n8n import:entities --inputDir ./outputs --truncateTables true

워크플로와 크레덴셜 가져오기

CLI로 워크플로와 크레덴셜을 가져올 수 있습니다.

⚠️ ID 업데이트: 워크플로와 크레덴셜을 내보낼 때 n8n은 그 ID도 함께 내보냅니다. 기존 데이터베이스에 같은 ID의 워크플로와 크레덴셜이 있다면 덮어써집니다. 이를 피하려면 가져오기 전에 ID를 삭제하거나 변경하세요.

플래그:

Flag	설명
--help	도움말 프롬프트.
--input	입력 파일 이름 또는 `--separate`를 쓸 때 디렉터리.
--projectId	워크플로/크레덴셜을 지정 프로젝트로 가져오기. `--userId`와 함께 사용 불가.
--separate	`--input`이 주는 디렉터리에서 `*.json` 파일 가져오기.
--userId	워크플로/크레덴셜을 지정 사용자로 가져오기. `--projectId`와 함께 사용 불가.
--skipMigrationChecks	마이그레이션 검증 체크 건너뛰기.
--activeState	가져오는 워크플로의 활성 상태 제어. `false`(기본값, 모든 가져온 워크플로 비활성화) 또는 `fromJson`(각 워크플로 JSON의 `active` 필드 사용, 멀티-메인 모드만)

💡 SQLite로의 마이그레이션: n8n은 워크플로와 크레덴셜 이름을 128자로 제한하지만 SQLite는 크기 제한을 강제하지 않습니다. 이 때문에 가져오기 중 Data too long for column name 같은 오류가 발생할 수 있습니다. 이 경우 n8n 인터페이스에서 이름을 고치고 다시 내보내거나, 가져오기 전에 JSON 파일을 직접 편집하세요.

워크플로

⚠️ 알려진 문제: 가져온 후 cron 트리거가 계속 실행됨: 이전에 활성 상태였던 워크플로를 가져올 때의 동작은 실행 모드에 따라 다르며 알려진 버그입니다. 멀티-메인과 queue 모드 인스턴스에서는 이전에 활성 상태였던 워크플로의 cron 트리거가 가져올 때 비활성화됩니다. 멀티-메인이 아닌 인스턴스에서는 이전에 활성 상태였던 워크플로의 cron 트리거가 n8n 인스턴스를 재시작할 때까지 계속 실행됩니다.

특정 파일에서 워크플로 가져오기:

n8n import:workflow --input=file.json

지정 디렉터리의 모든 워크플로 파일을 JSON으로 가져오기:

n8n import:workflow --separate --input=backups/latest/

💡 가져올 때 버전 메타데이터: 가져온 파일에 versionMetadata 속성(특정 버전이나 발행 버전을 대상으로 하는 내보내기가 추가)이 포함되어 있으면 n8n은 그 과거 이름과 설명을 워크플로 히스토리 테이블에 보존합니다. 현재 워크플로 엔티티의 이름과 설명은 그대로 유지됩니다.

기본적으로 import:workflow는 모든 가져온 워크플로를 비활성화합니다. 대신 각 JSON 파일의 active 필드를 보존하려면 --activeState=fromJson을 넘기세요(멀티-메인 & queue 모드에서만 지원):

n8n import:workflow --separate --input=backups/latest/ --activeState=fromJson

크레덴셜

특정 파일에서 크레덴셜 가져오기:

n8n import:credentials --input=file.json

지정 디렉터리의 모든 크레덴셜 파일을 JSON으로 가져오기:

n8n import:credentials --separate --input=backups/latest/

라이선스

지우기

n8n의 데이터베이스에서 기존 라이선스를 지우고 n8n을 기본 기능으로 리셋합니다.

n8n license:clear

라이선스에 플로팅 엔타이틀먼트[^1]가 포함되어 있다면 이 명령 실행 시 이를 풀로 반환하려 시도하며, 다른 인스턴스에서 사용 가능하게 만듭니다.

정보

기존 라이선스에 대한 정보를 표시합니다.

n8n license:info

사용자 관리

n8n CLI로 사용자 관리를 리셋할 수 있습니다. 이는 사용자 관리를 설정 전 상태로 되돌리며 모든 사용자 계정을 제거합니다.

비밀번호를 잊었는데 이메일로 비밀번호 재설정을 할 수 있는 SMTP를 설정하지 않았을 때 사용하세요.

n8n user-management:reset

사용자의 MFA 비활성화

사용자가 복구 코드를 잃어버렸다면 이 명령으로 해당 사용자의 MFA를 비활성화할 수 있습니다. 그러면 사용자는 다시 로그인해 MFA를 다시 설정할 수 있어요.

n8n mfa:disable [email protected]

LDAP 비활성화

아래 명령으로 LDAP 설정을 리셋할 수 있습니다.

n8n ldap:reset

커뮤니티 노드와 크레덴셜 제거

n8n CLI로 커뮤니티 노드를 관리할 수 있습니다. 현재는 커뮤니티 노드와 크레덴셜만 제거할 수 있는데, 커뮤니티 노드가 불안정을 일으킬 때 유용합니다.

명령 플래그:

Flag	설명
--help	CLI 도움말 표시.
--credential	크레덴셜 타입. 노드의 `<NODE>.credential.ts` 파일에서 `name` 값을 찾아 가져옵니다.
--package	커뮤니티 노드의 패키지 이름.
--uninstall	노드 제거.
--userId	크레덴셜을 소유한 사용자의 ID. 셀프호스팅에선 DB를 조회하고, 클라우드에선 API 키로 API를 조회합니다.

노드

패키지 이름으로 커뮤니티 노드 제거:

n8n community-node --uninstall --package <COMMUNITY_NODE_NAME>

예를 들어 Evolution API 커뮤니티 노드를 제거하려면:

n8n community-node --uninstall --package n8n-nodes-evolution-api

크레덴셜

커뮤니티 노드 크레덴셜 제거:

n8n community-node --uninstall --credential <CREDENTIAL_TYPE> --userId <ID>

예를 들어 Evolution API 커뮤니티 노드 크레덴셜을 제거하려면, 저장소에서 credentials.ts 파일의 name을 찾으세요:

n8n community-node --uninstall --credential evolutionApi --userId 1234

보안 감사

n8n 인스턴스에서 보안 감사를 실행해 일반적인 보안 문제를 감지할 수 있습니다.

n8n audit

[^1]: n8n에서 엔타이틀먼트는 특정 기간 동안 n8n 인스턴스에 플랜 제한 기능에 대한 접근을 부여합니다.

n8n 명령줄 사용