명령 레퍼런스
ntro의 모든 공개 명령과 옵션을 용도별로 정리했습니다.
읽는 법
<인자>는 꼭 필요한 값,[인자]는 생략할 수 있는 값입니다. 터미널에서[인자]를 생략하면 목록에서 고르거나 입력하라고 묻습니다. 자동화에서는 직접 적어야 할 수 있습니다.- 표에는 그 명령 전용 옵션만 적었습니다.
--team,--json같은 공통 옵션은 CLI 설정에 있습니다. - 명령 그룹(
builds,domains,env등)에 붙는 옵션(예:--app)은 하위 명령 모두에 적용됩니다. - 모든 명령은
--help로 사용법과 예시를 볼 수 있습니다.
로그인·상태·업데이트
| 명령 | 설명 |
|---|---|
ntro login | 브라우저로 로그인합니다. --no-browser: 브라우저를 열지 않고 URL과 코드만 보여 줍니다. |
ntro logout | 로그아웃하고 로컬 로그인 정보를 지웁니다. |
ntro whoami | 로그인한 계정과 이메일 인증 여부를 보여 줍니다. |
ntro token | REST API를 직접 호출할 때 쓸 5분짜리 접속 토큰을 출력합니다. NITROSHIP_TOKEN이 있으면 그 API 토큰을 씁니다. 사용법은 API 인증에 있습니다. |
ntro status | API 상태와 로그인 상태를 확인합니다. |
ntro healthcheck | API의 /healthz를 확인합니다. |
ntro update | 최신 버전으로 업데이트합니다. --check: 확인만 합니다. 별칭 upgrade. |
자동 업데이트 알림: ntro는 하루에 한 번까지 백그라운드에서 새 버전을 확인하고, 있으면 명령이 끝난 뒤 알려 줍니다. 명령을 느리게 만들지 않습니다. --json, CI(CI가 비어 있지 않음), stderr가 터미널이 아닐 때, 개발·프리릴리스 빌드, --help·--version·자동 완성에서는 확인하지 않습니다. 직접 끄려면 NITROSHIP_NO_UPDATE_NOTIFIER=1을 설정하세요.
팀
| 명령 | 설명 |
|---|---|
ntro teams list | 내가 속한 팀 목록 |
ntro teams create [이름] | 팀을 만듭니다. --slug <슬러그>로 슬러그를 지정할 수 있고, 이름에서 슬러그를 만들 수 없으면 필수입니다. |
ntro teams switch [팀] | 기본 팀을 바꿉니다. 별칭 ntro switch. |
ntro teams members list | 팀 멤버 목록 |
ntro teams members add [이메일] | 초대를 보냅니다. --role member|billing|viewer. 자동화에서는 이메일과 역할 모두 필요합니다. |
ntro teams members role [사용자] [역할] | 멤버 역할을 바꿉니다. 사용자는 ID 또는 이메일. |
ntro teams members remove [사용자] | 멤버를 뺍니다. 자동화에서는 대상과 --yes 필요. |
ntro teams invitations create [이메일] | 초대를 보냅니다. --role은 생략하면 member. |
ntro teams invitations list | 초대 목록. 별칭 ls. |
ntro teams invitations revoke [초대 ID|이메일] | 보류 중인 초대를 취소합니다. 자동화에서는 대상과 --yes 필요. 별칭 rm. |
초대·멤버 관리는 팀 owner만 할 수 있습니다. 초대는 수락해야 팀에 들어오고 7일 뒤 만료됩니다. 소유권 이전과 자세한 규칙은 팀과 권한을 참고하세요. teams의 별칭은 team입니다.
앱과 폴더 연결
| 명령 | 설명 |
|---|---|
ntro apps list | 팀의 앱 목록. 별칭 ls. |
ntro apps create [슬러그] | 앱을 만들고 현재 폴더에 연결합니다. --no-link: 연결하지 않습니다. |
ntro apps show [앱] | 앱 정보. 생략하면 연결된 앱. |
ntro apps delete [앱] | 앱을 삭제합니다. 터미널에서는 슬러그를 직접 입력해 확인하고, 자동화에서는 --yes 필요. 별칭 rm, remove. |
ntro link [앱] | 현재 폴더를 앱에 연결합니다. 생략하면 목록에서 고릅니다. |
ntro unlink | 현재 폴더의 연결을 지웁니다. 앱은 삭제되지 않습니다. |
ntro unlink --json은 연결을 지웠으면 {"unlinked":true,"appId":"<id>"}(알면 teamId도), 연결이 없었으면 {"unlinked":false}를 출력합니다. 연결 방식은 CLI 설정 > 앱 연결에 있습니다.
배포
ntro deploy [폴더] # 또는 ntro [폴더]인자 없이 ntro만 실행해도 현재 폴더를 배포합니다.
| 옵션 | 설명 |
|---|---|
--app <ID|슬러그> | 배포할 앱. 연결된 폴더라면 생략할 수 있습니다. |
--prod / --preview / --target production|preview | 배포 대상. 하나만 쓸 수 있습니다. 생략하면 첫 배포는 프로덕션, 이후는 프리뷰. |
--no-wait | 빌드를 대기열에 넣고 바로 끝냅니다. |
--timeout <시간> | 기다리는 최대 시간. 기본 10분. |
--yes | 질문 없이 진행합니다. 연결되지 않은 폴더라면 --app이 필요합니다. |
--local, --image, --bundle-dir, --entrypoint, --skip-build | 직접 빌드해서 올릴 때 씁니다. 아래 참고. |
--regions, --tier, --min-instances <0..32>, --max-instances <1..32>, --port | 컴퓨트 설정. 직접 업로드에서만 쓸 수 있습니다. |
기본으로는 배포가 ready 또는 failed가 될 때까지 기다리며 빌드 로그를 보여 줍니다. --json을 쓰면 진행 상황은 stderr로, 결과는 stdout에 JSON 객체 하나로 나옵니다. 기다렸다면 Deployment 객체, --no-wait였다면 Build 객체입니다.
배포 방식 고르기
| 방식 | 명령 예시 | 언제 쓰나요 |
|---|---|---|
| 원격 빌드 (기본) | ntro deploy . | 대부분의 경우. 소스를 올리면 나이트로쉽이 빌드합니다. |
| 로컬 빌드 | ntro deploy . --local | 지원되는 정적 앱이나 관리형 Node.js 앱(Next.js 포함)을 내 컴퓨터에서 빌드하거나, 이미 만든 정적 폴더를 그대로 올릴 때 |
| 로컬 빌드 재사용 | ntro deploy . --local --skip-build | 지원되는 관리형 프레임워크 앱을 이미 빌드했고, 결과물을 다시 빌드하지 않고 올릴 때 |
| 컨테이너 이미지 | ntro deploy --image sha256:<digest> | 직접 빌드한 OCI 이미지를 배포할 때 |
| Node.js 번들 | ntro deploy --bundle-dir ./out --entrypoint 'node server.js' | 실행할 파일이 모인 폴더와 실행 명령을 직접 정할 때 |
배포 자산을 올릴 때 앱에 이미 저장된 콘텐츠는 재사용합니다. 진행 상황에는 실제로 보낸 파일 바이트와 건너뛴 변경 없는 파일 수가 표시됩니다. Node.js 번들은 여전히 전체를 올립니다. 업로드는 나이트로쉽 API를 거치며, 이전 서버에는 자동으로 모든 파일을 보냅니다.
--image와--bundle-dir는 함께 쓸 수 없습니다.--bundle-dir에는--entrypoint가 꼭 필요합니다.--local은static·node-server프리셋과 Next.js 전용 어댑터를 지원합니다. 정적 사이트용 툴체인 이미지를 생성하는 빌더를 포함해container·container-static프리셋은 거부합니다. Dockerfile 빌드도 호스팅 빌드가 필요합니다.--local을 빼면 나이트로쉽이 소스를 빌드합니다. 자세한 내용은 빌드 프레임워크 문서를 참고하세요.- 원격 빌드에서는 컴퓨트 플래그를 쓸 수 없습니다. 콘솔의 App Settings > Compute나
nitroship.json을 쓰세요. 자세한 내용은 컴퓨트 설정 문서를 참고하세요. --tier에는 플랫폼에서 제공하는 티어 이름을 씁니다. 기본은standard이고large등이 있으며, 사용할 수 있는 이름과 CPU·메모리는 콘솔이나GET /v1/compute/options에서 확인할 수 있습니다. 비활성화된 티어로는 새로 배포할 수 없습니다.ntro registry login은 나이트로쉽 레지스트리에 이미지를 올리기 위한 Docker 로그인 명령을 출력만 합니다(--json이면registry,username,password). 출력에 비밀번호가 들어 있으니 공유 로그에 남기지 마세요.
배포 관리·로그
| 명령 | 설명 |
|---|---|
ntro deployments list | 배포 목록. --target production|preview로 거르기. 별칭 ntro ls, ntro list. |
ntro deployments show <짧은 ID|ID> | 배포 상세 |
ntro inspect [짧은 ID|ID] | 배포 상세. --logs: 이벤트도 함께 보기. |
ntro promote <짧은 ID|ID> | 준비된 배포를 프로덕션으로 승격. --yes. |
ntro rollback <짧은 ID> | 프로덕션을 예전 배포로 되돌리기. --yes. |
ntro redeploy <짧은 ID|ID> | 준비된 배포의 파일로 새 배포 만들기. --prod 또는 --preview. |
ntro logs [짧은 ID|ID] | 배포 이벤트. --follow: 계속 따라 보기. |
ntro builds list | 원격 빌드 목록 |
ntro builds logs [ID] | 빌드 이벤트. --follow: 계속 따라 보기. |
ntro builds cancel [ID] | 대기·실행 중인 빌드 취소. 자동화에서는 ID와 --yes 필요. |
모두 --app으로 앱을 지정할 수 있습니다. 승격·롤백의 개념은 배포 관리를 참고하세요.
도메인
| 명령 | 설명 |
|---|---|
ntro domains add [호스트] | 도메인 등록 |
ntro domains list | DNS·인증서 상태 보기. 별칭 ls. |
ntro domains verify <호스트> | 소유권 확인 요청. --wait, --timeout <시간>. |
ntro domains remove [호스트] | 도메인 해제. --yes. 별칭 rm. |
자세한 내용은 커스텀 도메인 문서를 참고하세요.
환경 변수
| 명령 | 설명 |
|---|---|
ntro env ls [production|preview] | 목록. 별칭 list. |
ntro env add <이름> [production|preview] | 값 추가. 기본은 비밀 값. --no-sensitive(일반 값), --sensitive, --force(덮어쓰기). |
ntro env rm <이름> [production|preview] | 삭제. --yes. 별칭 remove. |
ntro env pull [파일] | 일반 값을 파일로 저장. --environment production|preview, --yes(덮어쓰기). |
ntro env run -- <명령> [인자...] | 일반 값을 넣고 명령 실행. --environment production|preview. |
자세한 내용은 환경 변수 문서를 참고하세요.
캐시
| 명령 | 설명 |
|---|---|
ntro purge <URL|/경로> | --app, --wait, --yes: 정확한 URL/경로 하나를 무효화합니다. 인자 대신 --prefix <경로>, --glob <패턴>, 반복 --tag <태그>(최대 16개), --host <호스트>, --all 중 한 종류를 선택합니다. --delete는 stale/백그라운드 갱신 대신 응답 캐시를 논리 삭제하며 기존 프리렌더 동작은 그대로입니다. |
자세한 내용은 캐시 무효화 문서를 참고하세요.
사용량·청구
| 명령 | 설명 |
|---|---|
ntro usage | 팀 사용량과 예상 금액. --from, --to(YYYY-MM-DD 또는 RFC3339), --by region|app|day. |
ntro billing | 팀 플랜·결제 상태 |
ntro invoices | 청구서 목록 |
ntro usage의 금액은 크레딧 잔액이 아니라 팀 청구 통화로 표시한 예상 금액입니다. 1크레딧 = 1 USD이며, 통화별 환산에는 실시간 환율이 아닌 운영자가 게시한 고정 크레딧 가격을 씁니다. 플랜의 월 크레딧은 사용 요금에만 적용되고 이월되지 않습니다. 운영자가 지급한 크레딧은 통화와 관계없이 먼저 지급한 순서대로 청구서 총액에서 차감합니다. 총액이 0보다 큰 청구서의 결제가 완료되면 청구 고객 정보에 저장된 이메일 주소로 영수증을 보냅니다.
자세한 내용은 사용량과 청구 문서를 참고하세요.