TubeTube CLI: make AI videos from your terminal

Installation

Nothing to install: npx fetches the latest version each time it runs. Install it globally if you use it daily.

npx tubetube --help

# or, to keep it around
npm install -g tubetube
tubetube version

Node.js 18.17 or newer is the only requirement, on macOS, Linux or Windows. The package has zero dependencies, so nothing else lands in your node_modules.

Authentication

Create a key on your Account page, then log in once.

tubetube login                    # asks for the key and verifies it
tubetube login --key tt_live_…    # non-interactive
tubetube whoami                   # account, plan, credits
tubetube logout                   # forget the stored key

The key is stored in ~/.tubetube/config.json with owner-only permissions. It is shown in full only once, at creation: the server keeps a SHA-256 hash of it, never the key itself. Revoking a key on the Account page takes effect immediately.

A key can create, read, download and delete videos on your account. It can never use operator-only settings such as automatic publishing to Google Drive, even on an admin account.

Quickstart

npx tubetube login
npx tubetube styles                       # pick a look
npx tubetube create --title "Counting song" \
    --style "Pixar-style 3D" \
    --lyrics-file song.txt \
    --scene-duration 5 \
    --dry-run                             # what would it cost?

npx tubetube create --title "Counting song" \
    --style "Pixar-style 3D" \
    --lyrics-file song.txt \
    --scene-duration 5 \
    --wait --download                     # launch, follow, save the mp4

Global flags

Every command exits with a non-zero status on failure, including watch when the generation itself fails, so a script stops on its own. Unknown options are rejected rather than ignored: a typo cannot silently change your settings and waste credits.

Commands

create

Builds the parameters, asks the server for a price, then launches. Credits are reserved at launch and whatever is not produced is refunded when the job ends.

# Price it, launch nothing
tubetube create --title "My song" --style "Pixar-style 3D" \
    --lyrics-file song.txt --dry-run

# Launch and follow until the file is on disk
tubetube create --title "My song" --style "Pixar-style 3D" \
    --lyrics-file song.txt --wait --download

# Same recipe as a previous video, new words
tubetube create --from a1b2c3d4 --lyrics-file new-song.txt --wait

# Text from stdin
cat script.txt | tubetube create --type narration --style "Watercolor storybook"

The text comes from --lyrics, --lyrics-file, stdin, or the video referenced by --from. The visual style is required: pass --style with a preset name or --style-text with your own prompt.

list

Your videos, newest first. Ids are shortened to their first 8 characters.

tubetube list
tubetube list --status processing
tubetube list --limit 50 -o json
tubetube list --cursor 2026-08-30T20:36:23Z   # next page

get

Everything about one video: type, style, engine, credits, every pipeline step with its state, and a summary of the files produced.

tubetube get a1b2c3d4
tubetube get a1b2c3d4 -o json | jq .steps

watch

Polls until the video reaches a final state, drawing a progress bar with the step currently running. In -o json mode it prints one JSON object per poll, which is what you want in a log.

tubetube watch a1b2c3d4
tubetube watch a1b2c3d4 --interval 15   # seconds between polls, minimum 2

download

Downloads the finished files. The main video is renamed after the video title, so several downloads can live in the same folder.

tubetube download a1b2c3d4                            # the finished video
tubetube download a1b2c3d4 --all --output-dir ./out   # every scene, image and audio file
tubetube download a1b2c3d4 --asset archive            # the zip of all assets
tubetube download a1b2c3d4 --url-only                 # print signed URLs instead

Downloads made without a subscription carry a small tubetube.io mark. Subscribing later makes every video you have already made downloadable clean.

assets

Lists every file of a video with its kind, scene number, size and duration.

tubetube assets a1b2c3d4
tubetube assets a1b2c3d4 -o json | jq '[.assets[] | select(.kind=="scene_video")] | length'

delete

Permanent: the files are removed from storage and the record is dropped. Refused while a job is still running.

tubetube delete a1b2c3d4          # asks for confirmation
tubetube delete a1b2c3d4 --yes    # no prompt, for scripts

styles, engines, options

The accepted values, straight from the server, so you never have to guess an identifier like veo31fast720.

tubetube styles              # featured and custom styles
tubetube styles --all        # the full catalogue
tubetube engines             # engines and the scene durations each one allows
tubetube options -o json     # everything, machine-readable

whoami, credits

tubetube whoami     # email, plan, balance, watermark status, key source
tubetube credits    # just the number, handy in a shell prompt

Shell completion

# zsh — add to ~/.zshrc
source <(tubetube completion zsh)

# bash — add to ~/.bashrc
source <(tubetube completion bash)

# fish
tubetube completion fish > ~/.config/fish/completions/tubetube.fish

Recipes

One video a day, from a cron job

#!/usr/bin/env bash
set -euo pipefail
export TUBETUBE_API_KEY="$(cat ~/.secrets/tubetube)"

id=$(tubetube create --title "Daily story $(date +%F)" \
      --type narration --style "Watercolor storybook" \
      --lyrics-file "$HOME/stories/$(date +%F).txt" \
      -o json | jq -r .video.id)

tubetube watch "$id"                        # exits non-zero if it fails
tubetube download "$id" --output-dir ~/out

Batch: same recipe, many texts

for f in lyrics/*.txt; do
  tubetube create --from a1b2c3d4 --lyrics-file "$f" \
      --title "$(basename "$f" .txt)" -o json | jq -r .video.id
done > ids.txt

xargs -a ids.txt -I{} tubetube watch {}

Check the cost before spending

tubetube create --title x --style "Pixar-style 3D" \
    --lyrics-file song.txt --dry-run -o json | jq '{credits, scenes, balance: .quote.balance}'

REST API

The CLI is a thin client: every command is one HTTP call. Authenticate with Authorization: Bearer tt_live_…. Responses are JSON; errors always look like { "error": { "code": "…", "message": "…" } }.

# List videos
curl -s https://www.tubetube.io/api/v1/videos \
  -H "Authorization: Bearer $TUBETUBE_API_KEY"

# Price a video without launching it
curl -s https://www.tubetube.io/api/v1/quote \
  -H "Authorization: Bearer $TUBETUBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params":{"contentType":"song","format":"9:16",
       "lyrics":"Twinkle twinkle little star, how I wonder what you are",
       "imageStyle":"3D CGI in the style of Pixar, rounded expressive characters",
       "audioSource":"suno"}}'

# Create and launch
curl -s -X POST https://www.tubetube.io/api/v1/videos \
  -H "Authorization: Bearer $TUBETUBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"My song","params":{ … }}'

GET /api/v1/options returns the full prompt of every style, which is what you put in params.imageStyle. params accepts the same fields as the web wizard; anything you omit takes its default server-side.

Error codes

The CLI turns these into one-line messages and a non-zero exit status. With -o json it prints the error object instead, so a script can branch on .error.code.

Environment

Frequently asked questions