Skip to main content

​
Introduction

The TikTok Miner CLI is a command-line tool for querying and managing the TikTok Miner database. Built with Commander.js and TypeScript, it provides developers with direct database access.
The CLI is currently in early development. Many planned features are not yet implemented in the source code. This documentation describes the current query-db command and planned future capabilities.

​
Installation

The CLI is bundled with the TikTok Miner application. To use it: 
bun cli/index.ts <command> [options]

​
Available Commands

Currently, the CLI implements the following command:

​
Database Operations

  • query-db - Query and explore database contents with SQL
    • Execute custom SQL queries against PostgreSQL
    • Query creator profiles, metrics, and analytics
    • Access budget and cost tracking data
Additional command groups (creators, discovery) are planned but not yet fully implemented in the codebase. The CLI entry point references these modules but the implementation files are pending.

​
Planned Commands

The following commands are referenced in the CLI architecture but pending implementation:
  • creators - Creator profile management (planned)
  • discovery - Discovery pipeline operations (planned)
  • db - Extended database utilities (planned)
  • analysis - Analytics and reporting (planned)

​
Global Options

All commands support these global options: 
-V, --version        Output the version number
-h, --help          Display help for command

​
Environment Configuration

The CLI requires environment variables to be configured. Create a .env file in the project root: 
# Required: Database connection
DATABASE_URL=postgresql://user:password@localhost:5432/tiktok_miner
DIRECT_URL=postgresql://user:password@localhost:5432/tiktok_miner

# Optional: For future features
APIFY_API_TOKEN=your_apify_token
OPENAI_API_KEY=your_openai_key

​
Quick Start

​
Query Database

Execute a raw SQL query: 
bun cli/index.ts query-db "SELECT * FROM \"CreatorProfile\" LIMIT 10"
Query TikTok profiles: 
bun cli/index.ts query-db "SELECT username, \"followerCount\" FROM \"TiktokProfile\" ORDER BY \"followerCount\" DESC LIMIT 20"

​
Check CLI Version

bun cli/index.ts --version

​
Get Help

bun cli/index.ts --help
bun cli/index.ts query-db --help

​
Output Formats

The CLI supports multiple output formats:
  • Table (default): Human-readable table format
  • JSON: Machine-readable JSON output
  • CSV: Spreadsheet-compatible format

​
Command Structure

The CLI follows this general structure: 
tiktok-miner <command> [subcommand] [options] [arguments]
Examples: 
# Database query
tiktok-miner query-db --username john_doe

# Raw SQL
tiktok-miner query-db "SELECT * FROM creators"

​
Development Status

The TikTok Miner CLI is under active development. Current status: ✅ Implemented:
  • Basic CLI framework with Commander.js
  • query-db command structure
  • Version and help commands
⏳ In Progress:
  • Query result formatting
  • Creator management commands
  • Discovery pipeline integration
📋 Planned:
  • Export functionality
  • Batch operations
  • Analytics commands
  • Reporting tools

Database Commands

Detailed query-db command reference

Database Setup

Database schema and configuration

Environment Variables

Complete configuration reference

API Monitoring

Monitor CLI operations and costs

​
Troubleshooting

Ensure you’re running the CLI from the app/ directory where cli/index.ts is located.
cd app
bun cli/index.ts --help
Verify your DATABASE_URL is correct and the PostgreSQL server is running:
# Check if PostgreSQL is running
docker-compose ps postgres

# Test connection
psql $DATABASE_URL -c "SELECT 1"
Some commands reference modules that are not yet implemented. This is expected during the development phase. Stick to the query-db command for current functionality.
Ensure the database user has appropriate permissions:
# Grant necessary permissions
GRANT SELECT, INSERT, UPDATE ON ALL TABLES IN SCHEMA public TO your_user;

​
Contributing

The CLI is open for contributions. Priority areas:
  1. Implement creator management commands
  2. Add discovery pipeline CLI integration
  3. Build export and reporting tools
  4. Improve output formatting
  5. Add test coverage
See the main repository for contribution guidelines.

Build docs developers (and LLMs) love

Get started for freeTalk to us