audible-cli

AUDIBLE-CLI

A powerful command-line tool for managing and downloading your Audible audiobooks.

Built with ❤️ in Python.

[!NOTE]

audible-rs — a Rust rewrite in the making, experienced testers wanted

A ground-up Rust reimplementation of audible-cli (and the Audible library) is in active development: one fast, statically-linked binary — no Python required — with a reworked command set, an encrypted auth format, a local library database (SQLite/FTS5), and a capability-based plugin system.

It is pre-alpha and I'm looking for experienced users to run it against real accounts and report the rough edges. If you're comfortable on the command line and don't mind occasional breakage, please help kick the tyres → github.com/mkb79/audible-rs (the README there has a one-line installer for prebuilt Linux/macOS binaries). Share feedback, questions and findings in the audible-rs Discussions.

audible-cli stays fully supported — audible-rs is the future direction, not an immediate replacement, and the two use separate config directories, so you can run them side by side.

✨ Features

• Manage multiple Audible accounts (profiles)
• Browse and export your library and wishlist
• Download audiobooks in AAXC or AAX with metadata & chapters
• ⚡ Fast HTTP requests powered by httpx
• ️ Plugin system for custom commands & extensions
• Cross-platform: Linux, macOS, Windows
• Prebuilt executables (no Python required)

Installation

With uv tool (recommended)

uv tool install audible-cli

With uvx

uvx --from audible-cli audible

From PyPI

pip install audible-cli

From GitHub

git clone https://github.com/mkb79/audible-cli.git
cd audible-cli
pip install .

⚡ Faster crypto (optional)

Install the optional cryptography extra to enable audible's Rust-accelerated crypto backend. It noticeably speeds up cryptographic operations such as fetching activation bytes and decrypting AAX/AAXC files:

pip install "audible-cli[cryptography]"
# or, when installed as a tool:
uv tool install "audible-cli[cryptography]"

Without the extra, audible-cli still works using the pure-Python fallback.

️ Standalone executables

Don’t want to install Python?
Prebuilt binaries are available on the releases page.

ℹ️ The prebuilt binaries bundle an accelerated crypto backend, with no extra setup — the Rust-based cryptography everywhere except Windows on arm64, which uses pycryptodome because cryptography publishes no wheel for it. Either way you are not on the slow pure-Python fallback.

Windows — x86_64 onedir (recommended), x86_64 onefile
Also on ARM: arm64 onedir, arm64 onefile

macOS — Apple silicon only: onefile, onedir
On an Intel Mac, install from PyPI instead: pipx install audible-cli

Linux — take these: x86_64, arm64
Built on Ubuntu 22.04, so they need glibc 2.35 — Ubuntu 22.04, Debian 12, RHEL 9 and anything newer.
There are also builds on a 24.04 base (x86_64, arm64). They need glibc 2.38 and so reach fewer systems; take one only if you have a reason to.

ℹ️ The download names now carry the architecture. The old names without one (audible_mac.zip, audible_win.zip and the rest) are still published alongside and will be dropped after 15 November 2026.

⚠️ On Windows, prefer the onedir build for faster startup.

Quickstart

1. Run the interactive setup:

   bash复制

   audible quickstart

   → creates config, profile, and auth file.

2. List your library:

   bash复制

   audible library list

3. Download your entire library:

   bash复制

   audible download --all --aax

Common use cases

⚙️ Configuration & Profiles

App directory

audible-cli stores its configuration files in an app directory.

You can override this by setting the environment variable:

export AUDIBLE_CONFIG_DIR=/path/to/dir

Config file

• Name: config.toml
• Format: TOML
• Structure:
  • [APP] section → global defaults
  • [profile.] section → settings per Audible account

Example:

[APP]
primary_profile = "default"
filename_mode   = "ascii"
chapter_type    = "tree"

[profile.default]
auth_file    = "auth.json"
country_code = "us"

[profile.germany]
auth_file    = "auth_de.json"
country_code = "de"

Profiles

• Each profile corresponds to an Audible account or marketplace
• Contains:
  • auth_file → authentication file
  • country_code → Audible marketplace (us, de, uk, …)
• Switch profiles with:

audible -P germany library list

The [APP].primary_profile is used if no profile is specified.

Auth files

