Skip to main content

​
Overview

The tinbox doctor command runs comprehensive diagnostic checks to verify your Tinbox installation and configuration. It checks system dependencies, Python packages, API keys, and local model support.

​
Basic Usage

tinbox doctor

tinbox doctor

​
Options

​
--json
boolean
default:"false"
Output the diagnostic report as JSON instead of formatted tables.Default: falseUse case: Useful for automation, CI/CD pipelines, or programmatic parsing of the diagnostic results.

​
What It Checks

The doctor command runs diagnostic checks across multiple categories:

​
System Tools

​
poppler
system-tool
Required for: PDF processing and translationCheck: Verifies that poppler utilities (specifically pdftoppm) are installed and accessibleInstallation:
  • macOS: brew install poppler
  • Ubuntu/Debian: sudo apt-get install poppler-utils
  • Windows: Download from poppler for Windows

​
Python Packages

​
pdf2image
python-package
Required for: PDF to image conversionInstallation: pip install pdf2image
​
python-docx
python-package
Required for: DOCX file supportInstallation: pip install python-docx
​
pillow
python-package
Required for: Image processingInstallation: pip install pillow

​
API Keys (Cloud Models)

​
OPENAI_API_KEY
environment-variable
Required for: OpenAI models (openai:gpt-4o, etc.)Setup: Set environment variable with your OpenAI API key
export OPENAI_API_KEY="sk-..."
​
ANTHROPIC_API_KEY
environment-variable
Required for: Anthropic Claude models (anthropic:claude-3-sonnet, etc.)Setup: Set environment variable with your Anthropic API key
export ANTHROPIC_API_KEY="sk-ant-..."
​
GOOGLE_API_KEY
environment-variable
Required for: Google Gemini models (google:gemini-1.5-pro, etc.)Setup: Set environment variable with your Google API key
export GOOGLE_API_KEY="..."

​
Local Model Support

​
ollama
local-service
Required for: Local model inference (ollama:mistral-small, etc.)Check: Verifies that Ollama is installed and runningInstallation:
  • Visit ollama.ai for installation instructions
  • Start Ollama service: ollama serve

​
Output Format

​
Human-Readable Format (Default)

The default output displays diagnostic results in categorized tables: 
Tinbox Diagnostic Report

┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┓
┃ System Tools       ┃          ┃                       ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━┩
│ Check              │ Status   │ Details               │
├────────────────────┼──────────┼───────────────────────┤
│ poppler            │ OK       │ Found at /usr/bin/... │
└────────────────────┴──────────┴───────────────────────┘

┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Python Packages    ┃          ┃                       ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━┩
│ Check              │ Status   │ Details               │
├────────────────────┼──────────┼───────────────────────┤
│ pdf2image          │ OK       │ Version: 1.16.3       │
│ python-docx        │ OK       │ Version: 1.1.0        │
│ pillow             │ OK       │ Version: 10.2.0       │
└────────────────────┴──────────┴───────────────────────┘

┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┓
┃ API Keys           ┃          ┃                       ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━┩
│ Check              │ Status   │ Details               │
├────────────────────┼──────────┼───────────────────────┤
│ OPENAI_API_KEY     │ OK       │ Set                   │
│ ANTHROPIC_API_KEY  │ MISSING  │ Install: export ...   │
│ GOOGLE_API_KEY     │ MISSING  │ Install: export ...   │
└────────────────────┴──────────┴───────────────────────┘

Core checks passed. Some optional features may be unavailable.
Set API keys for cloud models or install Ollama for local models.

​
JSON Format

The --json flag outputs a machine-readable JSON report: 
{
  "all_ok": false,
  "required_ok": true,
  "checks": [
    {
      "name": "poppler",
      "category": "System Tools",
      "ok": true,
      "required": true,
      "details": "Found at /usr/bin/pdftoppm",
      "hint": null
    },
    {
      "name": "OPENAI_API_KEY",
      "category": "API Keys",
      "ok": true,
      "required": false,
      "details": "Set",
      "hint": null
    },
    {
      "name": "ANTHROPIC_API_KEY",
      "category": "API Keys",
      "ok": false,
      "required": false,
      "details": "Not set",
      "hint": "Set environment variable: export ANTHROPIC_API_KEY=your-key"
    }
  ]
}

​
Exit Codes

​
0
exit-code
Success: All required checks passed. Tinbox is ready to use.
​
0 (with warnings)
exit-code
Partial Success: Core checks passed, but some optional features are unavailable (e.g., missing API keys).
​
1
exit-code
Failure: One or more required checks failed. System dependencies or Python packages are missing.

​
Status Messages

​
All Checks Passed

All checks passed! Tinbox is ready to use.
All required and optional checks succeeded. You can use all Tinbox features.

​
Core Checks Passed

Core checks passed. Some optional features may be unavailable.
Set API keys for cloud models or install Ollama for local models.
Required system dependencies are installed, but some cloud model providers or local model support is unavailable.

​
Required Checks Failed

Some required checks failed. Please fix the issues above.
Critical dependencies are missing. Install required system tools or Python packages before using Tinbox.

​
Examples

​
Run Basic Diagnostics

tinbox doctor

​
Get JSON Output for CI/CD

tinbox doctor --json > doctor-report.json

​
Check Before Translation

# Verify setup before running expensive translation
tinbox doctor && tinbox translate document.pdf --model openai:gpt-4o --to es

​
Parse JSON Output with jq

# Check if all required dependencies are available
tinbox doctor --json | jq '.required_ok'

# List all failed checks
tinbox doctor --json | jq '.checks[] | select(.ok == false) | .name'

# Get installation hints for missing items
tinbox doctor --json | jq '.checks[] | select(.ok == false) | .hint'

​
Troubleshooting Common Issues

​
Missing Poppler

Error: poppler check fails Solution: 
# macOS
brew install poppler

# Ubuntu/Debian
sudo apt-get install poppler-utils

# Verify installation
which pdftoppm

​
Missing Python Packages

Error: pdf2image, python-docx, or pillow checks fail Solution: 
# Install all extras at once
pip install tinbox[all]

# Or install individually
pip install pdf2image python-docx pillow

​
Missing API Keys

Error: OPENAI_API_KEY, ANTHROPIC_API_KEY, or GOOGLE_API_KEY checks fail Solution: 
# Set environment variables (add to ~/.bashrc or ~/.zshrc for persistence)
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GOOGLE_API_KEY="..."

# Verify
tinbox doctor

​
Ollama Not Running

Error: ollama check fails Solution: 
# Install Ollama (visit ollama.ai for platform-specific instructions)

# Start Ollama service
ollama serve

# Verify in another terminal
tinbox doctor

​
Use in CI/CD Pipelines

The tinbox doctor command is useful for validating environments in automated workflows: 
# GitHub Actions example
- name: Check Tinbox setup
  run: |
    tinbox doctor --json > doctor-report.json
    cat doctor-report.json
    
- name: Verify required checks
  run: |
    if ! tinbox doctor --json | jq -e '.required_ok'; then
      echo "Required Tinbox dependencies are missing"
      exit 1
    fi

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us