📝 Description

TTKDL-CLI is a lightweight command-line tool for downloading TikTok videos directly from one or multiple URLs. It lets you configure download paths, control concurrent download limits, and set persistent default folders for saving videos across sessions.

🚀 Features

• Download one or multiple TikTok videos from URLs (any URL format, full or short).
• Concurrent downloads (up to 5 videos at a time).
• Custom output paths or persistent default save folders.
• Simple and intuitive command-line interface.

💻 Technologies

• Node.js (runtime for the CLI)
• JavaScript (ES Modules)

⚙️ Prerequisites

Before using the CLI, make sure you have installed:

• Node.js (version 18.x or higher)
• npm (Node.js package manager)

To check if you have Node.js and npm installed, run:

node -v
npm -v

If you don't have Node.js installed, you can download it here: https://nodejs.org.

🛠️ Installation

You can run the CLI either by installing it globally or using npx:

Global Installation

npm install -g @thiagobrg60/ttkdl-cli

After installing, the ttkdl command will be available globally in your terminal.

Using npx (without installing)

npx @thiagobrg60/ttkdl-cli "https://www.tiktok.com/@example/video/123456789"

📖 Usage

Single Download

Download a single TikTok video:

# Single download with full URL
ttkdl "https://www.tiktok.com/@example/video/123456789"

# Single download with short URL
ttkdl "https://vm.tiktok.com/example"

Multiple Downloads

Download multiple videos at once:

# Multiple downloads with mixed URLs
ttkdl "https://www.tiktok.com/@example/video/123456789" "https://vt.tiktok.com/example-2" "https://vm.tiktok.com/example-3"

Custom Output Path

Specify a custom save location for a single download session:

ttkdl "https://vt.tiktok.com/example" -o "./my/folder"

Maximum Concurrent Downloads

Set the number of videos to download simultaneously (max: 5):

ttkdl "https://vm.tiktok.com/example-1" "https://vt.tiktok.com/example-2" -m 5

Default Save Location

Configure a persistent default folder for all downloads:

ttkdl config -r "C:/default/videos/folder"

🎯 Command Reference

Global Commands

ttkdl [options]

| Arguments / Options | Description | |---------------------|-------------------------------| | -h, --help | Shows the help message | | -v, --version | Shows the current CLI version |

Download Commands

ttkdl <urls> [options]

| Arguments / Options | Description | Default | |-----------------------|------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------| | <urls> | One or more valid TikTok URLs (e.g., https://vt.tiktok.com/example) | — | | -o, --output <path> | Sets the save path for videos (one-time, optional) | Windows: C:/Users/<username>Linux: /home/<username>macOS: /Users/<username> | | -m, --max <number> | Sets the number of videos to download simultaneously (max 5, optional) | 3 |

Configuration Commands

ttkdl config [options]

| Arguments / Options | Description | Default | |------------------------|---------------------------------------------------------------- |--------------------------------------------------------------------------------------------------| | -r, --root <path> | Sets the default folder where videos will be saved (persistent) | Windows: C:/Users/<username>Linux: /home/<username>macOS: /Users/<username> |

🤝 Contributing

Contributions are welcome! To contribute to the project, follow these steps:

1. Fork the repository.

2. Create a branch for your feature or change: git checkout -b your-branch-name.

3. Make your changes, add and commit: git add . and git commit -m 'commit message'.

4. Push your changes to the forked repository: git push origin your-branch-name.

5. Create a pull request on GitHub to the main repository.

💡 If you find a bug or have a feature request, please open an Issue on GitHub.

⚠️ Disclaimer

This is an open-source command-line tool developed for educational and technical demonstration purposes, focusing on web automation, CLI design, and media handling.

Important:

• The tool is intended to interact only with publicly accessible resources.
• Any use must comply with the Terms of Service, copyright laws, and policies of the respective platforms.
• It is not intended for large-scale, automated, or commercial redistribution of third-party content.
• The author assumes no responsibility for misuse of this software.

This project is not affiliated with, endorsed by, or supported by TikTok or any other platform.

📬 Contact

If you have any questions, feel free to contact me via email:

📄 License

This project is licensed under the MIT License. See the LICENSE file for more details.

⭐ If this project helped you, consider leaving a star on the repository!