Flucto docs

Quick start

Download Flucto-<version>-cli-setup.zip from GitHub Releases and extract it into a writable folder. Run install.cmd on Windows or bash install.sh on macOS/Linux — no existing Node.js and no admin rights required. The bootstrap downloads a private Node.js 24 runtime from nodejs.org, verifies its SHA256, and installs the bundled CLI plus yt-dlp/FFmpeg under a private prefix. Internet access is required.

# after extracting
install.cmd                    # Windows
bash install.sh                # macOS / Linux

# verify in a new shell
flucto doctor --json
flucto setup --json            # provision/refresh binaries manually

Both fl and flucto are registered. Note that PowerShell reserves fl for Format-List — use flucto or fl.cmd there; fl works in cmd.exe and POSIX shells. Transcripts only? Skip the ffmpeg download with flucto setup --yt-dlp-only --json.

Isolated install without persistent PATH changes: install.ps1 -InstallDir DIR -NoProfile or install.sh --install-dir DIR --no-profile. The Windows bootstrap execution policy is process-scoped — it does not change your user policy. If you already run Node.js 24, npm i -g flucto also works but is not required.

Commands

Every command supports -j (--json). Human output and machine output come from the same engine.

flucto search "<keyword>"        # integrated search across 12 sites
flucto download <url>            # MP4/MP3 download (d)
flucto batch <file>              # batch from a URL list (b)
flucto transcript <url>          # captions → Markdown (t)
flucto md <url>                  # Markdown with frontmatter (m)
flucto channel to-md <@handle>   # whole channel → Markdown folder
flucto info <url>                # metadata (i)
flucto formats <url>             # available formats (f)
flucto languages <url>           # caption language list (l)
flucto doctor                    # binary health check (doc)
flucto setup                     # provision yt-dlp/ffmpeg (s)
flucto update check|download|apply

batch and channel to-md always create a dedicated subfolder under --out (e.g. notes/handle-channel-md-20260829-…/) — files never mix.

fl transcript vs fl md

• /t (transcript) — same format as the desktop app: title, metadata, timestamped paragraphs.
• /m (md) — document-oriented: YAML frontmatter + thumbnail. Great for Obsidian/blog pipelines.

Search

flucto search "<keyword>" searches 12 registered sites: YouTube · X · Reddit · Bilibili · Dailymotion · Niconico · OK.ru · VK Video · Instagram · Threads · TikTok · Vimeo. Select one with --platform <site>; IDs include youtube, x, reddit, bilibili, dailymotion, nicovideo, ok, vkvideo, instagram, threads, tiktok, and vimeo. --limit caps total results, not each site (1–50, default 20).

flucto search "nature" --limit 20 --json
flucto search "nature" --platform youtube --json
flucto search "初音ミク" --platform nicovideo --json

Results identify their source and native/index method. Partial failures retain other results; partial failure and empty searches exit 0, while total failure returns error and exits 4. The desktop Search videos default is All sites (integrated).

Search on X, Instagram, TikTok, and Vimeo, browser search on OK.ru and Threads, and every public-index path require local Google Chrome (or FLUCTO_CHROME_PATH). Bilibili, VK Video, and other providers also use Chrome-based fallbacks when native search is restricted. Contexts are temporary and anonymous; your logged-in profile is not read. No CAPTCHA, region, paid-content, or private-content bypass. A searchable video may still be deleted, private, or region-locked when downloaded.

Global options

Markdown conversion

Captions are parsed from JSON3, XML/SRV3 and VTT, stripped of markup, and grouped into paragraphs by silence gaps. If the requested language is missing, Flucto falls back (base language → original ASR → alternates) up to 3 candidates — and says unavailable when there is truly nothing.

# list caption languages
fl l "https://youtu.be/…" -j

# Korean captions to stdout
fl t "https://youtu.be/…" -l ko -s

# a channel into a notes folder
fl channel to-md "@handle" --limit 100 -o ./notes -l ko

Rate limits (429) meet exponential backoff; repeated failures open a circuit breaker for 60s and return SERVICE_UNAVAILABLE. That is your cue to add cookies or a proxy.

Cookies · proxy · env

When YouTube asks to "sign in to confirm you're not a bot", attach cookies or a proxy. Flags take precedence over environment variables.

AI agents

The CLI was designed for agents from day one: result JSON on stdout, progress NDJSON on stderr — cleanly separated for pipes.

# parse just the final result
fl t "URL" -j 2>/dev/null | jq .filePath

# watch progress while it runs
fl channel to-md "@handle" -o ./notes --progress-json

Exit codes

Just tell your agent: "Install the Flucto CLI from the GitHub release cli-setup.zip (it brings its own Node runtime), then turn this channel's recent captions into timestamped Markdown notes in ./notes: https://youtube.com/@handle"

Desktop app

The same TypeScript engine behind a GUI: batch queue, format presets, download history, integrated search across 12 sites, and a captions→Markdown panel. Installers for Windows, macOS and Linux live on GitHub Releases.

• /Integrated search — per-site counts, native/index attribution, and real errors under Search sources
• /Advanced network settings — cookies.txt/proxy from the UI (same engine as --cookies)
• /yt-dlp auto-refresh — follows the official nightly channel so extractors stay current
• /App updates — electron-updater on Windows/Linux; unsigned macOS downloads a verified DMG for manual replacement

Only need the CLI? Skip the app — cli-setup.zip brings its own Node runtime. Want fl alongside the app? Same ZIP or npm i -g flucto — same settings, same engine.

Troubleshooting