{"id":13961411,"url":"https://github.com/mkb79/audible-cli","last_synced_at":"2025-07-21T06:30:48.790Z","repository":{"id":37016882,"uuid":"292281009","full_name":"mkb79/audible-cli","owner":"mkb79","description":"A command line interface for audible package. With the cli you can download your Audible books, cover, chapter files. ","archived":false,"fork":false,"pushed_at":"2024-06-06T20:01:20.000Z","size":20434,"stargazers_count":433,"open_issues_count":35,"forks_count":45,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-08-09T17:29:36.839Z","etag":null,"topics":["aax","aaxc","chapter","cover","download","pdf","profiles","python","subcommands","toml"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mkb79.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["mkb79"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2020-09-02T12:47:08.000Z","updated_at":"2024-08-08T15:17:03.000Z","dependencies_parsed_at":"2024-04-01T12:30:52.162Z","dependency_job_id":"bc4088b3-a58c-44c4-8977-59d5e4f0256b","html_url":"https://github.com/mkb79/audible-cli","commit_stats":{"total_commits":177,"total_committers":12,"mean_commits":14.75,"dds":0.07909604519774016,"last_synced_commit":"59ec48189d32cf1e0054be05650f35d83bafdfdb"},"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkb79%2Faudible-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkb79%2Faudible-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkb79%2Faudible-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkb79%2Faudible-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mkb79","download_url":"https://codeload.github.com/mkb79/audible-cli/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226878801,"owners_count":17696720,"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":["aax","aaxc","chapter","cover","download","pdf","profiles","python","subcommands","toml"],"created_at":"2024-08-08T17:01:07.199Z","updated_at":"2025-07-21T06:30:48.783Z","avatar_url":"https://github.com/mkb79.png","language":"Python","readme":"# audible-cli\n\n**audible-cli** is a command line interface for the \n[Audible](https://github.com/mkb79/Audible) package. \nBoth are written with Python.\n\n## Requirements\n\naudible-cli needs at least *Python 3.10* and *Audible v0.8.2*.\n\nIt depends on the following packages:\n\n* aiofiles\n* audible\n* click\n* colorama (on Windows machines)\n* httpx\n* Pillow\n* tabulate\n* toml\n* tqdm\n\n## Installation\n\nYou can install audible-cli from pypi with\n\n```shell\n\npip install audible-cli\n\n```\n\nor install it directly from GitHub with\n\n```shell\n\ngit clone https://github.com/mkb79/audible-cli.git\ncd audible-cli\npip install .\n\n```\n\nor as the best solution using [uvx](https://github.com/astral-sh/uv)\n\n```shell\n\nuvx --with audible-cli audible\n\n```\n\n## Standalone executables\n\nIf you don't want to install `Python` and `audible-cli` on your machine, you can\nfind standalone exe files below or on the [releases](https://github.com/mkb79/audible-cli/releases) \npage (including beta releases). At this moment Windows, Linux and macOS are supported.\n\n### Links\n\n1. Linux\n    - [ubuntu latest onefile](https://github.com/mkb79/audible-cli/releases/latest/download/audible_linux_ubuntu_latest.zip)\n    - [ubuntu 22.04 onefile](https://github.com/mkb79/audible-cli/releases/latest/download/audible_linux_ubuntu_22_04.zip)\n\n2. macOS\n    - [macOS latest onefile](https://github.com/mkb79/audible-cli/releases/latest/download/audible_mac.zip)\n    - [macOS latest onedir](https://github.com/mkb79/audible-cli/releases/latest/download/audible_mac_dir.zip)\n\n3. Windows\n    - [Windows onefile](https://github.com/mkb79/audible-cli/releases/latest/download/audible_win.zip)\n    - [Windows onedir](https://github.com/mkb79/audible-cli/releases/latest/download/audible_win_dir.zip)\n\nOn every execution, the binary code must be extracted. On Windows machines this can result in a long start time. If you use `audible-cli` often, I would prefer the `directory` package for Windows!\n\n### Creating executables on your own\n\nYou can create them yourself this way\n\n```shell\n\ngit clone https://github.com/mkb79/audible-cli.git\n\n# onefile output\nuv run pyinstaller --clean -F --hidden-import audible_cli -n audible -c pyi_entrypoint\n\n# onedir output\nuv run pyinstaller --clean -D --hidden-import audible_cli -n audible -c pyi_entrypoint\n```\n\n### Hints\n\nThere are some limitations when using plugins. The binary maybe does not contain\nall the dependencies from your plugin script. \n\n## Tab Completion\n\nTab completion can be provided for commands, options and choice values. Bash, \nZsh and Fish are supported. More information can be found \n[here](https://github.com/mkb79/audible-cli/tree/master/utils/code_completion).\n\n\n## Basic information\n\n### App dir\n\naudible-cli use an app dir where it expects all necessary files.\n\nIf the ``AUDIBLE_CONFIG_DIR`` environment variable is set, it uses the value \nas config dir. Otherwise, it will use a folder depending on the operating \nsystem.\n\n| OS       | Path                                      |\n|----------|-------------------------------------------|\n| Windows  | ``C:\\Users\\\u003cuser\u003e\\AppData\\Local\\audible`` |\n| Unix     | ``~/.audible``                            |\n| Mac OS X | ``~/.audible``                            |\n\n### The config file\n\nThe config data will be stored in the [toml](https://github.com/toml-lang/toml) \nformat as ``config.toml``.\n\nIt has a main section named ``APP`` and sections for each profile created \nnamed ``profile.\u003cprofile_name\u003e``\n\n### profiles\n\naudible-cli make use of profiles. Each profile contains the name of the \ncorresponding auth file and the country code for the audible marketplace. If \nyou have audiobooks on multiple marketplaces, you have to create a profile for \neach one with the same auth file.\n\nIn the main section of the config file, a primary profile is defined. \nThis profile is used, if no other is specified. You can call \n`audible -P PROFILE_NAME`, to select another profile.\n\n### auth files\n\nLike the config file, auth files are stored in the config dir too. If you \nprotected your auth file with a password call `audible -p PASSWORD`, to \nprovide the password.\n\nIf the auth file is encrypted, and you don’t provide the password, you will be \nasked for it with a „hidden“ input field. \n\n### Config options\n\nAn option in the config file is separated by an underline. In the CLI prompt,\nan option must be entered with a dash.\n\n#### APP section\n\nThe APP section supports the following options:\n- primary_profile: The profile to use, if no other is specified\n- filename_mode: When using the `download` command, a filename mode can be \n  specified here. If not present, \"ascii\" will be used as default. To override\n  these option, you can provide a mode with the `--filename-mode` option of the\n  download command.\n- chapter_type: When using the `download` command, a chapter type can be specified \n  here. If not present, \"tree\" will be used as default. To override\n  these option, you can provide a type with the `--chapter-type` option of the\n  download command.\n\n#### Profile section\n\n- auth_file: The auth file for this profile\n- country_code: The marketplace for this profile\n- filename_mode: See APP section above. Will override the option in APP section.\n- chapter_type: See APP section above. Will override the option in APP section.\n\n## Getting started\n\nUse the `audible-quickstart` or `audible quickstart` command in your shell \nto create your first config, profile and auth file. `audible-quickstart` \nruns on the interactive mode, so you have to answer multiple questions to finish.\n\nIf you have used `audible quickstart` and want to add a second profile, you need to first create a new authfile and then update your config.toml file.\n\nSo the correct order is:\n\n   1. add a new auth file using your second account using `audible manage auth-file add`\n   2. add a new profile to your config and use the second auth file using `audible manage profile add`\n\n\n## Commands\n\nCall `audible -h` to show the help and a list of all available subcommands. You can show the help for each subcommand like so: `audible \u003csubcommand\u003e -h`. If a subcommand has another subcommands, you csn do it the same way.\n\nAt this time, there the following buildin subcommands: \n\n- `activation-bytes`\n- `api`\n- `download`\n- `library`\n    - `export`\n    - `list`\n- `manage`\n    - `auth-file`\n        - `add`\n        - `remove`\n    - `config`\n        - `edit`\n    - `profile`\n        - `add`\n        - `list`\n        - `remove`\n- `quickstart`\n- `wishlist`\n    - `export`\n    - `list`\n    - `add`\n    - `remove`\n\n## Example Usage\n\nTo download all of your audiobooks in the aaxc format use:\n```shell\naudible download --all --aaxc\n```\nTo download all of your audiobooks after the Date 2022-07-21 in aax format use: \n```shell\naudible download --start-date \"2022-07-21\" --aax --all\n```\n\n## Verbosity option\n\nThere are 6 different verbosity levels:\n\n- debug\n- info\n- warning\n- error\n- critical\n\nBy default, the verbosity level is set to `info`. You can provide another level like so: `audible -v \u003clevel\u003e \u003csubcommand\u003e ...`.\n\nIf you use the `download` subcommand with the `--all` flag there will be a huge output. Best practise is to set the verbosity level to `error` with `audible -v error download --all ...`\n\n## Plugins\n\n### Plugin Folder\n\nIf the ``AUDIBLE_PLUGIN_DIR`` environment variable is set, it uses the value \nas location for the plugin dir. Otherwise, it will use a the `plugins` subdir \nof the app dir. Read above how Audible-cli searches the app dir.\n\n### Custom Commands\n\nYou can provide own subcommands and execute them with `audible SUBCOMMAND`.\nAll plugin commands must be placed in the plugin folder. Every subcommand must \nhave his own file. Every file have to be named ``cmd_{SUBCOMMAND}.py``. \nEach subcommand file must have a function called `cli` as entrypoint. \nThis function has to be decorated with ``@click.group(name=\"GROUP_NAME\")`` or  \n``@click.command(name=\"GROUP_NAME\")``.\n\nRelative imports in the command files doesn't work. So you have to work with \nabsolute imports. Please take care about this. If you have any issues with \nabsolute imports please add your plugin path to the `PYTHONPATH` variable or \nadd this lines of code to the beginning of your command script:\n\n```python\nimport sys\nimport pathlib\nsys.path.insert(0, str(pathlib.Path(__file__).parent))\n```\n\nExamples can be found \n[here](https://github.com/mkb79/audible-cli/tree/master/plugin_cmds).\n\n\n## Own Plugin Packages\n\nIf you want to develop a complete plugin package for ``audible-cli`` you can\ndo this on an easy way. You only need to register your sub-commands or \nsubgroups to an entry-point in your setup.py that is loaded by the core \npackage.\n\nExample for a setup.py\n\n```python\nfrom setuptools import setup\n\nsetup(\n    name=\"yourscript\",\n    version=\"0.1\",\n    py_modules=[\"yourscript\"],\n    install_requires=[\n        \"click\",\n        \"audible_cli\"\n    ],\n    entry_points=\"\"\"\n        [audible.cli_plugins]\n        cool_subcommand=yourscript.cli:cool_subcommand\n        another_subcommand=yourscript.cli:another_subcommand\n    \"\"\",\n)\n```\n\n## Command priority order\n\nCommands will be added in the following order:\n\n1. plugin dir commands\n2. plugin packages commands\n3. build-in commands\n\nIf a command is added, all further commands with the same name will be ignored.\nThis enables you to \"replace\" build-in commands very easy.\n\n## List of known add-ons for `audible-cli`\n\n- [audible-cli-flask](https://github.com/mkb79/audible-cli-flask)\n- [audible-series](https://pypi.org/project/audible-series/)\n\nIf you want to add information about your add-on please open a PR or a new issue!\n","funding_links":["https://github.com/sponsors/mkb79"],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkb79%2Faudible-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmkb79%2Faudible-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkb79%2Faudible-cli/lists"}