# CLI

> Nodaro CLI를 npm이나 독립 실행형 바이너리로 설치하고, 인스턴스마다 한 번 로그인한 뒤 터미널이나 CI 작업에서 워크플로, 앱, 단일 노드를 실행하세요.

Source: https://nodaro.ai/ko/docs/developers/cli

**Nodaro CLI**(`@nodaro/cli`)는 Nodaro용 명령줄 클라이언트입니다. 워크플로 목록을 보고 실행하며, 게시된 앱을 실행하고, 워크플로 없이 단일 노드를 실행하고, 각 실행이 끝날 때까지 따라갑니다. 로그인한 프로필 여러 개를 나란히 유지하고 스크립트용 JSON을 출력하므로 터미널 작업, cron 작업, CI 파이프라인에 잘 맞습니다.

CLI는 [TypeScript SDK](https://nodaro.ai/docs/developers/sdk)를 얇게 감싼 것입니다. 코드로 작성하는 연동에는 SDK를 직접 사용하세요.

## 설치
**npm**

npm 패키지는 macOS, Linux, Windows에서 실행됩니다. Node.js 20 이상이 필요합니다.

```bash
npm install -g @nodaro/cli
nodaro --version
```

패키지를 설치하지 않고 명령 하나만 실행하려면 `npx`를 사용하세요.

```bash
npx @nodaro/cli projects list
```

**macOS 및 Linux 바이너리**

독립 실행형 바이너리는 약 60MB의 단일 파일입니다. Node.js가 필요 없으며, 약 10ms 만에 시작됩니다.

CLI 릴리스는 공개 저장소에 `cli-vX.Y.Z` 태그로 올라갑니다. 저장소의 “latest” 릴리스는 CLI가 아니라 앱의 릴리스이므로, `releases/latest/download/...` 링크로는 CLI 바이너리를 받을 수 없습니다. 먼저 최신 `cli-v` 태그를 찾은 다음, 그 태그에서 내려받으세요.

```bash
# 1. The newest CLI version
NODARO_CLI_VERSION=$(curl -fsSL "https://api.github.com/repos/nodaroai/app.nodaro.ai/git/matching-refs/tags/cli-v?per_page=100" \
| grep -o '"refs/tags/cli-v[0-9][0-9.]*"' | tr -d '"' | sed 's#refs/tags/cli-v##' \
| sort -t. -k1,1n -k2,2n -k3,3n | tail -n 1)
echo "Installing @nodaro/cli $NODARO_CLI_VERSION"

# 2. Your platform: darwin-arm64 (Apple silicon), darwin-x64 (Intel Mac), linux-x64 or linux-arm64
NODARO_CLI_PLATFORM=darwin-arm64

# 3. Download. -f fails on an HTTP error instead of saving the error page as the binary.
curl -fL "https://github.com/nodaroai/app.nodaro.ai/releases/download/cli-v$NODARO_CLI_VERSION/nodaro-$NODARO_CLI_PLATFORM" \
  -o /usr/local/bin/nodaro && chmod +x /usr/local/bin/nodaro
nodaro --version
```

**Windows 바이너리**

PowerShell에서 최신 `cli-v` 태그를 찾은 다음 `nodaro-windows-x64.exe`를 내려받으세요.

```powershell
$v = (Invoke-RestMethod "https://api.github.com/repos/nodaroai/app.nodaro.ai/git/matching-refs/tags/cli-v?per_page=100") |
ForEach-Object { $_.ref -replace '^refs/tags/cli-v', '' } |
Where-Object { $_ -match '^\d+\.\d+\.\d+$' } |
Sort-Object { [version]$_ } | Select-Object -Last 1
Invoke-WebRequest "https://github.com/nodaroai/app.nodaro.ai/releases/download/cli-v$v/nodaro-windows-x64.exe" -OutFile nodaro.exe
.\nodaro.exe --version
```

버전을 고정하려면 첫 번째 단계를 건너뛰고 버전을 직접 지정하세요. 모든 CLI 릴리스와 바이너리는 공개 저장소의 [cli-v 릴리스](https://github.com/nodaroai/app.nodaro.ai/releases?q=cli-v)에 나와 있습니다.

## 로그인
CLI는 개인 API 토큰으로 인증하며, 토큰을 프로필에 저장합니다.

### 브라우저 로그인 시작
`nodaro auth login`을 실행하세요. CLI가 브라우저에서 Nodaro 인스턴스의 **Nodaro CLI 승인** 페이지를 엽니다.

### CLI 승인
필요하면 로그인한 다음 **승인**을 클릭하세요. Nodaro가 기기 이름을 딴 개인 API 토큰을 만들어 터미널로 돌려줍니다.

### 프로필 확인
`nodaro auth status`를 실행하세요. 프로필 이름, 인스턴스 주소, 그리고 가려진 토큰이 표시됩니다.

브라우저 흐름이 실패하면 CLI는 대신 토큰을 붙여 넣으라고 요청합니다. 토큰을 직접 만들려면 Nodaro에서 **설정 › API 토큰**을 열고 **토큰 만들기**를 클릭하세요. 전체 토큰은 한 번만 표시됩니다. 개인 API 토큰은 Nodaro Cloud와 Business 에디션 설치에서 쓸 수 있습니다. 토큰이 작동하는 방식은 [인증](https://nodaro.ai/docs/developers/api/authentication)에서 확인하세요.

```bash
nodaro auth login                                   # browser sign-in
nodaro auth login --no-browser                      # paste a token instead
nodaro auth login --token "$NODARO_TOKEN"           # non-interactive, for CI
nodaro auth status [--profile <name>] [--json]      # show a profile, token masked
nodaro auth logout [--profile <name>]               # delete a saved profile
```

| `auth login` 옵션 | 기능 |
| --- | --- |
| `--profile <name>` | 저장할 프로필입니다. 기본값은 `production`입니다. |
| `--token <token>` | 브라우저를 열거나 묻지 않고 이 토큰을 저장합니다. |
| `--base-url <url>` | Nodaro 인스턴스입니다. 기본값은 `https://app.nodaro.ai`입니다. |
| `--no-browser` | 브라우저를 건너뛰고 대신 토큰을 붙여 넣습니다. |

CLI는 프로필을 `~/.config/nodaro/config.json`에 저장하며, 이 파일은 내 사용자만 읽을 수 있습니다(파일 모드 `0600`). 파일을 다른 폴더에 두려면 `NODARO_CONFIG_DIR`을 설정하세요.

## 여러 인스턴스에 프로필 사용
**프로필**은 저장된 인스턴스 주소와 토큰입니다. Nodaro Cloud, 스테이징 설치, 로컬 설치처럼 인스턴스마다 프로필을 하나씩 만드세요. 그런 다음 모든 명령이 받는 `--profile`로 하나를 고르세요.

```bash
nodaro auth login --profile prod    --base-url https://app.nodaro.ai
nodaro auth login --profile staging --base-url https://staging.example.com
nodaro auth login --profile local   --base-url http://localhost:3000

nodaro projects list --profile staging
```

`--profile`이 없는 명령은 기본 프로필을 씁니다. 프로필을 저장하기 전까지 기본값은 `production`이며, 처음 저장한 프로필이 기본 프로필이 됩니다. 그래서 대부분은 플래그 없이 `nodaro auth login`을 한 번 실행하는 것으로 충분합니다.

## 워크스페이스 선택
조직이 있는 인스턴스에서는 작업이 **워크스페이스**에 있습니다. 명령 하나에는 `--workspace <id>`로, 셸이나 CI 작업에는 `NODARO_WORKSPACE`로 워크스페이스를 고르거나, `nodaro workspace use <id>`로 프로필에 저장하세요. 아무것도 설정하지 않으면 개인 공간에서 작업합니다. [워크스페이스와 조직](https://nodaro.ai/docs/developers/cli/workspaces)을 참고하세요.

## 실행하는 세 가지 방법
CLI는 Nodaro가 작업을 실행하는 세 가지 방법을 모두 다룹니다. 만든 것에 맞는 방법을 고르세요.

| 목표 | 명령 |
| --- | --- |
| 저장된 워크플로 실행 | `nodaro workflows run <workflowId>` |
| 다듬어진 입력과 출력을 갖춘 게시된 앱 실행 | `nodaro apps run <slug> --input key=value` |
| 워크플로 없이 단일 노드를 직접 실행 | `nodaro nodes run <type> --param key=value` |

`nodaro nodes run`은 `generate_image`, `generate_video` 같은 [MCP 서버](https://nodaro.ai/docs/mcp/tools)의 동사형 도구에 해당하는 CLI 명령입니다. 모든 생성 노드는 `POST /v1/<type>`에서 응답하므로, `nodaro nodes list`에 나오는 노드는 모두 `nodaro nodes run`으로 실행할 수 있습니다. REST 쪽은 [단일 노드 실행](https://nodaro.ai/docs/developers/api/nodes)을 참고하세요.

실행이 끝날 때까지 기다리려면 `--watch`를 추가하세요.

```bash
nodaro nodes run generate-image \
  --param prompt="a snow leopard on a mountain ridge, cinematic" \
  --param provider=flux \
  --watch
```

`--param` 문법은 [매개변수와 입력 파일](https://nodaro.ai/docs/developers/cli/params)에서 확인하고, CLI로 스크립트를 짜기 전에 [출력과 종료 코드](https://nodaro.ai/docs/developers/cli/output)를 읽어 보세요.

## CLI가 다루지 않는 것
CLI는 크레딧, 개발자 앱, OAuth, 파이프라인, Reduce, 업로드 도우미를 다루지 않습니다. 이런 기능에는 [SDK](https://nodaro.ai/docs/developers/sdk)나 [REST API](https://nodaro.ai/docs/developers/api)를 사용하세요.

CLI에서 코드로 옮겨 가는 것은 간단합니다. 다음은 `nodaro workflows run wf_abc`에 해당하는 SDK 코드입니다.

```ts

const nodaro = createClient({
baseUrl: "https://app.nodaro.ai",
auth: new StaticTokenAuth(process.env.NODARO_TOKEN!),
})

const run = await nodaro.workflows.run("wf_abc")
```

## 다음 단계
  - [명령](https://nodaro.ai/docs/developers/cli/commands): 
프로젝트, 세션, 워크플로, 앱, 노드, 모델, 프리셋, 작업, 갤러리, Webhook, 결제를 다루는 모든 핵심 명령입니다.
  
  - [매개변수와 입력 파일](https://nodaro.ai/docs/developers/cli/params): 
    --param, --input, --params-file이 텍스트를 요청 본문으로 바꾸는 방식입니다.
  
  - [출력과 종료 코드](https://nodaro.ai/docs/developers/cli/output): 
JSON 출력, --watch, 그리고 스크립트에서 분기할 때 쓰는 종료 코드입니다.
  
  - [예시](https://nodaro.ai/docs/developers/cli/examples): 
cron 작업, CI 게이트, 녹취록으로 만드는 자막, 프롬프트 마법사 활용법입니다.

## 자주 묻는 질문

### Nodaro CLI는 어떻게 설치하나요?

Node.js 20 이상에서 npm install -g @nodaro/cli를 실행하세요. Node.js가 없으면 공개 GitHub 저장소의 cli-v 릴리스에서 macOS, Linux, Windows용 독립 실행형 바이너리를 내려받으세요. 설치는 nodaro --version으로 확인합니다.

### Nodaro CLI에 로그인하려면 어떻게 하나요?

nodaro auth login을 실행하세요. 브라우저에서 Nodaro CLI 승인 페이지가 열리고, 승인을 클릭하면 CLI가 개인 API 토큰을 받습니다. CI 작업에서는 nodaro auth login --token으로 토큰을 직접 넘기세요.

### Nodaro CLI는 토큰을 어디에 저장하나요?

~/.config/nodaro/config.json에 저장하며, 파일 권한은 내 사용자만 읽을 수 있도록 설정됩니다. 파일을 다른 폴더에 두려면 NODARO_CONFIG_DIR 환경 변수를 설정하세요.

### 셀프 호스팅 Nodaro 설치에서도 CLI를 쓸 수 있나요?

네. --base-url을 내 설치 환경의 주소로 설정해 프로필을 저장하세요. 예를 들어 nodaro auth login --profile local --base-url http://localhost:3000을 실행한 다음, 명령에 --profile local을 붙이면 됩니다.

### CLI와 SDK 중 무엇을 써야 하나요?

터미널 작업, cron 작업, CI 파이프라인, 빠른 확인에는 CLI를 쓰세요. 코드로 작성하는 연동에는 TypeScript SDK를 쓰세요. CLI는 SDK를 얇게 감싼 것이므로, CLI가 하는 일은 SDK로도 모두 할 수 있습니다.