Command Line Interface

The YouVersion Bible Client includes a comprehensive command-line interface for easy access to all features.

Installation

The CLI is automatically available when you install the package:

# Using Poetry (recommended)
poetry install
poetry run youversion --help

# Or using pip
pip install -e .
youversion --help

Basic Usage

The CLI provides several commands for accessing different types of data:

# Get verse of the day
poetry run youversion votd

# Get moments
poetry run youversion moments

# Get highlights
poetry run youversion highlights

# Get notes
poetry run youversion notes

# Get bookmarks
poetry run youversion bookmarks

# Get images
poetry run youversion images

# Get plan progress
poetry run youversion plan-progress

# Get plan subscriptions
poetry run youversion plan-subscriptions

# Convert notes to markdown
poetry run youversion convert-notes

Global Options

All commands support these global options:

--json: Output results in JSON format instead of human-readable format.

--limit LIMIT: Limit the number of items displayed (default: 10).

Command Reference

votd

Get the verse of the day.

poetry run youversion votd [--day DAY] [--json]

Options:

--day DAY: Specific day number (1-365) --json: Output as JSON

Examples:

poetry run youversion votd

poetry run youversion votd --day 100

poetry run youversion votd --json

moments

Get user moments.

poetry run youversion moments [--page PAGE] [--limit LIMIT] [--json]

Options:: --page PAGE: Page number (default: 1) --limit LIMIT: Number of items to display (default: 10) --json: Output as JSON
Examples:: poetry run youversion moments poetry run youversion moments --page 2 poetry run youversion moments --limit 5 --json

highlights

Get user highlights.

poetry run youversion highlights [--page PAGE] [--limit LIMIT] [--json]

Options:: --page PAGE: Page number (default: 1) --limit LIMIT: Number of items to display (default: 10) --json: Output as JSON
Examples:: poetry run youversion highlights poetry run youversion highlights --page 2 --limit 5

notes

Get user notes.

poetry run youversion notes [--page PAGE] [--limit LIMIT] [--json]

Options:: --page PAGE: Page number (default: 1) --limit LIMIT: Number of items to display (default: 10) --json: Output as JSON
Examples:: poetry run youversion notes poetry run youversion notes --json

bookmarks

Get user bookmarks.

poetry run youversion bookmarks [--page PAGE] [--limit LIMIT] [--json]

Options:: --page PAGE: Page number (default: 1) --limit LIMIT: Number of items to display (default: 10) --json: Output as JSON
Examples:: poetry run youversion bookmarks poetry run youversion bookmarks --page 1

images

Get user images.

poetry run youversion images [--page PAGE] [--limit LIMIT] [--json]

Options:: --page PAGE: Page number (default: 1) --limit LIMIT: Number of items to display (default: 10) --json: Output as JSON
Examples:: poetry run youversion images poetry run youversion images --json

plan-progress

Get reading plan progress.

poetry run youversion plan-progress [--page PAGE] [--limit LIMIT] [--json]

Options:: --page PAGE: Page number (default: 1) --limit LIMIT: Number of items to display (default: 10) --json: Output as JSON
Examples:: poetry run youversion plan-progress poetry run youversion plan-progress --limit 5

plan-subscriptions

Get reading plan subscriptions.

poetry run youversion plan-subscriptions [--page PAGE] [--limit LIMIT] [--json]

Options:: --page PAGE: Page number (default: 1) --limit LIMIT: Number of items to display (default: 10) --json: Output as JSON
Examples:: poetry run youversion plan-subscriptions poetry run youversion plan-subscriptions --json

convert-notes

Convert notes to markdown format.

poetry run youversion convert-notes [--json]

Options:: --json: Output as JSON
Examples:: poetry run youversion convert-notes poetry run youversion convert-notes --json

badges

Get user badges.

poetry run youversion badges [--page PAGE] [--limit LIMIT] [--json]

Options:: --page PAGE: Page number (default: 1) --limit LIMIT: Number of items to display (default: 10) --json: Output as JSON
Examples:: poetry run youversion badges poetry run youversion badges --page 1

create-moment

Create a new moment (note, highlight, etc.).

poetry run youversion create-moment --kind KIND --content CONTENT --title TITLE [options]

