docs/advanced/command-line-interface.md
Libationcli.exe allows limited access to Libation's functionalities as a CLI.
Warnings about relying solely on the CLI:
The liberate and convert commands show a progress bar in the terminal while downloading or converting (e.g. [##########----------] 2.5 min remaining). The progress bar is only shown when the CLI is run interactively with output not redirected.
To turn off the progress bar (for scripting, logging, or cleaner output), redirect standard output and/or standard error. The progress bar is automatically disabled when either stream is redirected.
libationcli liberate > log.txt 2>&1
libationcli convert 2> errors.txt
Redirecting also avoids progress-bar control characters in log files.
LibationCli uses a verb-first layout: the first argument is always a command name (for example scan, liberate).
Global help — list every verb and its short description (use this when you are not sure which verb to run):
libationcli --help
libationcli -h
On Windows, /?, /h, and /help are also accepted when they are the only argument.
Verb-specific help — options for a single command:
libationcli scan --help
libationcli scan -h
The help verb is equivalent for many cases: libationcli help scan.
Help-only invocations exit with status code 0 (success), so scripts can treat them as non-errors.
All verbs use the same Libation data directory as the GUI (where AccountsSettings.json and Settings.json live). To point the CLI elsewhere:
libationcli --libationFiles "D:\path\to\LibationFiles" scan
You can also set the environment variable LIBATION_FILES_DIR to that directory instead of passing --libationFiles every time.
Imports a single account from a JSON file in the format produced by mkb79's audible-cli export (Libation's GUI export to the same format is compatible). The file is validated, tokens are refreshed, and the account is appended to AccountsSettings.json unless the same account id and locale already exist.
libationcli import-account "C:\path\to\account.json"
libationcli import-account /home/me/Audible/account.json
Use libationcli import-account --help for the exact options on your build.
login-external)For headless servers or when you prefer not to use the GUI, this verb performs the same external browser OAuth flow as Libation's alternate login: the CLI prints a sign-in URL, you complete login in your own browser, then supply the full URL shown in the browser after Audible redirects you (it is normal if that page looks broken or says the page does not exist).
Required flags:
--account / -a — Your Audible login id (email).--locale / -l — Marketplace code, same as in the GUI (for example us, uk, de).Interactive use (terminal attached to a keyboard):
libationcli login-external --account [email protected] --locale us
Non-interactive use (stdin redirected, Docker without -t, scripts): pass the post-login URL explicitly:
libationcli login-external -a [email protected] -l us --response-url "https://www.amazon.com/ap/maplanding?..."
If the account row already has valid saved tokens, the CLI reports that no browser login is needed and exits without opening the flow.
Use libationcli login-external --help for the exact options on your build.
list-accounts)Prints each row from AccountsSettings.json: Audible login id, optional nickname, marketplace (us, uk, …), whether Scan library is enabled for that account, and whether stored identity tokens are currently valid (the same check login-external uses before starting a browser flow). Use this on headless setups to see which accounts still need login-external or import-account.
libationcli list-accounts
libationcli list-accounts --bare
--bare (-b) prints tab-separated values with no table: account id, name, locale, scan library (yes / no), authenticated (yes / no), for scripts and cut / awk.
Scan library (yes / no) is the same checkbox as "Include in library scan?" in Accounts: it controls whether the main Libation app includes that account in automatic scans (startup / periodic scan behavior). It does not restrict libationcli scan with no arguments, which still imports from every configured account unless you pass specific account nicknames or ids.
If no accounts exist yet, the CLI prints No accounts configured. and exits successfully.
libationcli scan
libationcli scan nickname1 nickname2
libationcli convert
libationcli liberate
libationcli liberate --pdf
libationcli liberate -p
libationcli liberate --force
libationcli liberate -f
get-license commandlibationcli liberate --license /path/to/license.lic
libationcli liberate --license - < /path/to/license.lic
libationcli get-setting
libationcli get-setting -b
libationcli get-setting FileDownloadQuality
libationcli liberate B017V4IM1G -override FileDownloadQuality=Normal
libationcli liberate B017V4IM1G -o FileDownloadQuality=normal -o UseWidevine=true Request_xHE_AAC=true -f
libationcli copydb --connectionString "my postgres connection string"
libationcli copydb -c "my postgres connection string"
libationcli export --path "C:\foo\bar\my.json" --json
libationcli export -p "C:\foo\bar\my.json" -j
libationcli export -p "C:\foo\bar\my.csv" --csv
libationcli export -p "C:\foo\bar\my.csv" -c
libationcli export -p "C:\foo\bar\my.xlsx" --xlsx
libationcli export -p "C:\foo\bar\my.xlsx" -x
Set download statuses throughout library based on whether each book's audio file can be found.
Must include at least one flag: --downloaded , --not-downloaded.
Downloaded: If the audio file can be found, set download status to 'Downloaded'.
Not Downloaded: If the audio file cannot be found, set download status to 'Not Downloaded'
UI: Visible Books > Set 'Downloaded' status automatically. Visible books. Prompts before saving changes
CLI: Full library. No prompt
libationcli set-status -d
libationcli set-status -n
libationcli set-status -d -n
libationcli get-license B017V4IM1G
$asin="B017V4IM1G"
$xHE_AAC=@('true', 'false')
$Qualities=@('Normal', 'High')
foreach($q in $Qualities){
foreach($x in $xHE_AAC){
$license = ./libationcli get-license $asin --override FileDownloadQuality=$q --override Request_xHE_AAC=$x
echo $($license | ConvertFrom-Json).ContentMetadata.content_reference
echo $license | ./libationcli liberate --force --license -
}
}
Libation detects the replacment characters for filenames by identifying the currently running OS and not the target filesystem. This can lead to problems when running the Libation CLI on Linux but targeting an NTFS drive for the download.
To change (and override) the replacment characters, the code snippet below can
be defined in the Settings.json. The example below contains the HiFi_NTFS
replacements that allow for high fidelity filenames when targeting an NTFS file
system.
::: details Example NTFS ReplacementCharacters
"ReplacementCharacters": {
"Replacement": [
{
"CharacterToReplace": "\u0000",
"ReplacementString": "_",
"Description": "All other invalid characters"
},
{
"CharacterToReplace": "/",
"ReplacementString": "∕",
"Description": "Forward Slash (Filename Only)"
},
{
"CharacterToReplace": "\\",
"ReplacementString": "",
"Description": "Back Slash (Filename Only)"
},
{
"CharacterToReplace": "\"",
"ReplacementString": "“",
"Description": "Open Quote"
},
{
"CharacterToReplace": "\"",
"ReplacementString": "”",
"Description": "Close Quote"
},
{
"CharacterToReplace": "\"",
"ReplacementString": "＂",
"Description": "Other Quote"
},
{
"CharacterToReplace": "<",
"ReplacementString": "＜",
"Description": "Open Angle Bracket"
},
{
"CharacterToReplace": ">",
"ReplacementString": "＞",
"Description": "Close Angle Bracket"
},
{
"CharacterToReplace": ":",
"ReplacementString": "_",
"Description": "Colon"
},
{
"CharacterToReplace": "*",
"ReplacementString": "✱",
"Description": "Asterisk"
},
{
"CharacterToReplace": "?",
"ReplacementString": "？",
"Description": "Question Mark"
},
{
"CharacterToReplace": "|",
"ReplacementString": "⏐",
"Description": "Vertical Line"
}
]
}
:::