{"id":28641025,"url":"https://github.com/dotcs/xkcd-cli","last_synced_at":"2025-06-12T20:36:42.272Z","repository":{"id":37800773,"uuid":"481370394","full_name":"dotcs/xkcd-cli","owner":"dotcs","description":"A xkcd terminal viewer that uses fzf for searching and renders images directly in terminals that support image rendering (e.g., kitty, iterm2, any other with sixel support)","archived":false,"fork":false,"pushed_at":"2022-06-20T10:31:34.000Z","size":76,"stargazers_count":27,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"develop","last_synced_at":"2025-06-06T06:05:56.964Z","etag":null,"topics":["cli","cli-app","iterm2","kitty","python","sixel","wezterm","xkcd","xkcd-comics"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dotcs.png","metadata":{"files":{"readme":"Readme.md","changelog":"Changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-04-13T20:50:51.000Z","updated_at":"2025-05-06T13:49:27.000Z","dependencies_parsed_at":"2022-06-23T14:21:48.575Z","dependency_job_id":null,"html_url":"https://github.com/dotcs/xkcd-cli","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/dotcs/xkcd-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotcs%2Fxkcd-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotcs%2Fxkcd-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotcs%2Fxkcd-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotcs%2Fxkcd-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dotcs","download_url":"https://codeload.github.com/dotcs/xkcd-cli/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotcs%2Fxkcd-cli/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259522779,"owners_count":22870552,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","cli-app","iterm2","kitty","python","sixel","wezterm","xkcd","xkcd-comics"],"created_at":"2025-06-12T20:36:40.484Z","updated_at":"2025-06-12T20:36:42.238Z","avatar_url":"https://github.com/dotcs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# xkcd cli tool\n\n\u003cp align=\"center\"\u003e\n\u003cimg alt=\"Lint and static code analysis on develop branch\" src=\"https://github.com/dotcs/xkcd-cli/actions/workflows/lint-sca.yaml/badge.svg?branch=develop\"/\u003e\n\u003ca href=\"https://github.com/dotcs/xkcd-cli/blob/main/LICENSE\"\u003e\u003cimg alt=\"License: MIT\" src=\"https://black.readthedocs.io/en/stable/_static/license.svg\"/\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/psf/black\"\u003e\u003cimg alt=\"Code style: black\" src=\"https://img.shields.io/badge/code%20style-black-000000.svg\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nGet your daily dose of [xkcd] directly from the terminal! 🤩\n\nhttps://user-images.githubusercontent.com/3976183/163873282-f586f312-2643-4b77-af79-89e344091b2f.mp4\n\n[xkcd] is a webcomic created by [Randall Munroe][munroe]. \nIt is a comic of Language, Math, Romance and Sarcasm and a [couple of other categories][explain-xkcd-categories].\n\nIf [kitty], [iterm] or any terminal that has support for the [sixel] file format is used as the terminal, the xkcd comic will be rendered directly in the terminal, otherwise the default viewer for PNG images is used.\nThis tool requires [fzf] to be installed on the machine to filter available comics by their title. \n\n## Installation\n\n### With pip\n\nInstall this package directly from the [Python Package Index (PyPI)][pypi-repo].\nThe CLI tool requires Python \u003e= 3.8 to be installed.\n\n```console\n$ pip install dcs-xkcd-cli\n```\n\nThis will install a CLI tool named `xkcd` which can be used as described below.\n\n### With pipx\n\nInstallation with [pipx] is similar to the pip variant above, but uses `pipx` instead of `pip`.\n\n```console\n$ pipx install dcs-xkcd-cli\n```\n\nNote that with pipx, this package can be tried out without the need to install it permanently.\n\n```console\n$ pipx run dcs-xkcd-cli \u003cargs\u003e\n```\n\n\n## Usage\n\n### Search by title\n\n```console\n$ xkcd show\n```\n\nThis functionality requires [fzf] to be installed.\n\n### Show latest xkcd comic\n\n```console\n$ xkcd show --latest\n```\n\n### Show random xkcd comic\n\n```console\n$ xkcd show --random\n```\n\n### Show xkcd comic by its ID\n\n```console\n$ xkcd show --comic-id 207\n```\n\n### Upscaling / width of comics\n\nBy default images are upscaled to match the terminal dimensions.\nThis behavior can be controlled with the `--terminal-scale-up / --no-terminal-scale-up` options.\nImages can be also rendered with an explicit width by using the `--width` CLI option.\n\n```console\n$ xkcd show --comic-id 207 --no-terminal-scale-up    # disable scaling\n$ xkcd show --comic-id 207 --width 1200              # set explicit width\n```\n\n\n### Disable rendering in terminals\n\n```console\n$ xkcd show --no-terminal-graphics\n```\n\nThis command will disable the automatic image protocol detection and directly open the image with the help of `xdg-open` in the default image viewer.\n\n### Disable or update cache\n\nUnder the hood this tool uses a cache which is updated once per day transparently.\nThe cache is used to remember the list of xkcd comics from the [archive].\n\nTo disable the cache, use the following command\n\n```console\n$ xkcd show --no-cache\n```\n\nTo update the cache manually, use the following command\n```console\n$ xkcd update-cache\n```\n\n## Development\n\nThis repository manages Python dependencies with [poetry].\nTo install the package and its dependencies run:\n\n```console\n$ poetry install\n```\n\nThe code is formatted with [black] and type checked with [pyright].\n\nThen run the the following commands to lint and test the code:\n\n```console\n$ poetry run python -m black --check --diff .   # tests for any lint issues\n$ poetry run python -m black .                  # auto-formats the code\n\n$ poetry run python -m pyright                  # runs static code analysis\n\n$ poetry run python -m pytest --cov=\"xkcd_cli/\" --cov-report term --cov-report html   # run tests with code coverage report\n```\n\n\n[fzf]: https://github.com/junegunn/fzf\n[kitty]: https://sw.kovidgoyal.net/kitty/\n[archive]: https://xkcd.com/archive/\n[xkcd]: https://xkcd.com\n[munroe]: https://en.wikipedia.org/wiki/Randall_Munroe\n[explain-xkcd-categories]: https://www.explainxkcd.com/wiki/index.php/Category:Comics_by_topic\n[pypi-repo]: https://pypi.org/project/dcs-xkcd-cli/\n[pipx]: https://pypa.github.io/pipx/\n[iterm]: https://iterm2.com/\n[sixel]: https://en.wikipedia.org/wiki/Sixel\n[poetry]: https://python-poetry.org/\n[black]: https://black.readthedocs.io/en/stable/\n[pyright]: https://github.com/Microsoft/pyright\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdotcs%2Fxkcd-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdotcs%2Fxkcd-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdotcs%2Fxkcd-cli/lists"}