Options:: --kind KIND: Moment kind (note, highlight, bookmark, etc.) --content CONTENT: Moment content (required) --title TITLE: Moment title (required) --status STATUS: Status (private, draft, public) --body BODY: Body text --color COLOR: Highlight color (hex code) --language-tag TAG: Language tag (e.g., ‘en’) --references REFS: Bible references --labels LABELS: Labels/tags --json: Output as JSON
Examples:: poetry run youversion create-moment --kind note --content "My note" --title "Title" poetry run youversion create-moment --kind highlight --content "Text" --title "Title" --color ff0000

get-bible-configuration

Get Bible configuration.

poetry run youversion get-bible-configuration [--json]

Options:: --json: Output as JSON
Examples:: poetry run youversion get-bible-configuration

get-bible-versions

Get Bible versions for a language.

poetry run youversion get-bible-versions [--language-tag TAG] [--json]

Options:: --language-tag TAG: Language tag (default: ‘eng’) --json: Output as JSON
Examples:: poetry run youversion get-bible-versions poetry run youversion get-bible-versions --language-tag spa

get-bible-version

Get specific Bible version details.

poetry run youversion get-bible-version VERSION_ID [--json]

Arguments:: VERSION_ID: Version ID (required)
Options:: --json: Output as JSON
Examples:: poetry run youversion get-bible-version 1

get-bible-chapter

Get Bible chapter content.

poetry run youversion get-bible-chapter REFERENCE [--version-id ID] [--json]

Arguments:: REFERENCE: USFM reference (e.g., ‘GEN.1’, ‘JHN.3.16’) (required)
Options:: --version-id ID: Version ID (default: 1) --json: Output as JSON
Examples:: poetry run youversion get-bible-chapter GEN.1 poetry run youversion get-bible-chapter JHN.3.16 --version-id 1

search-bible

Search Bible text.

poetry run youversion search-bible QUERY [--version-id ID] [--book BOOK] [--json]

Arguments:: QUERY: Search query (required)
Options:: --version-id ID: Version ID to search in --book BOOK: Book filter (e.g., ‘JHN’, ‘GEN’) --json: Output as JSON
Examples:: poetry run youversion search-bible "love" poetry run youversion search-bible "love" --version-id 1 poetry run youversion search-bible "love" --book JHN

get-themes

Get available themes.

poetry run youversion get-themes [--language-tag TAG] [--json]

Options:: --language-tag TAG: Language tag (default: ‘eng’) --json: Output as JSON
Examples:: poetry run youversion get-themes poetry run youversion get-themes --language-tag spa

send-friend-request

Send a friend request to a user.

poetry run youversion send-friend-request USER_ID [--json]

Arguments:: USER_ID: User ID to send friend request to (required)
Options:: --json: Output as JSON
Examples:: poetry run youversion send-friend-request 123456

Note

For a complete list of all 47+ commands, run:

poetry run youversion --help

Configuration

Environment Variables

The CLI reads credentials from environment variables:

export YOUVERSION_USERNAME=your_username
export YOUVERSION_PASSWORD=your_password

Or create a .env file in your project root:

YOUVERSION_USERNAME=your_username
YOUVERSION_PASSWORD=your_password

Poetry Scripts

All 47+ CLI commands are available as Poetry scripts for easier access:

Moments & Content: .. code-block:: bash

poetry run votd # Get verse of the day poetry run moments # Get moments poetry run highlights # Get highlights poetry run notes # Get notes poetry run bookmarks # Get bookmarks poetry run images # Get images poetry run badges # Get badges poetry run create-moment # Create a moment poetry run convert-notes # Convert notes to markdown

Plans: .. code-block:: bash

poetry run plan-progress # Get plan progress poetry run plan-subscriptions # Get plan subscriptions poetry run plan-completions # Get plan completions

Bible & Audio: .. code-block:: bash

poetry run get-bible-configuration # Get Bible configuration poetry run get-bible-versions # Get Bible versions poetry run get-bible-version # Get Bible version by ID poetry run get-bible-chapter # Get Bible chapter poetry run get-recommended-languages # Get recommended languages poetry run get-audio-chapter # Get audio chapter poetry run get-audio-version # Get audio version

Search: .. code-block:: bash

poetry run search-bible # Search Bible poetry run search-plans # Search plans poetry run search-users # Search users

Videos & Images: .. code-block:: bash

poetry run get-videos # Get videos poetry run get-video-details # Get video details poetry run get-images # Get images poetry run get-image-upload-url # Get image upload URL

Events: .. code-block:: bash

poetry run search-events # Search events poetry run get-event-details # Get event details poetry run get-saved-events # Get saved events poetry run save-event # Save event poetry run delete-saved-event # Delete saved event poetry run get-all-saved-event-ids # Get all saved event IDs poetry run get-event-configuration # Get event configuration

