PsychonautWiki CLI Tool

A command-line interface for accessing substance information from the PsychonautWiki API. This tool allows you to search for substances, view detailed information, and export data in various formats without using a web browser.

Features

• Search substances by name with fuzzy matching
• View detailed information including dosage, duration, effects, and routes of administration
• Local caching to reduce API calls and improve performance
• Multiple output formats: terminal display, JSON, and Markdown
• Export functionality to save substance information as Markdown files
• Cache management with statistics and clearing options

Installation

1. Clone this repository:

git clone <repository-url>
cd pw-cli

2. Create a virtual environment:

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install the package:

pip install -e .

Usage

Basic Commands

Search for substances

pw search <substance-name>
pw search caffeine
pw search --limit 5 stimulant

Get detailed information

pw info <substance-name>
pw info caffeine
pw info --json caffeine  # JSON output

Export to Markdown

pw export <substance-name>
pw export caffeine  # Creates Caffeine.md
pw export --output custom.md caffeine

Cache Management

View cache statistics

pw cache-stats

List cached substances

pw list

Clear cache

pw clear-cache

Configuration Options

Custom cache settings

pw --cache-dir /path/to/cache --cache-ttl 7200 info caffeine

• --cache-dir: Custom directory for cache files (default: ~/.pw-cli/cache)
• --cache-ttl: Cache time-to-live in seconds (default: 3600 = 1 hour)

Output Formats

Terminal Display

The default output shows substance information in a formatted, easy-to-read layout:

═══ Caffeine ═══

Classification:
  Chemical: Xanthines
  Psychoactive: Stimulants

Routes of Administration:
  ▸ oral
    Dosage (mg):
      Threshold: 10
      Light: 20-50
      Common: 50-150
      Strong: 150-500
      Heavy: 500
    Duration:
      Onset: 5-10 minutes
      Peak: 1-2 hours
      Total: 2-5 hours

JSON Output

Use the --json flag for structured data:

pw info --json caffeine

Markdown Export

Export substance information to Markdown files:

pw export caffeine  # Creates Caffeine.md

Data Source

This tool uses the PsychonautWiki API, which provides comprehensive information about psychoactive substances including:

• Dosage information for different routes of administration
• Duration data (onset, peak, duration, etc.)
• Effects profiles with detailed descriptions
• Tolerance and cross-tolerance information
• Chemical and pharmacological classifications

Caching

The tool implements local caching to:

• Reduce API calls and improve performance
• Allow offline access to previously queried substances
• Respect API rate limits

Cache files are stored in ~/.pw-cli/cache/ by default and expire after 1 hour.

Contributing

This tool is designed for educational and harm reduction purposes. Please use it responsibly and in accordance with local laws and regulations.

License

This project is open source. Please check the repository for license details.

Disclaimer

This tool is for educational and informational purposes only. The information provided should not be used as a substitute for professional medical advice. Always consult with healthcare professionals before making any decisions related to substance use.