Would it make sense adding a prompt when trying to write to an existing file, similar to --output? It's currenly always appending to the logfile. That could also be changed, either with a prefix or secondary parameter.

Hmm, I don't really see the benefit of a prompt when writing to an existing file. I would imagine most people writing out log files are going to be comfortable with log rotate or understand the basics of what they are doing.

@bastimeyer,
why not use the RotatingFileHandler of logging.handlers?

The reason why I asked about a prompt and whether to append or not is that the log output is not that useful if it gets appended to an existing file, because there's no real "preamble" that would make it clear that a new Streamlink instance is writing to the log file. Maybe it'd make sense always logging the used arguments (log_current_arguments) when the logfile argument is set.

RotatingFileHandler

This doesn't solve the issue I just mentioned. It's meant for proper log rotation and requires a maxBytes and backupCount value. And then there are also other handlers which might be preferred by some user instead. I'm not sure this fits into the scope of Streamlink's CLI.

My idea of the logfile argument is being able to write the log output of a single Streamlink instance into a separate file, not having a continuous/shared logfile of multiple instances, because it's not really useful.

This also raises the question whether a default logfile path could be used when - is set as the logfile argument value, eg. ${XDG_STATE_HOME:${HOME}/.local/state}/streamlink/logs/$(date --iso-8601=seconds).txt.

This doesn't solve the issue I just mentioned.

That wasn't meant to be either.

It's meant for proper log rotation and requires a maxBytes and backupCount value.

With default values of 0 you get the same behavior as with FileHandler.

@bastimeyer Are we good here or are you still working?

Yes, sorry about the confusion. After pushing the latest changes I updated the text of the OP, but didn't add a new comment. Unless someone has any concerns, this should be good. I was waiting for another review, as I've changed a ton since your review. The tests are now done properly and cover both POSIX and Windows paths.

To sum up the changes again:

• adds the --logfile parameter
• shares the same write stream between the logger and consoleoutput
• argument value can be a relative or an absolute path
• argument value can also be -, which makes it choose a default directory and file name
  • on Windows: %TEMP%\streamlink\logs\2021-05-31_19-57-00.log
  • on macOS: ${HOME}/Library/logs/streamlink/2021-05-31_19-57-00.log
  • on Linux/BSD: ${XDG_STATE_HOME:-${HOME}/.local/state}/streamlink/logs/2021-05-31_19-57-00.log
    (XDG_STATE_HOME is part of the XDG base directory standard 0.8 from 2021-05-08 and logs should go there now)
• tries to create parent directories
• always appends log data to the chosen log file
• user prompts and download progress always get written to stderr and not the logfile
• refactors the previous CLI-main logging tests and adds test for everything new (except the logdir constants)
• fixes escaped double-percent chars in the rendered docs

What could have been done differently:

• logrotation: unnecessary and if desired can be implemented later
• path templates: the - argument value already results in a dynamic path based on the current time and relative/absolute paths can be made dynamic with shell substitution

@bastimeyer I looked over the changes after you forced pushed 2 days ago and everything looks even better than it originally did. I'm going to merge this in, thanks for the improvements.