Goondex/docs/CLI_REFERENCE.md

CLI Reference

Complete command-line interface documentation for Goondex.

Global Flags

--db string   Path to SQLite database (default "./goondex.db")

Commands

goondex version

Print version information.

Usage:

goondex version

Output:

Goondex v0.1.0-dev2

---

goondex performer-search

Search for performers in the local database.

Usage:

goondex performer-search [query]

Arguments:

• query - Search term (searches name and aliases)

Examples:

# Search for performers matching "Riley"
goondex performer-search "Riley"

# Search with wildcards (SQL LIKE syntax)
goondex performer-search "Riley%"

Output Format:

Found 3 performer(s):

ID: 1
Name: Riley Reid
Aliases: Paige Riley
Country: United States
Gender: female
---

---

goondex studio-search

Search for studios in the local database.

Usage:

goondex studio-search [query]

Arguments:

• query - Search term (searches studio name)

Examples:

# Search for studios matching "Brazzers"
goondex studio-search "Brazzers"

Output Format:

Found 2 studio(s):

ID: 1
Name: Brazzers
Description: Premium adult entertainment network
---

---

goondex scene-search

Search for scenes in the local database.

Usage:

goondex scene-search [query]

Arguments:

• query - Search term (searches title and code)

Examples:

# Search for scenes matching "Big Wet Butts"
goondex scene-search "Big Wet Butts"

# Search by DVD code
goondex scene-search "BWB-2024-01"

Output Format:

Found 5 scene(s):

ID: 1
Title: Big Wet Butts 24
Code: BWB-024
Date: 2024-01-15
Description: The hottest scenes featuring...
---

---

Import Commands

goondex import performer

Search ThePornDB for performers and import them to the local database.

Usage:

goondex import performer [query]

Arguments:

• query - Search term for TPDB

Environment Variables:

• TPDB_API_KEY - Required. Your ThePornDB API key

Examples:

# Set API key
export TPDB_API_KEY="your-api-key-here"

# Import performers matching "Riley Reid"
goondex import performer "Riley Reid"

Output:

Searching TPDB for performers matching 'Riley Reid'...
Found 1 performer(s) on TPDB

Importing: Riley Reid (TPDB ID: 12345)
  ✓ Imported with local ID: 1

✓ Successfully imported 1/1 performers

Error Handling:

• If TPDB_API_KEY is not set: Error message
• If no results found: "No performers found on TPDB"
• If import fails: Warning with error details, continues to next

---

goondex import studio

Search ThePornDB for studios and import them to the local database.

Usage:

goondex import studio [query]

Arguments:

• query - Search term for TPDB

Environment Variables:

• TPDB_API_KEY - Required

Examples:

# Import studios matching "Brazzers"
goondex import studio "Brazzers"

Output:

Searching TPDB for studios matching 'Brazzers'...
Found 2 studio(s) on TPDB

Importing: Brazzers (TPDB ID: 100)
  ✓ Imported with local ID: 1
Importing: Brazzers Network (TPDB ID: 101)
  ✓ Imported with local ID: 2

✓ Successfully imported 2/2 studios

---

goondex import scene

Search ThePornDB for scenes and import them to the local database.

This command also imports related performers, studios, and tags.

Usage:

goondex import scene [query]

Arguments:

• query - Search term for TPDB

Environment Variables:

• TPDB_API_KEY - Required

Examples:

# Import scenes matching "Big Wet Butts"
goondex import scene "Big Wet Butts"

Output:

Searching TPDB for scenes matching 'Big Wet Butts'...
Found 3 scene(s) on TPDB

Importing: Big Wet Butts 24 (TPDB ID: 54321)
  ✓ Imported with local ID: 1

✓ Successfully imported 3/3 scenes

Automatic Imports: When importing a scene, Goondex automatically:

1. Imports the studio (if not already present)
2. Imports all performers (if not already present)
3. Imports all tags (if not already present)
4. Links performers and tags to the scene

---

Configuration

Database Location

Override the default database location:

goondex --db /path/to/custom.db performer-search "Riley"

Environment Variables

Variable	Required	Default	Description
TPDB_API_KEY	Yes*	-	ThePornDB API key

*Required only for import commands

Getting a TPDB API Key

1. Register at https://theporndb.net/register
2. Navigate to https://theporndb.net/user/api-tokens
3. Generate a new API token
4. Export it: export TPDB_API_KEY="your-key"

---

Exit Codes

Code	Meaning
0	Success
1	General error

---

Examples

Complete Workflow

# 1. Set up API key
export TPDB_API_KEY="DNdmkEPlUTWWDuT98jYcxCIfAxReDrHJ55PyCGru496ae577"

# 2. Import a performer
goondex import performer "Riley Reid"

# 3. Import a studio
goondex import studio "Brazzers"

# 4. Import scenes
goondex import scene "Big Wet Butts"

# 5. Search local database
goondex performer-search "Riley"
goondex studio-search "Brazzers"
goondex scene-search "Big Wet"

Custom Database Location

# Use a different database
export GOONDEX_DB="/mnt/storage/media.db"
goondex --db "$GOONDEX_DB" import performer "Riley Reid"
goondex --db "$GOONDEX_DB" performer-search "Riley"

---

Troubleshooting

"TPDB_API_KEY environment variable is not set"

Solution: Export your API key before running import commands:

export TPDB_API_KEY="your-key-here"

"No performers found on TPDB"

Possible Causes:

1. Typo in search query
2. TPDB doesn't have that performer
3. API rate limiting (wait a minute and retry)

"API returned status 401"

Cause: Invalid or expired API key

Solution:

1. Verify your API key at https://theporndb.net/user/api-tokens
2. Generate a new key if needed
3. Update your environment variable

"API returned status 429"

Cause: Rate limiting

Solution: Wait 60 seconds and retry

---

Future Commands (Planned)

v0.2.x

• goondex identify --scene-id <id> - Match local scene to TPDB
• goondex sync - Sync all data from TPDB
• goondex tui - Launch interactive browser

v0.3.x

• goondex daemon start - Start background service
• goondex daemon stop - Stop background service
• goondex daemon status - Check daemon status