# Command-line tool (CLI)

> Install transcript1 to transcribe video links and local files from your terminal. Batch folders, save subtitles or return JSON for scripts and agents.

Canonical: https://transcript1.com/docs/cli
Last updated: 2026-11-01

Run `transcript1` with a YouTube, X, TikTok, Instagram, Facebook or Bluesky link, or a local audio or video file to get its transcript. Additional platforms and their client-version requirements are listed below. See [Sources and options](https://transcript1.com/docs/sources-and-options) for accepted platforms and restrictions. The standalone CLI needs no Node.js.

Use CLI 1.2.0 or newer for social links. CLI 1.1.0 and older accept only YouTube links and reject the new links locally. Run `transcript1 update` to update.

That version is the baseline for the original six platforms. Twitch, Dailymotion, Pinterest, LinkedIn and Snapchat require a CLI release that includes those platforms; older clients can reject them locally.

Social posts must be public. For posts with several videos, only the first video is transcribed. See [Sources and options](https://transcript1.com/docs/sources-and-options) for accepted short links and limits.

## Install

On macOS or Linux (x64 or ARM64):

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

The installer puts the binary in `~/.local/bin` and prints a PATH hint if needed. Set `TRANSCRIPT1_INSTALL_DIR` to choose another folder.

It also adds `t1`, a short alias for `transcript1`. If you use zsh, it adds `alias transcript1='noglob transcript1'` to `~/.zshrc` so links with `?` work unquoted; set `TRANSCRIPT1_NO_MODIFY_SHELL=1` to skip that.

On Windows x64, open PowerShell:

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

This installs to `%LOCALAPPDATA%\Programs\transcript1`, adds `t1.cmd` as a short alias and adds the folder to your user PATH. Open a new terminal to use it.

## Sign in

Run:

```bash
transcript1 login
```

This opens transcript1.com in your browser. Over SSH or without a display, it prints the link instead. Compare the code shown in your terminal with the one on the page, then click Approve. The CLI waits for approval and saves a key named `transcript1 CLI (<computer name>)`. You can find it on the [API keys page](https://transcript1.com/dashboard/account/tokens).

Use `transcript1 login --no-browser` to print the link without opening a browser.

To paste an existing key, run `transcript1 login --with-key`. Piped input still works: `transcript1 login < key.txt`.

For CI and agents, set `TRANSCRIPT1_API_KEY`; it takes priority over the saved key. An agent without a terminal or a key can run `transcript1 login < /dev/null` and send you the link to approve.

`transcript1 logout` revokes the CLI key and removes it from your computer. If revocation fails, it removes the saved key and asks you to revoke it on the API keys page. Pasted keys must be revoked on that page.

## Transcribe a link

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

The command waits for the transcript and prints text to stdout. It uses usable original-language captions from YouTube, X, TikTok, Bluesky, Dailymotion and LinkedIn when available and AI transcription otherwise. Progress goes to stderr.

Tip: in zsh, quote links. An unquoted `&` splits the command, and `?` is a glob unless you use the alias the installer adds.

## Transcribe a file

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

Files can be up to 2 GB (2,000,000,000 bytes). Supported extensions are mp3, wav, m4a, flac, ogg, opus, mp4, mov, webm and mkv. The CLI uploads the file and waits for the transcript.

## Batches

Pass several inputs or a folder:

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

File patterns like `recordings/*.mp3` work, also on Windows. Folders expand to their top-level media files, sorted by name. Several inputs write one file each to `./transcripts` by default. `--jobs` controls how many inputs run at once: 1–20, with a default of 2.

Use `-` to read one link or file path per line from stdin. In a shell on macOS or Linux:

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

Blank lines and lines starting with `#` are skipped. Exact duplicate inputs run once.

With one input, `-o` names an output file, or a folder if it already exists or ends in `/`. With several inputs, `-o` names a folder. Missing output folders are created.

YouTube links and local files whose output file already exists are skipped. Add `--overwrite` to redo them:

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

## Formats and options

| Option | Meaning |
|---|---|
| `-f`, `--format` | `text` (default), `srt`, `vtt` or `json`. JSON returns the API transcription object. |
| `--speakers` | Label speakers as Speaker 1, Speaker 2 and so on. |
| `--timestamps` | Put `[hh:mm:ss]` before each line. Text format only. |
| `--language` | An ISO 639-1 language code, or `auto` (default). |
| `--source` | `auto` (default) or `stt`. YouTube, X, TikTok, Bluesky, Dailymotion and LinkedIn also accept `captions` when a usable track exists; captions-only never downloads audio or falls back to STT. |
| `--fresh` | Do not reuse a link transcription from the last 24 hours. |

For speaker labels with timestamps:

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

`--speakers` cannot be combined with `--source captions`. With auto, speaker labels bypass captions. YouTube and X retain their existing caption behavior; TikTok, Bluesky, Dailymotion and LinkedIn also support available caption tracks. Non-YouTube captions have segment timing only (`words: null`), including auto-generated tracks. See [Sources and options](https://transcript1.com/docs/sources-and-options) for the capability matrix and language rules.

## Translate

Add `--translate <xx>` (a two-letter ISO 639-1 code such as `de`) to a transcription or to `get <id>` to also get a translation. Translation is free and uses 0 minutes; see [Translation](https://transcript1.com/docs/translation). Available from the CLI release after v1.2.0; run `transcript1 update`.

```bash
transcript1 --translate de -f srt -o talk.en-de.srt talk.mp3
transcript1 get --translate es --translation only <id>
```

`--translation both|only` needs `--translate`. `both` (default) is bilingual: SRT and VTT cues have two lines, the original and then the translation. `only` outputs the translation alone.

`get --translate` starts the translation if needed, also retries a failed one, and waits for it.

Output files are named `<name>.<xx>.<ext>` for `only` and `<name>.<orig>-<xx>.<ext>` for `both`. A file given with `-o <file>` is used as given.

A failed translation fails only that input (exit 1); other inputs continue. If the transcription has no such translation, the error is `no <xx> translation for <id>`.

## Scripts and agents

Agents with a shell can install the CLI, set `TRANSCRIPT1_API_KEY` and run `transcript1 <link>` or `transcript1 <file>`. For clients using MCP, see [MCP server setup](https://transcript1.com/docs/mcp).

Use `--json` for one JSON line per input on stdout as it finishes, with no progress, summary or update notice:

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

Each finished job is the API transcription object plus `input` and `reused`. When a transcript is written to a file, the line includes `file` and omits `transcript`. Errors before an id exists have `input` and an `error` object with `code` and `message`. Skipped inputs have `input`, `skipped` (`exists` or `out_of_minutes`) and `file` when applicable. `exists` applies only to YouTube links and local files.

With one input and no `-o`, `--json` includes the transcript in the object and ignores `-f`. With several inputs and no `-o`, transcripts go to `./transcripts` and each JSON line includes `file` instead of `transcript`. Whenever a file is written, `-f` selects its format. Use `-q` or `--quiet` to suppress progress and summaries while keeping transcript output and errors.

To start a job without waiting, then fetch it later:

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

Replace `<id>` with the id printed by the first command. `--no-wait` prints the id and status, or the object with `--json`. `get` waits while the job runs; it accepts `-f`, `-o`, `--timestamps`, `--no-wait`, `--json` and `-q`.

## Updates

```bash
transcript1 update
```

The CLI checks for a newer release at most once per 24 hours when stderr is a terminal and shows a notice if one is available. Set `TRANSCRIPT1_NO_UPDATE_CHECK=1` to disable the check. `--json` and `-q` also suppress it.

## Exit codes

| Code | Meaning |
|---|---|
| 0 | Every input succeeded or was skipped (YouTube links and local files with existing output). |
| 1 | At least one input failed or was skipped for lack of minutes. |
| 2 | Usage or sign-in problem. |
| 130 | Interrupted. |

Run `transcript1 --help` (or `transcript1` alone) for all commands and flags.