tldr-pages
[Feature Request] Add verbose/debug flag for better troubleshooting
I am experiencing issues with tldr when trying to fetch the page for tar. There is no error message other than "Page not found.":
❯ tldr tar
✔ Page not found. Updating cache...
✔ Creating index...
Page not found.
This issue seems to be related to my complex network setup (company laptop with custom certificates, running on WSL). I suspect there might be a networking issue blocking the request, but I have no way of investigating further due to the lack of detailed output or logs. I tried TLDR_ALLOW_INSECURE=1
Suggestion:
Add a --verbose flag to show detailed output of what tldr is doing.
Alternatively, add debug flags to provide more granular logging.
If there is already a debug flag, it would be helpful to mention in in README.
The issue is likely on my side, but without detailed logs, I cannot progress. Thank you for your assistance!
@kbdharun I could have a go at implementing something for this issue, do you have any ideas for how you'd like to approach it?
Looking at the current codebase, it uses print throughout and so the only way to have different levels of verbosity would be to pass around a verbose=True flag or similar to each function where necessary. Doing something like
if verbose:
print("Fetching foo from URL: bar")
A more robust approach would be to switch to the standard logging library which gives fine grained control at runtime. For example, some messages could use logger.info("This is a useful message") or logger.debug("This is a debug message"). By default, messages at the debug level are hidden but if the user passes in the --verbose flag at runtime then we could set the loglevel to DEBUG which would surface the verbose logging messages. Hope that makes sense :) It's a more significant refactor though, but not too tricky.
In either case, would you want to display a full traceback if an error occurs, or just increase the number of debug messages everywhere to give a detailed picture of what the tool is doing to the user (in the verbose case)?
Just to add another datapoint, I also suffer from a corporate SSL Inspection MitM setup (Netskope) and get the following error based on the latest version of tldr:
$ uv run tldr tar
Error fetching from tldr: <urlopen error _ssl.c:990: The handshake operation timed out>
This at least gives more of a hint to the problem than in the OP, but we obviously have different corporate environments.
That being said, using the environment variables in the README.md still yield the error:
$ TLDR_ALLOW_INSECURE=1 uv run tldr tar
Error fetching from tldr: <urlopen error _ssl.c:990: The handshake operation timed out>
and
$ TLDR_CERT=/usr/local/share/ca-certificates/nscacert.crt uv run tldr tar
Error fetching from tldr: <urlopen error _ssl.c:990: The handshake operation timed out>
Adding some debug logging locally, I can see that my error is occurring intermittently on a different URL each time. The script currently attempts to fetch the docs for every platform and on one run for example it fails on https://raw.githubusercontent.com/tldr-pages/tldr/main/pages/freebsd/tar.md but on another run it fails on https://raw.githubusercontent.com/tldr-pages/tldr/main/pages/common/tar.md.
Each time it does succeed on at least one URL though, so the subsequent run receives the doc from the cache. I clear it with tldr -k to re-test.
Would it be worth opening a new issue to switch this tool's usage of urllib to something more high level like the third party requests library? I suspect any issues with a flaky connection would be handled more gracefully than when using urllib directly.
Another option would be to only raise the URLError when zero pages are received, instead of falling over as soon as one request fails (even if others succeeded).
I could implement that improvement in a small PR?