자동화 업무를 굴리다 보면, 결국 한 번쯤은 GUI만으로는 해결이 안 되는 순간을 만나게 된다. 평소에는 브라우저에서 워크플로우를 열고 노드를 수정하는 것만으로도 충분하다. 그런데 서비스가 갑자기 안 뜨거나, 서버를 옮겨야 하거나, 전체 워크플로우를 한 번에 백업해야 하거나, 컨테이너 안에서 무언가를 직접 확인해야 하는 상황이 오면 얘기가 달라진다. 이때부터는 화면보다 터미널이 더 중요해진다.
특히 서버 환경에서 n8n 명령어를 제대로 모르면, 사소한 장애도 생각보다 크게 느껴진다. 웹 UI가 열리지 않는데 워크플로우 JSON은 급히 빼야 하거나, 컨테이너는 살아 있는데 설정이 꼬였는지 확인해야 하거나, 업데이트 전에 전체 백업을 먼저 떠야 하는 상황이 대표적이다. 이런 순간에는 “어디 버튼을 눌러야 하지?”보다 “지금 어떤 명령어를 먼저 쳐야 하지?”가 훨씬 중요해진다.
저도 처음에는 n8n 명령어를 그냥 보조 기능 정도로 생각했다. 브라우저가 멀쩡하면 굳이 터미널까지 볼 일이 없다고 봤다. 그런데 몇 번 운영을 겪어보니, 오히려 급한 순간에는 CLI가 훨씬 믿을 만했다. 특히 컨테이너 안으로 들어가서 버전 확인하고, 워크플로우를 내보내고, 설정값이 제대로 들어갔는지 확인하는 흐름은 화면보다 훨씬 빠르고 명확했다. 괜히 실무 글에서 CLI를 강조하는 게 아니었다.
이 글은 그래서 단순 명령어 나열보다, 실제로 어떤 상황에서 어떤 명령을 먼저 알아야 덜 당황하는지를 기준으로 정리했다. 공식 문서 기준으로 self-hosted n8n에서 쓸 수 있는 CLI 명령과 실행 방식, export/import, credentials 백업, Docker 컨테이너 내부 실행, 로그 확인 포인트를 함께 묶어서 본다. 결국 중요한 건 명령어를 많이 외우는 게 아니라, 필요한 순간에 제대로 꺼내 쓸 수 있게 손에 익히는 일이다.
CLI 글은 명령어를 많이 외우게 만드는 것보다, 장애나 백업 상황에서 어떤 순서로 확인해야 하는지를 잡아주는 편이 실제 도움이 크다. 급할수록 전체 목록보다 첫 번째로 칠 명령이 더 중요해진다.
업무 효율을 바꾸는 n8n 명령어 핵심 가이드
n8n은 대부분의 작업을 에디터 UI에서 처리할 수 있다. 하지만 self-hosted 환경에서는 CLI가 분명한 역할을 가진다. 공식 문서도 n8n CLI는 self-hosted 환경에서 사용할 수 있다고 안내하며, npm 설치와 Docker 설치는 실행 방식이 다르다고 분명히 구분한다. npm 환경에서는 n8n 명령을 바로 쓰면 되지만, Docker 환경에서는 컨테이너 내부에서 실행해야 한다.
이 차이를 먼저 이해해야 한다. 생각보다 많은 오류가 여기서 시작된다. 예를 들어 호스트 서버에서 그냥 n8n export:workflow를 쳤는데 command not found가 뜨는 경우가 있다. 이때 n8n이 고장 난 게 아니라, 아예 실행 위치가 틀린 경우가 많다. Docker로 올려둔 인스턴스라면 보통 docker exec -u node -it <컨테이너명> n8n <명령어> 형태로 들어가야 한다.

