Cordova 명령줄 도구(CLI) 참조 매뉴얼

Posted on 8월 04, 2026 by

이 장은 참조 매뉴얼이므로 전체를 학습할 필요 없이 필요할 때 찾아보면 됩니다.

CLI 구문

cordova <command> [옵션] -- [플랫폼 고유 매개변수]Code language: CSS (css)

전역 명령 목록

Cordova 프로젝트 폴더에 진입하지 않아도 실행 가능

명령설명
create새 프로젝트 생성
help지정한 명령의 도움말 확인
configCordova 전역 설정 항목 설정, 조회, 삭제, 편집, 목록 출력

프로젝트 명령 목록

유효한 Cordova 프로젝트 루트 디렉터리에서 실행해야 함

명령설명
info프로젝트 환경 정보 출력
requirements대상 플랫폼에 필요한 모든 의존 환경 검사 및 출력
platform프로젝트 플랫폼 관리 (Android/iOS/Browser 등)
plugin프로젝트 플러그인 관리
prepare리소스 파일을 각 플랫폼 디렉터리로 복사하고 컴파일 준비 수행
compile지정 플랫폼 프로젝트 컴파일
build앱 빌드 (prepare + compile과 동일)
clean플랫폼 컴파일로 생성된 캐시 산출물 정리
run앱 실행 (내부적으로 prepare + compile + 배포 및 실행 처리)
serve로컬 웹 서버를 실행해 웹 리소스 미리보기 (내부 prepare 실행)

공통 옵션 (모든 CLI 명령 지원)

매개변수설명
-d / –verbose상세 로그 출력. Node 코드에서 cordova-cli 호출 시 log, warn 이벤트를 수신해 로그를 얻을 수 있습니다: cordova.on('log', ()=>{})
-v / –version현재 Cordova CLI 버전 표시
–nohooks훅 스크립트(hook) 실행을 금지하며 정규식으로 훅 필터링 가능

플랫폼 고유 매개변수 설명

일부 명령은 플랫폼 사용자 정의 매개변수(platformOpts)를 지원합니다.
-- 구분자를 사용해야 합니다: -- 앞은 Cordova CLI가 해석하고, -- 뒤의 모든 매개변수는 대상 네이티브 플랫폼 빌드 도구에 직접 전달됩니다.

CLI 사용 예시

전체 작업 흐름 예시:

  1. 프로젝트 생성
  2. 카메라 플러그인 설치
  3. Android 플랫폼 추가
  4. Android 컴파일 및 실행
  5. Android 서명 매개변수를 사용해 정식 패키지 빌드
# 프로젝트 생성
cordova create myApp com.foxdevelop.myApp myApp
cd myApp

# 카메라 플러그인 추가
cordova plugin add cordova-plugin-camera

# Android 플랫폼 추가
cordova platform add android

# Android 컴파일 환경 의존성 검사
cordova requirements android

# Android 컴파일 (상세 로그 출력)
cordova build android --verbose

# 기기/에뮬레이터에서 앱 실행
cordova run android

# 릴리즈 정식 패키지 빌드 및 서명 매개변수 전달
cordova build android --release -- --keystore="..\android.keystore" --storePassword=android --alias=mykeyCode language: PHP (php)

각 명령 상세 설명

cordova create

Cordova 프로젝트 디렉터리 구조를 생성합니다.
구문:

cordova create path [패키지ID [앱 이름]] [옵션]Code language: CSS (css)

매개변수

값설명
path프로젝트 폴더 (폴더가 미리 존재해서는 안 되며 CLI가 자동 생성)
id패키지 식별자, 기본값: org.apache.cordova.hellocordova
역방향 도메인 형식이며 config.xml의 widget id에 대응. Java 패키지명 생성에 사용되므로 적절히 설정하는 것을 권장
name앱 표시 이름, 기본값: Hello Cordova
config.xml name에 대응하며 네이티브 프로젝트 클래스명으로 생성됨

옵션

  • --template：로컬/NPM/GitHub 사용자 정의 템플릿으로 프로젝트 생성
cordova create myapp com.mycompany.myteam.myapp MyAppCode language: CSS (css)

cordova platform

플랫폼 관리: 추가, 삭제, 업데이트, 목록 조회. 플랫폼 추가/삭제 시 프로젝트 platforms 디렉터리가 수정됩니다.

