Metadata-Version: 2.1
Name: ytcl
Version: 1.0.0
Summary: CLI frontend for ytdl-server
Home-page: https://gitlab.com/adralioh/ytcl
Author: Adralioh
License: UNKNOWN
Keywords: ytdl-server,youtube-dl,yt-dlp,youtube,download,cli
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: System :: Archiving
Classifier: Typing :: Typed
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Provides-Extra: windows_color
License-File: LICENSE

# ytcl
ytcl is a command-line frontend for
[ytdl-server](https://gitlab.com/adralioh/ytdl-server).

Its syntax is based on youtube-dl/yt-dlp, and it shares many of the same
arguments.

[TOC]

## Installation
ytcl requires [Python](https://www.python.org/) 3.7+.

Install from [PyPI](https://pypi.org/project/ytcl/):
```bash
pip3 install ytcl
```

Install from source:
```bash
git clone 'https://gitlab.com/adralioh/ytcl.git'
pip3 install ./ytcl
```

If you want color output to work on Windows, you can also optionally install
[Colorama](https://github.com/tartley/colorama):
```bash
pip3 install 'ytcl[windows_color]'
```

## Usage
First, you must set the `$YTCL_SERVER` env-var to the URL of the ytdl-server
so that ytcl can connect to it:
```bash
export YTCL_SERVER=http://ytdl-server.example.com
```

### Create a job
Download videos by creating a job:
```bash
ytcl create 'https://youtu.be/dQw4w9WgXcQ'
```

You can pass most arguments that youtube-dl accepts. Example:
```bash
ytcl create -f 'bestaudio/best' --extract-audio 'https://youtu.be/dQw4w9WgXcQ'
```

You can also start a job without waiting for it to finish:
```bash
ytcl -d create 'https://youtu.be/dQw4w9WgXcQ'
```

Run `ytcl create --help` for an exhaustive list of arguments.

### Get the status of a job
You can check the status of a job using the job ID:
```bash
ytcl get 'b7cce5f7-9f7c-47ed-ae13-2acf7c32cc29'
```

> The job ID is obtained from the output of the command where you create the
  job.

The above command will run until the job finishes. If you just want to get the
complete current status of the job, you can change the output format:
```bash
ytcl -f all get 'b7cce5f7-9f7c-47ed-ae13-2acf7c32cc29'
```

JSON output is also supported:
```bash
ytcl -f json get 'b7cce5f7-9f7c-47ed-ae13-2acf7c32cc29'
```

### Cancel a job
You can also cancel a running job:
```bash
ytcl cancel 'b7cce5f7-9f7c-47ed-ae13-2acf7c32cc29'
```

The above command will wait until the job is cancelled. You can also exit
immediately without waiting:
```bash
ytcl -d cancel 'b7cce5f7-9f7c-47ed-ae13-2acf7c32cc29'
```

### Basic authentication
If the ytdl-server uses basic authentication, you can provide the credentials
via the `$YTCL_SERVER_USERNAME` and `$YTCL_SERVER_PASSWORD` env-vars:
```bash
export YTCL_SERVER_USERNAME=user
export YTCL_SERVER_PASSWORD=password
```

If only the username is provided, you will be prompted for the password
interactively.

## Exit codes
ytcl exits with the following exit codes when an error occurs:

| Code | Description                                                          |
| ---: | -------------------------------------------------------------------- |
|    2 | Invalid argument                                                     |
|   10 | Unspecified error                                                    |
|   11 | ytcl tried to use a ytdl_opt that is blacklisted by the ytdl-server when creating a job |
|   12 | ytcl tried to use a custom_opt that is blacklisted by the ytdl-server when creating a job |
|   13 | ytcl tried to cancel a job that has already completed                |
|   14 | The job failed                                                       |
|   15 | ytcl received an error response from the ytdl-server                 |
|   16 | The URL of the ytdl-server wasn't provided. This can be set via the `$YTCL_SERVER` env-var |