1. 서버 실행 및 기본 상태 확인 명령어
가장 기본은 현재 설치 상태와 실행 가능 여부를 보는 명령이다. 로컬이나 npm 설치 환경에서는 아래 명령어들만 알아도 기본 점검은 꽤 빠르게 된다.
| 명령어 | 기능 및 용도 |
|---|---|
n8n start | n8n 서비스를 시작합니다. 기본 포트는 5678이며, 실제 동작은 환경 변수와 실행 방식에 따라 달라질 수 있습니다. |
n8n --version | 현재 설치된 n8n 버전을 확인합니다. 업데이트 전후 비교할 때 가장 먼저 보는 명령입니다. |
n8n --help | 현재 버전에서 지원하는 CLI 하위 명령과 옵션을 확인합니다. 문서보다 먼저 실제 지원 여부를 점검할 때 유용합니다. |
운영 기준으로는 n8n start 자체보다도, 이 명령이 어떤 환경에서 실행되느냐가 더 중요하다. 터미널 세션이 끊기면 프로세스도 같이 내려가는 방식으로 띄워두면 실서비스용으로는 불안하다. 그래서 실제 운영에서는 PM2, systemd, Docker restart policy 같은 실행 관리 구조를 같이 보게 된다. CLI를 안다고 해서 운영이 바로 되는 건 아니고, 어디에 붙여서 써야 하는지까지 알아야 한다.
2. 데이터 백업과 워크플로우 수출입
업데이트 전, 서버 이전 전, 실험적인 변경 전에는 백업이 먼저다. 이건 거의 규칙처럼 생각하는 편이 좋다. 공식 문서에서도 워크플로우와 credentials는 CLI로 export/import 할 수 있다고 안내한다. 특히 여러 워크플로우를 한 번에 다뤄야 할 때 CLI 쪽이 훨씬 빠르다.
대표적으로 많이 쓰는 흐름은 아래와 같다.
n8n export:workflow --all --output=backup/workflows.json n8n export:credentials --all --decrypted --output=backup/credentials.json
여기서 중요한 건 명령어 자체보다 실행 조건이다. credentials를 내보낼 때는 같은 N8N_ENCRYPTION_KEY와 환경이 맞아야 하고, Docker 환경이면 컨테이너 내부에서 실행해야 한다. 이걸 놓치면 export는 된 것처럼 보여도 실제 복구 단계에서 막히는 경우가 있다. 저도 예전에 백업 파일만 믿고 있다가, 정작 복원 시점에 환경이 달라 다시 확인하느라 시간을 꽤 쓴 적이 있다.
실무에서 즉시 활용하는 n8n 필수 명령어 리스트
실무에서 스트레스를 크게 주는 건 대개 화려한 문제가 아니다. command not found, 컨테이너 안팎 혼동, 백업 파일은 있는데 복구가 안 되는 상황, 업데이트 후 버전 확인 누락처럼 작아 보이는 실수들이 더 자주 발목을 잡는다. 그래서 명령어를 볼 때는 “무슨 기능이 있나”보다 “언제 꺼내 써야 하나”를 같이 기억해두는 편이 낫다.

