# CLI로 사용하기

> 터미널에서 영상 링크나 파일을 텍스트로 변환하세요. 폴더를 일괄 처리하고 자막을 저장하거나, 자동화 스크립트와 에이전트에 JSON을 전달할 수 있어요.

Canonical: https://transcript1.com/ko/docs/cli
Language: ko
Last updated: 2026-10-18

`transcript1` 명령 뒤에 영상 링크나 파일 경로를 넣으세요. YouTube, X, TikTok, Instagram, Facebook, Bluesky와 로컬 오디오·영상 파일을 텍스트로 변환할 수 있어요. 추가 플랫폼은 아래의 버전 조건을 확인하세요. 링크별 지원 범위는 [지원 링크와 변환 옵션](https://transcript1.com/ko/docs/sources-and-options)에 있어요. CLI는 단독 실행 파일이므로 Node.js 없이 설치할 수 있어요.

YouTube 외 소셜 링크를 쓰려면 CLI 1.2.0 이상이 필요해요. 1.1.0 이하는 YouTube 링크만 지원하며 다른 링크는 서버에 보내기 전에 거부해요. `transcript1 update`로 업데이트하세요.

1.2.0은 처음 지원한 여섯 플랫폼의 최소 버전이에요. Twitch, Dailymotion, Pinterest, LinkedIn, Snapchat을 쓰려면 해당 플랫폼 지원이 추가된 릴리스가 필요해요. 구버전에서는 링크를 서버에 보내기 전에 거부할 수 있어요.

공개 게시물만 사용할 수 있고, 영상이 여러 개면 첫 번째 영상만 변환해요. 단축 링크의 지원 형식과 한도는 [지원 링크와 변환 옵션](https://transcript1.com/ko/docs/sources-and-options)에서 확인하세요.

## CLI 설치하기

macOS와 Linux의 x64·ARM64 환경에서는 아래 명령을 실행하세요.

```bash
curl -fsSL https://transcript1.com/install.sh | sh
```

실행 파일은 `~/.local/bin`에 설치해요. PATH 설정이 필요하면 설치 후 안내해 드려요. 설치 폴더를 바꾸려면 `TRANSCRIPT1_INSTALL_DIR`을 지정하세요.

짧은 명령어 `t1`도 함께 설치해요. zsh에서는 `~/.zshrc`에 `alias transcript1='noglob transcript1'`을 추가해 `?`가 있는 링크도 따옴표 없이 쓸 수 있게 해요. 셸 설정 파일을 수정하지 않으려면 `TRANSCRIPT1_NO_MODIFY_SHELL=1`을 설정하세요.

Windows x64에서는 PowerShell에서 아래 명령을 실행하세요.

```powershell
irm https://transcript1.com/install.ps1 | iex
```

설치 위치는 `%LOCALAPPDATA%\Programs\transcript1`이에요. 짧은 명령어인 `t1.cmd`를 추가하고 설치 폴더를 사용자 PATH에 등록해요. 설치 후 새 터미널을 열어 사용하세요.

## 계정 연결하기

먼저 로그인 명령을 실행하세요.

```bash
transcript1 login
```

브라우저에서 transcript1.com을 열어요. SSH로 접속했거나 화면이 없는 환경이면 대신 링크를 출력해요. 터미널과 웹페이지의 코드가 같은지 확인하고 “Approve”를 누르세요. 승인하면 CLI가 `transcript1 CLI (<computer name>)`이라는 키를 저장해요. 대시보드의 [“API keys” 페이지](https://transcript1.com/dashboard/account/tokens)에서도 이 키를 확인할 수 있어요.

링크만 받고 브라우저를 자동으로 열지 않으려면 `transcript1 login --no-browser`를 실행하세요.

기존 API 키로 연결하려면 `transcript1 login --with-key`를 실행한 뒤 키를 붙여넣으세요. `transcript1 login < key.txt`처럼 표준 입력으로 전달할 수도 있어요.

CI나 에이전트 환경에서는 `TRANSCRIPT1_API_KEY`를 설정하세요. 이 값이 있으면 저장된 키 대신 사용해요. 터미널이나 키가 없는 에이전트도 `transcript1 login < /dev/null`로 승인 링크를 받아 사용자에게 전달할 수 있어요.

`transcript1 logout`을 실행하면 CLI 키를 폐기하고 컴퓨터에 저장한 키도 지워요. 서버에서 폐기하지 못한 경우에는 로컬 키를 지운 뒤 “API keys” 페이지에서 직접 폐기하도록 안내해요. 직접 붙여넣은 키는 로그아웃과 별도로 해당 페이지에서 폐기해야 해요.

## 영상 링크 변환하기

```bash
transcript1 'https://youtu.be/dQw4w9WgXcQ'
```

스크립트가 준비되면 텍스트를 stdout에 출력해요. YouTube, X, TikTok, Bluesky, Dailymotion, LinkedIn에서는 영상 원본 언어의 자막을 우선 사용하고, 사용할 자막이 없으면 AI 텍스트 변환을 실행해요. 기다리는 동안의 진행 상황은 stderr에 표시해요.

zsh에서는 링크를 따옴표로 감싸는 게 안전해요. 따옴표가 없으면 `&`에서 명령이 나뉘어요. `?`도 설치 시 추가한 별칭을 쓰지 않으면 파일 검색 패턴으로 해석해요.

## 로컬 파일 변환하기

```bash
transcript1 interview.mp3
transcript1 -f srt -o interview.srt interview.mp3
```

파일 경로를 주면 CLI가 업로드한 뒤 스크립트가 완성될 때까지 기다려요. 최대 크기는 2GB(2,000,000,000바이트)예요. mp3, wav, m4a, flac, ogg, opus, mp4, mov, webm, mkv 확장자를 지원해요.

## 여러 파일과 링크 한꺼번에 처리하기

파일·링크를 여러 개 나열하거나 폴더 경로를 넣으세요.

```bash
transcript1 interview.mp3 lecture.mp4
transcript1 -o transcripts/ ./recordings
transcript1 --jobs 4 -o transcripts/ interview.mp3 'https://youtu.be/dQw4w9WgXcQ'
```

`recordings/*.mp3` 같은 파일 패턴은 Windows에서도 사용할 수 있어요. 폴더를 지정하면 그 폴더 바로 아래의 미디어 파일을 이름순으로 처리해요. 입력이 여러 개면 기본적으로 `./transcripts`에 각각의 스크립트를 저장해요. 동시 처리 수는 `--jobs`로 1~20 사이에서 지정하세요. 기본값은 2예요.

입력에 `-`를 넣으면 stdin에서 한 줄에 하나씩 링크나 파일 경로를 읽어요. macOS와 Linux 셸에서는 아래처럼 파일 목록을 전달할 수 있어요.

```bash
transcript1 -o transcripts/ - < inputs.txt
```

빈 줄이나 `#`로 시작하는 줄은 무시해요. 같은 입력이 반복돼도 한 번만 처리해요.

입력이 하나면 `-o`에 저장할 파일 이름을 지정하세요. 다만 기존 폴더를 가리키거나 경로가 `/`로 끝나면 폴더로 사용해요. 입력이 여러 개일 때는 `-o`가 저장 폴더를 뜻해요. 폴더가 없으면 자동으로 만들어요.

YouTube 링크나 로컬 파일의 스크립트가 지정한 경로에 이미 있으면 해당 입력을 건너뛰어요. 다시 변환해서 덮어쓰려면 `--overwrite`를 붙이세요.

```bash
transcript1 --overwrite -o transcripts/ ./recordings
```

## 출력 형식과 변환 옵션

| 옵션 | 용도 |
|---|---|
| `-f`, `--format` | `text`(기본값), `srt`, `vtt`, `json` 중 출력 형식을 골라요. JSON은 API의 변환 작업 객체예요. |
| `--speakers` | 화자 분리를 켜면 Speaker 1, Speaker 2처럼 표시해요. |
| `--timestamps` | 텍스트의 각 줄 앞에 `[hh:mm:ss]`를 붙여요. text 형식에서만 가능해요. |
| `--language` | ISO 639-1 언어 코드로 지정하세요. 기본값은 `auto`예요. |
| `--source` | 기본값은 `auto`이며 `stt`도 가능해요. YouTube, X, TikTok, Bluesky, Dailymotion, LinkedIn에서 사용할 자막이 있으면 `captions`도 쓸 수 있어요. `captions`(자막만)는 오디오를 다운로드하거나 STT로 전환하지 않아요. |
| `--fresh` | 최근 24시간 내 같은 링크의 스크립트가 있어도 재사용하지 않고 새로 변환해요. |

화자 분리와 타임스탬프를 함께 적용하는 예제예요.

```bash
transcript1 --speakers --timestamps --language en interview.mp3
```

`--speakers`와 `--source captions`는 함께 사용할 수 없어요. auto에서 화자 분리를 켜면 자막을 건너뛰고 음성을 변환해요. YouTube와 X의 기존 자막 처리는 그대로이며 TikTok, Bluesky, Dailymotion, LinkedIn에서도 자막을 가져올 수 있어요. YouTube 외 플랫폼은 자동 생성 자막도 타임스탬프를 세그먼트 단위로만 제공해요(`words: null`). 플랫폼별 기능과 언어 선택 기준은 [지원 링크와 변환 옵션](https://transcript1.com/ko/docs/sources-and-options)을 확인하세요.

## 스크립트와 에이전트에서 자동화하기

에이전트가 셸을 사용할 수 있다면 CLI를 설치하고 `TRANSCRIPT1_API_KEY`를 설정하세요. 이후 `transcript1 <link>`나 `transcript1 <file>`을 실행하면 돼요. MCP 클라이언트로 연결하려면 [MCP 서버 연결](https://transcript1.com/ko/docs/mcp)을 확인하세요.

자동화에는 `--json`을 사용하세요. 입력 하나의 처리가 끝날 때마다 stdout에 JSON을 한 줄씩 출력해요. 진행 상황, 요약, 업데이트 알림은 표시하지 않아요.

```bash
transcript1 --json 'https://youtu.be/dQw4w9WgXcQ'
```

완료된 입력의 JSON은 API 작업 객체에 `input`, `reused`를 더한 형태예요. 스크립트를 파일에 저장했다면 `transcript` 대신 `file` 경로를 넣어요. 작업 ID가 생기기 전에 오류가 나면 `input`과 `error` 객체를 출력하며, 오류 안에는 `code`, `message`가 있어요.

건너뛴 입력에는 `input`과 `skipped`가 있어요. 건너뛴 이유는 `exists` 또는 `out_of_minutes`이고, 해당하는 경우 `file`도 포함해요. `exists`는 YouTube 링크와 로컬 파일에만 사용해요.

입력이 하나이고 `-o`가 없으면 `--json`은 객체에 스크립트까지 담고 `-f`는 무시해요. 입력이 여러 개이고 `-o`가 없으면 스크립트 파일은 `./transcripts`에 저장해요. 이때 각 JSON 줄에는 `transcript` 대신 `file`이 들어가요. 파일로 저장할 때의 형식은 항상 `-f`로 정해요.

스크립트와 오류만 출력하고 진행 상황·요약을 숨기려면 `-q`나 `--quiet`를 쓰세요.

작업만 시작하고 스크립트는 나중에 가져올 수도 있어요.

```bash
transcript1 --no-wait interview.mp3
transcript1 get <id>
```

첫 명령에서 받은 ID를 `<id>`에 넣으세요. `--no-wait`는 ID와 상태만 출력해요. `--json`을 함께 쓰면 객체를 출력해요. `get`은 작업이 끝날 때까지 기다려 가져오며, `-f`, `-o`, `--timestamps`, `--no-wait`, `--json`, `-q` 옵션을 지원해요.

## 최신 버전으로 업데이트하기

```bash
transcript1 update
```

stderr가 터미널에 연결돼 있으면 최대 24시간에 한 번 새 버전을 확인하고 업데이트 알림을 표시해요. 버전 확인 자체를 끄려면 `TRANSCRIPT1_NO_UPDATE_CHECK=1`을 설정하세요. `--json`이나 `-q`를 사용할 때도 업데이트 알림은 표시하지 않아요.

## 종료 코드

| 코드 | 종료 이유 |
|---|---|
| 0 | 모두 성공했거나, 스크립트 파일이 이미 있는 YouTube 링크·로컬 파일을 건너뛰었어요. |
| 1 | 하나 이상 실패했거나 사용 가능한 분량이 부족해 건너뛰었어요. |
| 2 | 명령 사용법 또는 로그인에 문제가 있어요. |
| 130 | 실행을 중단했어요. |

전체 명령과 옵션은 `transcript1 --help`로 확인하세요. 인자 없이 `transcript1`만 실행해도 도움말이 나와요.