• Stored in the same app directory as the config file
• Can be password-protected:

audible -p "mypassword" download --asin 

• If no password is passed, you will be prompted with hidden input

Config options

APP section

• primary_profile: default profile if none is specified
• filename_mode: filename handling for downloads
  • ascii (default)
  • override with --filename-mode
• chapter_type: chapter format for downloads
  • tree (default)
  • override with --chapter-type

Profile section

• auth_file: authentication file for this profile
• country_code: Audible marketplace
• filename_mode: overrides [APP].filename_mode
• chapter_type: overrides [APP].chapter_type

Continuous integration (GitHub Actions)

audible-cli can run headless in CI, for example to export your library on a schedule. The setup-audible-cli action installs audible-cli and configures a minimal, ephemeral Audible authentication on the runner, so later steps can run audible commands.

Signed Audible API requests need only two values from your local auth.json, so there is no need to upload the whole config directory. If you have not authenticated yet, do it once locally with audible quickstart (or audible manage auth-file add); this writes an auth.json into your config directory. The two values a runner needs are:

• adp_token
• device_private_key (a PEM block)

Add them as repository secrets and your marketplace as a plain variable. With gh and jq you can read both straight from auth.json:

jq -r .device_private_key auth.json | gh secret set AUDIBLE_DEVICE_PRIVATE_KEY
jq -r .adp_token          auth.json | gh secret set AUDIBLE_ADP_TOKEN
gh variable set AUDIBLE_COUNTRY_CODE --body de   # your Audible marketplace

Then the workflow is just:

name: Audible export

on:
  workflow_dispatch:
  schedule:
    - cron: "0 8 * * *"

jobs:
  export:
    runs-on: ubuntu-latest
    steps:
      - uses: mkb79/setup-audible-cli@v1
        with:
          adp-token: ${{ secrets.AUDIBLE_ADP_TOKEN }}
          device-private-key: ${{ secrets.AUDIBLE_DEVICE_PRIVATE_KEY }}
          country-code: ${{ vars.AUDIBLE_COUNTRY_CODE }}

      - run: audible library export --format json --output library.json

Only these two values are stored as secrets; access and refresh tokens, cookies, and account details are never uploaded, and the runner's auth files exist only for the lifetime of the job. See the setup-audible-cli action for its full set of inputs and outputs.

⚠️ These credentials grant access to your Audible account. Run authenticated workflows only from trusted branches, scheduled runs, or manual dispatches, never from arbitrary pull-request code.

A live example: earshot refreshes its data from Audible on a daily schedule using this action.

Built-in commands

• activation-bytes → Manage DRM activation keys
• api → Call raw Audible API endpoints
• download → Download audiobooks
• library → List, export your library
• wishlist → Manage wishlist (list, add, remove, export)
• manage → Profiles, configs, auth-files
• quickstart → Interactive setup

Show help:

audible  -h

Plugins & Extensions

Custom plugin commands

Create a file in the plugin folder, e.g. cmd_hello.py:

import click

@click.command(name="hello")
def cli():
    click.echo("Hello from plugin!")

Important: A custom plugin must start with the prefix cmd_. The loader scans for cmd_*.py files and attaches each command to the CLI.

Run:

audible hello

Plugin packages

You can also distribute plugins as Python packages via entry points.
The entry point group is audible.cli_plugins.

Example: pyproject.toml

[project]
name = "audible-myplugin"
version = "0.1.0"
dependencies = ["audible-cli", "click"]

[project.entry-points."audible.cli_plugins"]
my_command = "myplugin.cli:my_command"
another    = "myplugin.cli:another"

After installation, your plugin commands will automatically be available in audible:

audible my-command
audible another

Verbosity

Control logging output:

audible -v debug library list
audible -v error download --all

Levels: debug, info, warning, error, critical
Default: info

Output and diagnostics

Every command keeps its two streams apart. stdout carries the result you asked for: an API response, a list of titles, the activation bytes. stderr carries everything else — progress, warnings, errors, and the questions an interactive command asks. So a pipe only ever receives the payload:

audible api library | jq '.items[].title'
audible library list > titles.txt

To keep a record of a run, use --log-file rather than redirecting a stream. It writes the same log with a timestamp, module and line, follows `--verbos