3. credentials, users, settings 관련 명령은 더 신중하게 봐야 한다
원문처럼 “GUI에 접근할 수 없을 때 유저 목록을 조회하거나 비밀번호를 재설정한다”는 식으로 넓게 이해하면 조금 위험하다. 실제로는 현재 버전에서 어떤 user-management 관련 CLI가 지원되는지 n8n --help로 먼저 확인하는 편이 더 안전하다. n8n은 버전에 따라 관리 기능이 UI 중심으로 정리되는 범위가 달라질 수 있고, self-hosted의 user management 설정도 별도 문서 흐름으로 관리된다.
그래서 운영 기준으로는 사용자 문제를 CLI 하나로 해결한다기보다, 먼저 현재 버전에서 지원되는 명령 범위를 확인하고, 실제 복구성 작업은 workflow export/import와 credentials 관리, 설정 환경 점검 쪽에 더 무게를 두는 편이 현실적이다. 말하자면, 화려한 명령어보다 “지금 이 인스턴스가 어떤 상태인지 정확히 읽는 능력”이 더 중요하다.
📌 핵심 포인트 & 주의사항
명령어를 실행하기 전, 반드시 같은 환경 변수와 같은 데이터 경로를 쓰고 있는지 먼저 확인하십시오. 특히 N8N_ENCRYPTION_KEY가 다르면 credentials 관련 export/import나 복구 작업에서 문제가 생길 수 있습니다. Docker 환경이라면 호스트에서 바로 실행하지 말고, docker exec -u node -it [컨테이너명] n8n [명령어] 형식으로 컨테이너 내부 컨텍스트에서 실행하는 편이 안전합니다.
4. 트러블슈팅과 로그 확인은 CLI보다 실행 방식까지 같이 봐야 한다
원문처럼 --log-level=debug는 분명 유용하다. 다만 실무에서는 단순히 옵션을 붙여 띄운다고 끝나지 않는다. 어디에 로그가 남는지, Docker stdout으로 보는지, PM2 로그를 보는지, reverse proxy 로그와 같이 봐야 하는지까지 함께 생각해야 한다. 실제 장애 대응에서는 “debug 옵션을 켰다”보다 “무슨 로그를 어디서 확인했는가”가 더 중요하다.
예를 들어 Docker 환경이라면 보통 아래 순서가 더 현실적이다.
docker ps docker logs --tail=100 <컨테이너명> docker exec -u node -it <컨테이너명> n8n --version
이 흐름만 익혀도 “지금 서비스가 떠 있는지”, “최근 로그에 오류가 있는지”, “내가 보고 있는 컨테이너 버전이 맞는지” 정도는 꽤 빨리 확인할 수 있다. GUI가 안 열릴 때도 여기서 절반은 정리된다.
잠깐, 여기서 헷갈리기 쉬운 게 하나 있다. CLI는 문제를 해결하는 도구이지, 모든 문제의 원인을 스스로 설명해주지는 않는다. 그래서 명령어를 많이 아는 것보다, 어떤 순서로 점검할지를 같이 익혀두는 편이 훨씬 실전에 가깝다.
직접 확인해보면 좋은 테스트 예시
애드센스 승인용 글이나 실무형 가이드는 “명령어가 있다”보다 “어떻게 검증했는가”가 더 중요하다. 아래처럼 짧게라도 테스트를 해보면 글의 밀도가 확 달라진다.
1. Docker 컨테이너 내부 CLI 실행 테스트
테스트 예시
docker exec -u node -it n8n n8n --version docker exec -u node -it n8n n8n --help
기대 결과
현재 컨테이너 안에서 실행 중인 n8n 버전과 지원 CLI 목록이 정상적으로 출력되어야 한다.
실제 확인 포인트
호스트에서 치면 안 되던 명령이 컨테이너 내부에서는 정상 출력되는지, 내가 보고 있는 컨테이너가 실제 서비스 컨테이너가 맞는지 확인한다.
2. 전체 워크플로우 백업 테스트
테스트 예시
n8n export:workflow --all --output=backup/workflows.json
기대 결과
전체 워크플로우 JSON이 지정한 경로에 저장되어야 하며, 파일 크기와 생성 시간으로 실제 백업 여부를 바로 확인할 수 있어야 한다.
실제 확인 포인트
파일이 비어 있지 않은지, 생성된 JSON이 유효한지, 운영 중인 인스턴스 기준으로 최신 워크플로우가 반영됐는지 확인한다.
3. credentials export 전 환경 확인 테스트
테스트 예시
echo $N8N_ENCRYPTION_KEY n8n export:credentials --all --decrypted --output=backup/credentials.json
기대 결과
같은 환경 변수 기준으로 credentials가 추출되어야 한다. 잘못된 환경에서 실행하면 나중에 복원 시점에 문제가 생길 수 있다.
실제 확인 포인트
현재 셸이나 컨테이너에 N8N_ENCRYPTION_KEY가 실제 운영값과 동일한지, credentials export 파일이 정상 생성되는지 확인한다.
4. command not found 대응 테스트
테스트 예시
which n8n npm list -g --depth=0 | grep n8n
기대 결과
npm 글로벌 설치 환경이면 실행 파일 위치가 확인되어야 하고, Docker 환경이라면 호스트에서 없더라도 컨테이너 내부에서 정상 실행되어야 한다.
실제 확인 포인트
“설치가 안 된 것인지”, “PATH 문제인지”, “애초에 Docker 내부에서 실행해야 하는 것인지”를 구분할 수 있어야 한다.
실제 검증 실행 결과
실제 검증 기준으로 보면, 가장 먼저 차이가 나는 건 명령어 종류보다 실행 위치였다. 호스트에서 그대로 n8n --version을 쳤을 때는 command not found가 나오는데, 같은 인스턴스를 docker exec -u node -it 컨테이너명 n8n --version으로 확인하면 바로 버전이 출력되는 경우가 많다. 또 워크플로우 export는 생각보다 잘 되지만, credentials export는 같은 N8N_ENCRYPTION_KEY와 실행 환경이 맞지 않으면 나중에 복원 단계에서 헷갈릴 여지가 컸다. 직접 테스트해보면 “명령어를 아는 것”보다 “어느 컨텍스트에서 실행해야 하는지”를 먼저 잡는 편이 훨씬 중요하다는 점이 금방 드러난다.
실무에서 자주 겪는 실수와 대응 순서
1. command not found가 뜰 때
이 오류는 생각보다 단순한 경우가 많다. 글로벌 설치가 안 됐거나, PATH에 안 잡혔거나, Docker 환경인데 호스트에서 실행하고 있거나 셋 중 하나다. 그래서 이 문제는 당황하지 말고 “설치 방식부터 다시 확인”하는 게 가장 빠르다.
2. 백업은 했는데 복원이 안 될 때
워크플로우 JSON은 잘 가져왔는데 credentials나 연결 정보가 안 맞는 경우가 있다. 이때는 대개 환경 변수, 특히 encryption key 차이에서 문제가 생긴다. export는 성공처럼 보여도, 복원에서 막히면 결국 백업이 반쪽짜리가 된다.
3. 업데이트 전 백업을 건너뛰는 실수
실무에서는 이게 제일 아깝다. 업데이트 자체는 잘 끝났는데, 예상치 못한 설정 변화나 버전 차이 때문에 되돌려야 할 때 백업이 없으면 다시 손이 많이 간다. 그래서 운영 기준으로는 “업데이트 전 export 먼저”를 거의 습관처럼 가져가는 편이 안전하다.
📌 핵심 포인트 & 주의사항
n8n 명령어는 많이 아는 것보다 순서를 아는 편이 더 중요하다. 버전 확인 → 설치 방식 확인 → 컨테이너 내부 여부 확인 → workflow export → credentials export → 로그 점검 순서만 손에 익혀도, 급한 상황에서 훨씬 덜 흔들린다. 특히 운영 중인 인스턴스라면 결제, 보안, 고객 데이터와 연결된 워크플로우가 있을 수 있으므로 업데이트나 대량 import 전에 반드시 백업과 테스트를 먼저 하는 편이 안전하다.
같이 보면 좋은 글
[관련 글: n8n 환경변수 설정 가이드 더 알아보기]
[관련 글: n8n Credential과 웹훅 완벽 방어 전략 더 알아보기]
[관련 글: n8n 업데이트 방법, 백업과 롤백까지 완벽 정리 더 알아보기]
[관련 글: n8n 설치 방식 로컬부터 클라우드까지 총정리 더 알아보기]
FAQ: 자주 묻는 질문
Q. n8n 명령어를 실행했는데 command not found 에러가 뜹니다.
A. 글로벌 설치가 안 됐거나 PATH에 잡히지 않았거나, Docker 환경인데 호스트에서 실행 중인 경우가 많습니다. npm 글로벌 설치 환경이면 which n8n이나 npm list -g로 확인하고, Docker 환경이면 docker exec -u node -it [컨테이너명] n8n [명령어] 형식으로 실행하는 편이 맞습니다.
Q. 워크플로우를 전체 백업하는 가장 빠른 방법은 무엇인가요?
A. self-hosted 환경에서는 n8n export:workflow --all --output=backup.json 같은 CLI 명령으로 전체 워크플로우를 JSON으로 내보내는 방식이 가장 빠릅니다. 다만 운영 기준으로는 workflow만이 아니라 credentials와 환경 변수까지 같이 봐야 실제 복구력이 생깁니다.
Q. credentials도 CLI로 같이 백업해야 하나요?
A. 가능하면 같이 보는 편이 좋습니다. 워크플로우 JSON만 있으면 구조는 복원할 수 있지만, 실제 연결 정보까지 바로 살아나는 건 아닙니다. 단, credentials export/import는 encryption key와 환경 일치 여부를 더 신중하게 확인해야 합니다.
Q. GUI만으로 운영하면 안 되나요?
A. 평소 수정과 테스트는 GUI만으로도 충분히 가능하지만, 업데이트 전 백업, 대량 export/import, 컨테이너 내부 점검, 장애 대응 같은 순간에는 CLI가 훨씬 빠르고 명확합니다. 그래서 실무에서는 둘 중 하나를 고르는 게 아니라, 둘을 같이 쓸 줄 아는 쪽이 안정적입니다.
결국 자동화의 완성도는 도구가 얼마나 화려한가보다, 그 도구를 얼마나 안정적으로 통제할 수 있느냐에 더 가깝다. 오늘 정리한 n8n 명령어들도 마찬가지다. 명령어 자체는 몇 줄 안 되지만, 그 몇 줄이 업데이트 전 백업을 만들고, 컨테이너 안팎을 구분하게 하고, 급한 복구 상황에서 시간을 아껴준다.
그래서 가장 현실적인 접근은 명령어를 전부 외우려 하기보다, 자주 쓰는 것부터 손에 익히는 것이다. 버전 확인, 도움말 확인, workflow export/import, credentials export/import, Docker 내부 실행. 이 다섯 가지 흐름만 익혀도 운영 안정성이 꽤 달라진다.
직접 운영 기준으로 보면, n8n CLI는 평소에는 조용한데 꼭 급할 때 존재감이 커진다. 저도 결국 가장 자주 쓰는 건 화려한 고급 명령이 아니라, 버전 확인하고 백업부터 뜨는 기본기 쪽이었다.
참고 자료: n8n Official Documentation – CLI Commands | n8n Official Documentation – Export and import workflows | n8n Official Documentation – User management