Moments Management: .. code-block:: bash

poetry run get-moments # Get moments poetry run get-moment-details # Get moment details poetry run update-moment # Update moment poetry run delete-moment # Delete moment poetry run get-moment-colors # Get moment colors poetry run get-moment-labels # Get moment labels poetry run get-verse-colors # Get verse colors poetry run hide-verse-colors # Hide verse colors poetry run get-moments-configuration # Get moments configuration

Comments & Likes: .. code-block:: bash

poetry run create-comment # Create comment poetry run delete-comment # Delete comment poetry run like-moment # Like moment poetry run unlike-moment # Unlike moment

Devices: .. code-block:: bash

poetry run register-device # Register device poetry run unregister-device # Unregister device

Themes: .. code-block:: bash

poetry run get-themes # Get themes poetry run add-theme # Add theme poetry run remove-theme # Remove theme poetry run set-theme # Set theme poetry run get-theme-description # Get theme description

Social: .. code-block:: bash

poetry run send-friend-request # Send friend request

Localization: .. code-block:: bash

poetry run get-localization-items # Get localization items

Makefile Commands

All commands are also available via Makefile targets:

# Moments & Content
make cli-votd
make cli-moments
make cli-highlights
make cli-notes
make cli-bookmarks
make cli-images
make cli-badges
make cli-create-moment KIND='note' CONTENT='...' TITLE='...'
make cli-convert-notes

# Plans
make cli-plan-progress
make cli-plan-subscriptions
make cli-plan-completions

# Bible & Audio
make cli-get-bible-configuration
make cli-get-bible-versions
make cli-get-bible-version ID=1
make cli-get-bible-chapter REFERENCE='GEN.1' VERSION_ID=1
make cli-get-recommended-languages
make cli-get-audio-chapter REFERENCE='GEN.1' VERSION_ID=1
make cli-get-audio-version ID=1

# Search
make cli-search-bible QUERY='love' VERSION_ID=1
make cli-search-plans QUERY='daily' LANGUAGE_TAG='en'
make cli-search-users QUERY='john'

# See all commands: make help

Output Formats

Standardized Format

All CLI commands use a standardized output format that displays: - ID: Item identifier - Kind: Item type (e.g., NOTE, HIGHLIGHT, PLAN_SEGMENT_COMPLETION.V1) - Metadata: Key-value pairs from base/title/l_args (e.g., Segment, Title, etc.) - Time: Creation timestamp

All fields are consistently aligned for easy reading:

1. PLAN_SEGMENT_COMPLETION.V1
   ID         : 4892085495582558077
   Kind       : PLAN_SEGMENT_COMPLETION.V1
   Segment    : 1
   Title      : Teach Us To Pray
   Time       : 2025-11-22T19:00:35+00:00

2. NOTE
   ID         : 1234567890
   Kind       : NOTE
   Content    : This is my note
   Time       : 2025-11-22T18:00:00+00:00

Human-Readable Format

By default, the CLI outputs data in a human-readable format:

📖 Verse of the Day
Day: 1
USFM: JHN.3.16
Image ID: None

📋 Moments (Page 1)
Found 5 moments
--------------------------------------------------
  1. PLAN_SEGMENT_COMPLETION.V1
     ID         : 4892085495582558077
     Kind       : PLAN_SEGMENT_COMPLETION.V1
     Segment    : 1
     Title      : Teach Us To Pray
     Time       : 2025-11-22T19:00:35+00:00

JSON Format

Use the --json flag for machine-readable output:

{
  "day": 1,
  "usfm": ["JHN.3.16"],
  "image_id": null
}

Error Handling

The CLI provides clear error messages for common issues:

❌ Error: Missing credentials
Please set YOUVERSION_USERNAME and YOUVERSION_PASSWORD environment variables
Or create a .env file with your credentials:

YOUVERSION_USERNAME=your_username
YOUVERSION_PASSWORD=your_password

Exit Codes

0: Success
1: Error (authentication, API, or other errors)

Examples

Basic Usage

# Get today's verse
poetry run youversion votd

# Get first 5 highlights
poetry run youversion highlights --limit 5

# Get moments from page 2 as JSON
poetry run youversion moments --page 2 --json

Advanced Usage

# Get verse for day 100
poetry run youversion votd --day 100

# Get all notes as JSON for processing
poetry run youversion notes --json > notes.json

# Convert notes to markdown
poetry run youversion convert-notes --json > notes.md