Command-Line Interface Reference

This document provides a detailed reference for the Export Trakt for Letterboxd command-line interface, including all commands, options, and usage examples.

Basic Usage

The basic syntax for using the command-line interface is:

export-trakt [command] [options]

Available Commands

Command	Description
export	Export data from Trakt.tv (default)
schedule	Run scheduler
setup	Show setup instructions
validate	Validate configuration
auth	Interactive OAuth authentication
auth-url	Generate and display OAuth URL
auth-code	Manual authentication with authorization code
server	Start persistent OAuth & export server
fix-permissions	Fix credentials file permissions for Docker
token-status	Check authentication token status
token-refresh	Manually refresh access token
token-clear	Clear stored authentication tokens

Options

Option	Description	Default	Example
--config	Path to the configuration file	./config/config.toml	--config custom.toml
--export	Type of export	watched	--export all
--mode	Export mode	normal	--mode complete
--run	Run the script immediately once then exit	false	--run
--schedule	Run according to cron schedule format	(none)	--schedule "0 */6 * * *"

Execution Modes

The application supports three different execution modes:

Standard Mode (Default)

Execute using the traditional command-based approach:

export-trakt export --export watched --mode complete

Immediate Execution Mode (--run)

Execute the export immediately once and then exit:

export-trakt --run --export all --mode complete

Scheduled Mode (--schedule)

Execute the export according to a cron schedule:

export-trakt --schedule "0 */6 * * *" --export all --mode complete

Export Types

The --export option accepts the following values:

• watched: Export your watched movies
• collection: Export your movie collection
• shows: Export your watched TV shows
• ratings: Export your movie ratings
• watchlist: Export your movie watchlist
• all: Export all of the above data types

Export Modes

The --mode option accepts the following values:

• normal: Standard export mode
• initial: Initial setup export
• complete: Complete export with all data

Scheduling Format

The --schedule option uses the standard cron format:

minute hour day-of-month month day-of-week

Cron Schedule Examples

Schedule	Description
0 */6 * * *	Every 6 hours
0 9 * * 1	Every Monday at 9:00 AM
30 14 * * *	Every day at 2:30 PM
0 0 1 * *	First day of every month at midnight
*/15 * * * *	Every 15 minutes

Authentication Commands

The application provides several commands for managing OAuth authentication:

auth - Interactive OAuth Authentication

Launches the interactive OAuth authentication flow:

export-trakt auth

This command:

• Generates an authorization URL
• Starts a local callback server
• Exchanges authorization code for tokens
• Stores tokens securely

auth-url - Generate OAuth URL

Generates and displays the OAuth authentication URL without starting a server:

export-trakt auth-url

This command:

• Generates the OAuth authorization URL
• Displays step-by-step authentication instructions
• Provides the exact commands needed to complete authentication
• Useful for Docker environments or when you want to see the URL first

token-status - Check Token Status

Displays the current authentication token status:

export-trakt token-status

Shows information about:

• Token validity
• Expiration time
• Refresh token availability
• Current authentication state

token-refresh - Manual Token Refresh

Manually refreshes the access token:

export-trakt token-refresh

Useful for:

• Testing token refresh functionality
• Force refreshing before expiration
• Troubleshooting authentication issues

token-clear - Clear Stored Tokens

Removes all stored authentication tokens:

export-trakt token-clear

Use when:

• Switching between different Trakt.tv accounts
• Troubleshooting authentication issues
• Resetting authentication state

fix-permissions - Fix Credentials File Permissions

Diagnoses and fixes file permission issues with the credentials storage file:

export-trakt fix-permissions

This command:

• Checks the current permissions of the credentials file
• Detects if running in a Docker environment
• Applies appropriate permission fixes for the environment
• Provides guidance for alternative solutions

Useful when:

• You encounter "file permissions must be 0600 for security" errors
• Running in Docker environments where permission handling differs
• Troubleshooting credential storage issues
• Setting up the application for the first time

Alternative Solutions

If fix-permissions doesn't resolve your issues, consider using the environment variable backend:

1. Update your config.toml:

   [security]
   keyring_backend = "env"
   

2. Set environment variables:

   export TRAKT_CLIENT_ID="your_client_id"
   export TRAKT_CLIENT_SECRET="your_client_secret"
   

3. For Docker, add these to your docker-compose.yml:

   environment:
     - TRAKT_CLIENT_ID=your_client_id
     - TRAKT_CLIENT_SECRET=your_client_secret
   

📘 Note: For detailed OAuth setup instructions, see the OAuth Authentication Guide.

Configuration File

Most of the application's behavior is controlled by the configuration file (config.toml). This includes:

• Trakt API credentials
• OAuth authentication settings
• Export directory and file naming
• Logging configuration
• Internationalization settings

Usage Examples

Export Watched Movies (Traditional)

Export your watched movies using the traditional command approach:

export-trakt export --export watched

Immediate One-Time Export

Run the export immediately once and exit:

# Export all data immediately
export-trakt --run --export all --mode complete

# Export only watched movies immediately
export-trakt --run --export watched --mode normal

Scheduled Export

Set up a scheduled export that runs automatically:

# Export all data every 6 hours
export-trakt --schedule "0 */6 * * *" --export all --mode complete

# Export watched movies every day at 2:30 PM
export-trakt --schedule "30 14 * * *" --export watched --mode normal

# Export collection every Monday at 9:00 AM
export-trakt --schedule "0 9 * * 1" --export collection --mode complete

Export Your Collection

Export your movie collection:

export-trakt --run --export collection

Export Your Watchlist

Export your movie watchlist:

export-trakt --run --export watchlist

Export Your Ratings

Export your movie ratings:

export-trakt --run --export ratings

Export TV Shows

Export your watched TV shows:

export-trakt --run --export shows

Export Everything

Export all available data:

export-trakt --run --export all

Automatic Authentication Detection

The application automatically detects when OAuth authentication is required and provides helpful guidance:

First-Time Authentication

When you run an export command without authentication, the application will display:

🔐 AUTHENTICATION REQUIRED
==========================================
📱 Client ID: your_client_id_here
🔗 Redirect URI: http://localhost:8080/callback

🚀 QUICK AUTHENTICATION:
1. Open this URL in your browser:
   https://trakt.tv/oauth/authorize?...

2. Authorize the application on Trakt.tv
3. Run this command to complete authentication:
   docker run --rm -v "$(pwd)/config:/app/config" -p 8080:8080 trakt-exporter auth

4. Once authenticated, re-run this export command

💡 Authentication only needs to be done once.
   Tokens will be automatically refreshed afterwards.
==========================================

This makes the authentication process seamless, especially in Docker environments.

Using a Different Configuration File

Use an alternative configuration file:

export-trakt --run --config ~/custom_config.toml --export all

Advanced Scheduling Examples

# High-frequency monitoring (every 15 minutes)
export-trakt --schedule "*/15 * * * *" --export watched --mode normal

# Daily backup at midnight
export-trakt --schedule "0 0 * * *" --export all --mode complete

# Weekly comprehensive export
export-trakt --schedule "0 3 * * 0" --export all --mode complete

Export File Format

The exported files will be CSV files formatted to be compatible with Letterboxd's import system. Files are saved in the directory specified in the configuration file (default: ./exports/).

Exit Codes

The application uses the following exit codes to indicate different outcomes:

Code	Description
0	Success
1	General error