cordova {platform | platforms} [
    add <플랫폼 명세> [...] {--save | link=<경로> } |
    {remove | rm} 플랫폼 [...] {--save}|
    {list | ls}  |
    update ]Code language: HTML, XML (xml)

하위 명령 및 매개변수

하위 명령매개변수설명
add <플랫폼 명세>플랫폼 추가
–nosave설치 후 플랫폼 정보를 config.xml / package.xml에 기록하지 않음
–link=로컬 플랫폼 소스 사용 시 파일 복사 대신 심볼릭 링크 생성 (플랫폼 개발 디버깅용)
remove <플랫폼>플랫폼 삭제
–nosave플랫폼을 삭제하되 config.xml / package.json 내 기록은 유지
update <플랫폼>플랫폼 버전 업데이트
–saveconfig.xml에 기록된 플랫폼 버전 갱신
list / ls설치된 모든 플랫폼 및 사용 가능 플랫폼 목록 출력

플랫폼 명세 형식 <platform-spec>

플랫폼[@버전번호] | 로컬경로 | Git주소[#브랜치/tag/commit]Code language: PHP (php)
  • platform：플랫폼 이름 android / ios / browser / electron
  • version：시맨틱 버전 semver, 예시 ^13.0.0
  • path：로컬 플랫폼 소스 디렉터리 / tar 압축파일
  • url：Git 저장소 주소
  • commit-ish：지정 브랜치, 태그, commit 해시; 미지정 시 기본 master

지원 플랫폼

android、browser、electron、ios

# Android+iOS 추가하고 설정파일에 기록
cordova platform add android ios

# 버전 지정하여 Android 플랫폼 추가
cordova platform add android@^13.0.0

# Git 저장소의 특정 태그로 플랫폼 설치
cordova platform add https://github.com/myfork/cordova-android.git#13.0.0

# 로컬 디렉터리로 플랫폼 설치
cordova platform add ../android

# Android 플랫폼 삭제
cordova platform rm android

# 모든 플랫폼 확인
cordova platform lsCode language: PHP (php)

cordova plugin

프로젝트 플러그인 관리

cordova {plugin | plugins} [
    add <플러그인 명세> [..] {--searchpath=<디렉터리> | --noregistry | --link | --save | --force} |
    {remove | rm} {<플러그인ID> | <이름>} --save |
    {list | ls}
]Code language: HTML, XML (xml)

하위 명령 매개변수

하위 명령매개변수설명
add <플러그인 명세>플러그인 추가
–searchpath <디렉터리>플러그인 탐색 시 로컬 디렉터리를 우선 검색, 다중 경로 구분자: Windows ;、Linux/Mac :
–noregistrynpm 공식 레지스트리에서 플러그인 불러오지 않음
–link로컬 플러그인 디렉터리 설치 시 심볼릭 링크 생성 (플러그인 개발 디버깅)
–nosaveconfig.xml / package.json에 기록하지 않음
–force충돌 파일 강제 덮어쓰기 (6.1 버전 추가)
remove플러그인 삭제
–nosave플러그인을 삭제하되 설정 파일 기록 유지
list / ls설치된 플러그인 목록 표시

플러그인 명세 형식 <plugin-spec>

[@scope/]플러그인ID[@버전] | 로컬디렉터리 | Git주소[#commit][:하위디렉터리]Code language: PHP (php)

플러그인 해석 우선순위 (높음→낮음)

  1. 명령행에 직접 지정한 플러그인 및 버전
  2. config.xml / package.json에 저장된 플러그인 정보
  3. 현재 프로젝트와 호환 가능한 npm 최신버전 (플러그인 package.json에 cordova 의존성 선언)
  4. npm에 등록된 플러그인 최신버전
# 카메라, 파일 플러그인 설치, ../plugins 우선 탐색
cordova plugin add cordova-plugin-camera cordova-plugin-file --searchpath ../plugins

# 버전 지정 설치
cordova plugin add cordova-plugin-camera@^2.0.0

# 로컬 디렉터리로 플러그인 설치
cordova plugin add ../cordova-plugin-camera

# 플러그인 삭제
cordova plugin rm cordova-plugin-camera

# 플러그인 목록 확인
cordova plugin lsCode language: PHP (php)

플러그인 충돌 안내

일부 플러그인은 plugin.xml의 edit-config로 네이티브 설정 파일을 수정합니다.
여러 플러그인이 동일한 XML 노드를 수정하면 충돌이 발생하며 CLI는 기본적으로 설치를 차단합니다.
해결 방안:

  1. 플러그인 plugin.xml을 수정해 동일 노드 수정을 피하는 방식 권장
  2. --force로 강제 설치 (⚠️ 위험: 다른 플러그인의 수정 내용을 덮어쓸 수 있어 다른 플러그인이 정상 작동하지 않을 수 있음)

cordova prepare

config.xml 설정 내용을 각 플랫폼 네이티브 매니페스트 파일에 동기화하고 아이콘, 시작 이미지, 플러그인 리소스를 복사합니다. 프로젝트가 네이티브 SDK 컴파일 조건을 만족하도록 준비합니다.

cordova prepare [플랫폼 이름...]Code language: CSS (css)

플랫폼을 지정하지 않으면 모든 플랫폼에 대해 실행합니다.

cordova compile

컴파일만 수행하며 prepare는 실행하지 않습니다. 보통 직접 build 명령을 사용하며 훅 확장 시나리오에서 자주 활용됩니다.

cordova compile [플랫폼...]
    [--debug | --release]
    [--device | --emulator | --target=<이름>]
    [--buildConfig=<파일>]
    [-- 플랫폼 매개변수]Code language: CSS (css)

cordova build

prepare + compile과 동일하며 앱 패키지를 빌드합니다.

cordova build [플랫폼...]
    [--debug | --release]
    [--device | --emulator]
    [--buildConfig=<설정파일>]
    [-- 플랫폼 매개변수]Code language: CSS (css)
매개변수설명
–debug디버그용 빌드 패키지
–release정식 릴리즈 패키지
–device실기기용 패키지 빌드
–emulator에뮬레이터 아키텍처용 패키지 빌드
–buildConfig빌드 설정 파일 지정, 기본은 프로젝트 루트 build.json, 주로 서명 설정에 사용
cordova build android --release --buildConfig=build.json
cordova build android --release -- --keystore="app.keystore" --alias=key0Code language: JavaScript (javascript)

cordova run

prepare → build 순서로 실행한 뒤 앱을 실기기/에뮬레이터에 배포하고 실행합니다.

cordova run [플랫폼...]
    [--list | --debug | --release]
    [--noprepare]
    [--nobuild]
    [--device | --emulator | --target=<이름>]
    [--buildConfig=<파일>]
    [-- 플랫폼 매개변수]Code language: CSS (css)
매개변수설명
–list사용 가능한 실기기, 에뮬레이터 목록 표시
–noprepareprepare 단계 건너뛰기 (6.2+)
–nobuild컴파일을 건너뛰고 기존 설치 패키지 직접 배포
–target에뮬레이터/기기 이름 지정, --list로 이름 조회 후 사용

예시:

# 기기 목록 확인
cordova run android --list
# 지정 에뮬레이터로 실행
cordova run android --target=Nexus_5_API_23_x86
# 재컴파일 없이 바로 실행
cordova run android --nobuildCode language: PHP (php)

cordova emulate

cordova run --emulator의 별칭으로 에뮬레이터에서만 앱을 실행합니다.

cordova clean

각 플랫폼 컴파일 캐시 산출물 정리

cordova clean android

cordova requirements

플랫폼 구동에 필요한 모든 환경 의존성 검사 (JDK, Android SDK, Xcode 등)

cordova requirements android

모든 의존성 충족 시 종료코드 0을 반환하고 누락된 경우 0이 아닌 코드를 반환하며 자동화 빌드 환경 검증에 활용됩니다.

cordova info

전체 환경, 플랫폼, 플러그인 정보를 출력하며 버그 리포트 제출 시 필수로 사용합니다.

cordova info

cordova serve

로컬 웹 서버를 실행해 www 웹 리소스를 미리보며 기본 포트는 8000입니다.

cordova serve 8080
# 접속 주소：http://127.0.0.1:8080/android/wwwCode language: PHP (php)

cordova help

명령 도움말 확인

cordova help build
cordova build -h

cordova config

Cordova 전역 설정 관리

cordova config ls                # 모든 설정 목록 표시
cordova config set save-exact true
cordova config get save-exact
cordova config delete save-exact
cordova config editCode language: PHP (php)

Cordova 명령줄 도구(CLI) 참조 매뉴얼

Posted in Cordova 튜토리얼

답글 남기기

이메일 주소는 공개되지 않습니다. 필수 필드는 *로 표시됩니다