---
title: CLI | RunAPI
description: 모델 작업, Tasks, Files, Uploads, 계정 정보, 가격, 콜백 및 Harness를 위한 모든 RunAPI CLI
  명령을 설치하고 사용합니다.
url: https://runapi.ai/ko/docs/resources/cli.md
canonical: https://runapi.ai/ko/docs/resources/cli
locale: ko
---

> HTML 버전: https://runapi.ai/ko/docs/resources/cli
> 에이전트용 사이트 색인: https://runapi.ai/llms.txt

# CLI

RunAPI CLI는 모델 액션 및 계정 도구를 위한 JSON 우선 터미널 클라이언트입니다. 결과 데이터는 표준 출력에, 운영 진행 상황은 표준 오류에 기록하므로 터미널, 셸 스크립트, CI 작업 및 Harness에서 모두 동일하게 사용할 수 있습니다.

## 설치

Linux 또는 macOS에 현재 릴리스를 설치하세요:

```shell
curl -fsSL https://runapi.ai/cli/install.sh | sh
```

Homebrew 및 Go 소스 설치도 가능합니다:

```shell
brew install runapi-ai/tap/runapi
go install github.com/runapi-ai/cli/cmd/runapi@latest
```

Windows에서는 [최신 CLI 릴리스][1]에서 해당하는 `windows-amd64` 또는
`windows-arm64` 아카이브를 다운로드하고, `runapi.exe`를 압축 해제한 후
`PATH`에 추가하십시오.



[1]: https://github.com/runapi-ai/cli/releases/latest

배포 시 재현 가능한 바이너리가 필요한 경우, 인스톨러를 특정 버전 또는
설치 디렉터리에 고정하세요:

```shell
curl -fsSL https://runapi.ai/cli/install.sh | sh -s -- --version v0.13.1
curl -fsSL https://runapi.ai/cli/install.sh | sh -s -- --dir "$HOME/.local/bin"
```

설치 프로그램은 `RUNAPI_VERSION`, `RUNAPI_INSTALL_DIR`, `RUNAPI_INSTALL_BASE`, `RUNAPI_DOWNLOAD_BASE`, `RUNAPI_SKIP_LIBC_CHECK=1`도 허용합니다.

## 빠른 시작

워크스테이션에서 브라우저로 로그인하고 자격 증명 소스를 확인하십시오:

```shell
runapi login
runapi auth status
```

인라인 JSON 입력 또는 JSON 파일로 모델 작업을 실행합니다:

```shell
runapi nano-banana text-to-image --input '{"prompt":"a hummingbird drinking espresso","aspect_ratio":"1:1"}'
runapi nano-banana text-to-image --input-file request.json
```

대부분의 모델 액션은 비동기입니다. 기본적으로 종료 결과를 기다리며,
`--async`를 추가하면 Task를 즉시 반환하고 나중에 `wait`을 사용할 수 있습니다:

```shell
TASK_ID=$(runapi suno text-to-music --async --input '{"model":"suno-v5","vocal_mode":"instrumental","style":"minimal piano","title":"Short Piano Theme"}' | jq -r '.id')
runapi wait "$TASK_ID" --service suno --action text-to-music
```

## 명령어 규칙

모든 명령은 옵션이 `files create --url-only` 또는 `listen
--print-secret`과 같이 스칼라 값을 명시적으로 요청하지 않는 한 표준 출력에 JSON을 출력합니다. 진행 및 진단 메시지는 표준 오류에 남으므로 JSON은 `jq`로 안전하게 전달할 수 있습니다:

```shell
runapi nano-banana text-to-image --input-file request.json \
  | jq -r '.images[].url' \
  | xargs -I{} curl -OL {}
```

모델 액션은 정확히 하나의 요청 입력 소스를 허용합니다:

* `--input '<json object>'`는 인라인 JSON을 제공합니다.
* `--input-file path/to/request.json`은 파일에서 JSON을 로드합니다.
* `--input-file -`는 표준 입력에서 JSON을 읽습니다.

요청을 구성하기 전에 `runapi <service> <action> --help`를 사용하세요.
설치된 CLI는 액션의 현재 필드, 허용되는 모델 식별자, 유효성 검사 제약 조건을
나열합니다.

다음 전역 옵션은 모든 명령에 적용됩니다:

| 옵션 | 용도 |
|----------
| `--api-key` | 이 실행에 API 키를 사용합니다. `RUNAPI_API_KEY`를 재정의합니다. |
| `--base-url` | 이 실행에 다른 API 오리진을 사용합니다. |
| `--timeout` | 전체 명령 타임아웃 및 최대 작업 대기 시간을 설정합니다. 기본값은 15분입니다. |
| `--poll-interval` | 작업 폴링 간격을 설정합니다. 기본값은 3초입니다. |
| `--async` | 비동기 모델 작업 제출 후 즉시 반환합니다. |
| `--quiet` | JSON 출력을 변경하지 않고 표준 오류의 진행 상황 출력을 억제합니다. |

## 모델 액션

모델 명령 형식은 `runapi <service> <action>`입니다. 동기 액션은 응답을 즉시 반환합니다. 비동기 액션의 경우 기본 동작은 제출, 폴링 후 터미널 Task 결과를 반환하는 것이며, `--async`는 생성 응답을 대신 반환합니다.

최상위 미디어 URL 필드의 경우, 읽을 수 있는 로컬 파일 경로는 모델 작업이 실행되기 전에 업로드됩니다. 기존 `http://` 및 `https://` URL은
변경 없이 전송됩니다. 재사용 가능한 임시
URL이 필요하거나, 소스가 원격 URL이거나, 소스가 Base64 데이터인 경우 `files create`를 사용하세요.

### 오디오 및 음악 작업

* `suno`: `add-instrumental`, `add-vocals`, `blend-lyrics`,
  `boost-style`, `check-voice`, `convert-audio`, `cover-audio`,
  `create-mashup`, `extend-music`, `generate-artwork`,
  `generate-lyrics`, `generate-midi`, `generate-persona`,
  `generate-voice`, `get-timestamped-lyrics`,
  `regenerate-validation-phrase`, `replace-section`,
  `separate-audio-stems`, `text-to-music`, `text-to-sound`,
  `visualize-music`, `voice-to-validation-phrase`
* `producer`: `text-to-music`
* `gemini-omni`: `create-audio`, `create-character`, `text-to-video`
* `openai-tts`: `text-to-speech`
* `fish-audio`: `text-to-speech`
* `gemini-tts`: `text-to-speech`
* `elevenlabs`: `isolate-audio`, `speech-to-text`, `text-to-dialogue`,
  `text-to-sound`, `text-to-speech`

### 이미지 작업

* `nano-banana`: `edit-image`, `text-to-image`
* `imagen-4`: `remix-image`, `text-to-image`
* `seedream`: `decompose-layers`, `edit-image`, `text-to-image`
* `flux`: `remix-image`, `text-to-image`
* `flux-2`: `remix-image`, `text-to-image`
* `flux-kontext`: `text-to-image`
* `qwen-2`: `edit-image`, `text-to-image`
* `qwen-3`: `edit-image`, `text-to-image`
* `qwen-image`: `edit-image`, `remix-image`, `text-to-image`
* `recraft`: `remove-background`, `upscale-image`
* `z-image`: `text-to-image`
* `ideogram-v3`: `edit-image`, `reframe-image`, `remix-image`,
  `text-to-image`
* `gpt-image`: `edit-image`, `text-to-image`
* `gpt-image-2`: `edit-image`, `text-to-image`
* `gpt-4o-image`: `text-to-image`
* `midjourney`: `edit-image`, `get-seed`, `image-to-prompt`,
  `shorten-prompt`, `text-to-image`

### 비디오 및 애니메이션 작업

* `veo-3-1`: `extend-video`, `text-to-video`, `upscale-video`
* `seedance`: `text-to-video`
* `runway`: `extend-video`, `text-to-video`
* `runway-aleph`: `edit-video`
* `kling`: `avatar`, `edit-video`, `extend-video`, `image-to-video`,
  `motion-control`, `text-to-video`
* `infinitetalk`: `audio-to-video`
* `omnihuman`: `audio-to-video`, `human-identification`,
  `subject-detection`
* `wan`: `animate`, `edit-video`, `image-to-video`, `speech-to-video`,
  `text-to-image`, `text-to-video`
* `luma`: `modify-video`
* `hailuo`: `image-to-video`, `text-to-video`
* `volcengine-lip-sync`: `lip-sync-video`
* `happyhorse`: `edit-video`, `image-to-video`, `text-to-video`
* `grok-imagine`: `edit-image`, `extend`, `image-to-video`,
  `text-to-image`, `text-to-video`, `upscale-image`
* `topaz`: `upscale-image`, `upscale-video`
* `midjourney`: `extend-video`, `image-to-video`

위 목록은 이 CLI 릴리스의 완전한 액션 목록입니다. 각 액션의 정확한 요청 및 응답 계약은 [API 레퍼런스](https://runapi.ai/ko/docs/api/openai/chat-completions.md)에서 확인할 수 있으며, 로컬 명령 도움말이 버전별 필드의 출처입니다.

## 작업 생명주기

`get`을 사용하면 대기 없이 비동기 Task의 현재 상태를 조회할 수 있습니다.
`wait`을 사용하면 완료, 실패, 또는 명령 타임아웃에 도달할 때까지 폴링합니다.
두 명령 모두 CLI가 올바른 Task 결과 형식을 선택할 수 있도록 원래 서비스와
액션이 필요합니다.

```shell
runapi get "$TASK_ID" --service suno --action text-to-music
runapi wait "$TASK_ID" --service suno --action text-to-music --poll-interval 5s
```

## 파일

`runapi files create`는 임시 파일 업로드 URL 흐름을 유지합니다. 로컬 경로, 원격 URL,
또는 Base64 소스 하나를 업로드하고 한 시간 후 만료되는 URL을 반환합니다.

```shell
runapi files create ./reference.png --url-only
runapi files create --url https://example.test/reference.png --file-name reference.png
runapi files create --base64 "$(base64 < reference.png)" --file-name reference.png
```

소스 선택지는 상호 배타적입니다. `--url-only`는 URL만 출력하며, 전체 JSON 응답을 받으려면 이를 생략하세요.

URL 대신 안정적인 `file_id`가 필요할 때 영구 File 라이프사이클을 사용하세요:

```shell
runapi files create-file ./knowledge.pdf
runapi files list --order desc
runapi files retrieve file_123
runapi files content file_123 --output ./knowledge-copy.pdf
runapi files delete file_123
```

`content`는 `--output`이 필요합니다. `-`를 전달하면 정확한 File 바이트를 표준 출력에 씁니다.
제한 사항, 계정 격리, REST 수명 주기에 대해서는 [파일 및 업로드](https://runapi.ai/ko/docs/resources/files.md)를 참조하세요.

## 업로드

최종 File을 구성하기 전에 Uploads를 사용하여 하나 이상의 Part를 전송하세요.
Create는 최종 바이트 수와 메타데이터를 선언하며, 완료 시 구성 순서에 따라
`--part-id`를 반복하세요:

```shell
runapi uploads create --bytes 1048576 --filename archive.bin --mime-type application/octet-stream
runapi uploads add-part upload_123 ./archive.part-01
runapi uploads complete upload_123 --part-id part_123
runapi uploads cancel upload_123
```

## 계정 및 요금

인증된 사용자와 선택된 Account를 검사한 후 잔액
및 지출 카운터를 조회하세요:

```shell
runapi account info
runapi account balance
```

`pricing list`는 현재 가격 일정을 읽습니다. 서비스, 액션, 모델로 필터링할 수 있습니다.
`pricing quote`는 필요한 서비스와 액션에 대한 작업 예약 비용을 추정합니다. 액션이 모델별로
다른 경우 `--model`을 추가하고, `--params` 또는 `--params-file`로 가격 입력값을 제공하세요.

```shell
runapi pricing list --service suno --action text-to-music --model suno-v4
runapi pricing quote --service suno --action text-to-music --model suno-v4 \
  --params '{"vocal_mode":"auto_lyrics","prompt":"A chill lo-fi beat"}'
runapi pricing quote --service suno --action text-to-music --params-file pricing-inputs.json
```

가격 명령은 견적이 계정 소유의 소스 태스크를 참조하는 경우를 제외하고 자격 증명이 필요하지 않습니다.

## 인증 및 구성

`runapi login`은 브라우저 인증 흐름을 열고 결과 자격 증명을 저장합니다. 서버 및 CI 환경에서는
`auth import-token`이 표준 입력에서 API 키를 받아 기본적으로 검증하고, 프로세스 목록이나
셸 기록에 값을 노출하지 않고 저장합니다:

```shell
printf '%s' "$RUNAPI_API_KEY" | runapi auth import-token --token -
runapi auth status
runapi logout
```

`auth import-token --skip-verify`는 오프라인 이미지 설정을 지원합니다. 설정 중에 검증을 실행할 수 없는 경우에만
사용하세요. `auth status`는 나중에 활성 자격 증명을 확인합니다.

API 키 우선순위는 `--api-key`, 다음으로 `RUNAPI_API_KEY`, 그 다음으로 로컬 CLI 구성 파일 순입니다. Base URL 우선순위는 `--base-url`, 다음으로 `RUNAPI_BASE_URL`, 그 다음으로 저장된 Base URL, 마지막으로 `https://runapi.ai` 순입니다. 구성 파일은 `~/.config/runapi/config.json`이며, `XDG_CONFIG_HOME`이 설정된 경우 `$XDG_CONFIG_HOME/runapi/config.json`입니다.

## 로컬 콜백 리스너

`runapi listen`은 선택한 API 키 하나에 대한 작업 콜백을 수신하고, 선택적으로 서명된 각
콜백을 로컬 HTTP 엔드포인트로 전달합니다. 리스너 작업을 사용하려면 브라우저 로그인이 필요합니다.

```shell
runapi login
runapi api-keys list --json
runapi listen http://localhost:3000/webhooks/runapi --callback-api-key-id token_abc123
```

위치 URL과 `--forward-to`는 대안입니다. 리스너는 서명된 각 콜백 본문을 표준 출력에 기록합니다. `callback_url`이 있는 Task는 해당 URL로 계속 전달되며 로컬 리스너에도 복사됩니다.

유효한 리스너 이벤트를 수신한 후, CLI는 로컬 HTTP 요청을 시도하기 전에 이를 확인합니다. 각 이벤트는 로컬에서 한 번만 전달됩니다. 2xx가 아닌 응답이나 연결 오류는 터미널에 보고되지만, 리스너가 이벤트를 재전송하지는 않습니다. 이 로컬 디버깅 동작은 Task의 `callback_url`에 대한 전달 재시도에 영향을 주지 않습니다.

각 계정은 콜백 구독 키당 최대 100개의 활성 리스너와 총 1,000개의 활성 리스너를 실행할 수 있습니다. 한도에 도달하면 유휴 리스너를 중지하거나 잠시 후 다시 시도하세요. API 응답은 선택된 키, 계정, 또는 전체 서비스 용량이 가득 찼는지 여부를 알려줍니다.

유휴 리스너는 약 15~30초마다 새 이벤트를 확인합니다. 이벤트는 보통 약 15초 내에 발견되며, 사용 가능한 경우 즉시 읽힙니다. 제한에 도달하면 유휴 리스너를 중단하거나 잠시 기다렸다가 다시 시도하십시오. 기존의 전달 및 확인 동작은 변경되지 않습니다.

키 선택 순서는 다음과 같습니다. 단일 명령에 대해 `--callback-api-key-id`, 프로젝트 `.runapi.toml`의 `callback_api_key_id`, 그 다음 대화형 선택기. 프로젝트 구성은 Git 루트 또는 Git 저장소 외부의 현재 디렉터리에 저장되며 안정적인 ID만 포함합니다:

```toml
callback_api_key_id = "token_abc123"
```

리스너를 시작하지 않고 선택한 키의 Listen 서명 시크릿을 출력하거나, 노출 후 교체합니다:

```shell
runapi listen --print-secret --callback-api-key-id token_abc123
runapi listen --rotate-secret --callback-api-key-id token_abc123
```

교체는 선택한 키의 활성 리스너를 무효화합니다. 리스너를 재시작하기 전에 새로 출력된 시크릿으로 모든 로컬 검증자를 업데이트하세요.

## Harness

지원되는 Harness에 이식 가능한 RunAPI CLI 스킬을 설치하고, 지원되는 대상을 검사하거나, 설치된 스킬을 제거합니다:

```shell
runapi agent install-skill --target codex
runapi agent list-targets
runapi agent uninstall-skill --target codex
```

기본 제공 대상은 `claude`, `codex`, `gemini`, `openclaw`, `hermes`입니다.
`install-skill`은 스킬 릴리스를 고정하기 위한 `--version`, 사용자 지정 대상 디렉터리를 위한
`--target-dir`, 소스 저장소를 위한 `--source`, 기존 스킬 디렉터리를 덮어쓰기 위한
`--force`를 허용합니다.

## 셸 자동 완성 및 버전

Bash, Zsh, Fish 또는 PowerShell에 대한 완성 스크립트를 생성합니다. 예를 들어
현재 셸에서 Bash 완성을 로드하려면:

```shell
source <(runapi completion bash)
runapi completion zsh
runapi completion fish
runapi completion powershell
runapi version
```

명령 목록은 `runapi --help`를, 명령의 옵션은 `runapi <command> --help`를,
모델 액션의 필드는 `runapi <service> <action> --help`를 사용하세요.

## 종료 코드

명령어는 스크립트에서 처리할 수 있는 0이 아닌 코드와 함께 종료됩니다:

| 코드 | 의미 |
|----------
| `0` | 성공 |
| `2` | 인증 실패 또는 지원하지 않는 플랫폼 |
| `3` | 크레딧 부족 또는 필수 로컬 의존성 누락 |
| `4` | 유효성 검사 오류, 리소스를 찾을 수 없음, 또는 매니페스트 파싱 오류 |
| `5` | 타임아웃, 다운로드 실패, 또는 체크섬 불일치 |
| `6` | 요청 횟수 초과(속도 제한) |
| `7` | 작업 실패 |

요청 필드, Task 상태 값, 콜백 페이로드, 오류 본문,
속도 제한 처리에 대해서는 [API
참조](https://runapi.ai/ko/docs/api/openai/chat-completions.md)를 계속하세요. 동일한 워크플로가 애플리케이션 내부에 속하는 경우
[SDK](https://runapi.ai/ko/docs/resources/sdks.md)를 사용하세요.

---

## RunAPI의 더 많은 정보

- [홈](https://runapi.ai/ko/.md)
- [모델 카탈로그](https://runapi.ai/ko/models.md)
- [요금](https://runapi.ai/ko/pricing.md)
- [제공사](https://runapi.ai/ko/models)
- [문서](https://runapi.ai/ko/docs/guides)
- [SDK](https://runapi.ai/ko/sdk.md)
- [CLI](https://runapi.ai/ko/cli.md)
- [MCP Server](https://runapi.ai/ko/mcp.md)
- [Claude Code와 Cursor](https://runapi.ai/ko/claude-code-vs-cursor.md)
- [Cursor API 설정](https://runapi.ai/ko/cursor-api-setup.md)
- [RunAPI와 OpenRouter 비교](https://runapi.ai/ko/openrouter-alternative.md)
- [엔터프라이즈](https://runapi.ai/ko/contact.md)
- [문의](https://runapi.ai/ko/contact.md)
- [약관](https://runapi.ai/ko/terms.md)
- [개인정보](https://runapi.ai/ko/privacy.md)
- [에이전트용 사이트 색인](https://runapi.ai/llms.txt)

문의: contact@runapi.ai

## 구조화된 데이터

```json
[
  {
    "@context": "https://schema.org",
    "inLanguage": "ko",
    "@type": "WebSite",
    "name": "RunAPI",
    "url": "https://runapi.ai/ko",
    "potentialAction": {
      "@type": "SearchAction",
      "target": {
        "@type": "EntryPoint",
        "urlTemplate": "https://runapi.ai/ko/models?q={search_term_string}"
      },
      "query-input": "required name=search_term_string"
    }
  },
  {
    "@context": "https://schema.org",
    "inLanguage": "ko",
    "@type": "Organization",
    "name": "RunAPI",
    "url": "https://runapi.ai/ko",
    "logo": {
      "@type": "ImageObject",
      "url": "https://runapi.ai/koicon.svg"
    },
    "sameAs": [
      "https://github.com/runapi-ai"
    ]
  },
  {
    "@context": "https://schema.org",
    "inLanguage": "ko",
    "@type": "TechArticle",
    "headline": "CLI",
    "description": "모델 작업, Tasks, Files, Uploads, 계정 정보, 가격, 콜백 및 Harness를 위한 모든 RunAPI CLI 명령을 설치하고 사용합니다.",
    "url": "https://runapi.ai/ko/docs/resources/cli",
    "mainEntityOfPage": "https://runapi.ai/ko/docs/resources/cli"
  }
]
```