CLI Guide

Complete reference for the Perpendicularity command-line interface.

📖 Overview

The perpendicularity CLI provides three main interfaces:

ask - Single question/answer
interactive - Conversational mode
api - Start web server

Plus utility commands for listing models and prompts.

🎯 Quick Reference

# Single query
perpendicularity ask "Which of the following drugs is preferred for further development? 1. CC(=O)OC1=CC=CC=C1C(=O)O (Aspirin) or 2. O=C(CCCCCCC(=O)Nc1ccccc1)NO"

# Interactive mode
perpendicularity interactive

# Start API server
perpendicularity api

# List available models
perpendicularity list-models

# List available prompts
perpendicularity list-prompts

# Show help
perpendicularity --help
perpendicularity ask --help

📝 Commands

`ask` - Single Question

Ask a single question and get an answer.

Usage:

perpendicularity ask QUESTION [OPTIONS]

Options:

-c, --config PATH - Config file path (default: config/agent_config.yaml)
-m, --model NAME - Model to use (default: from config)
--agent-type TYPE - Agent type: langgraph or react (default: langgraph)
--max-steps INT - Maximum reasoning steps (default: 5)
--prompt NAME - System prompt to use (default: default)
--plain - Force plain text output (no rich formatting)
--debug - Enable debug logging
--dry-run - Show configuration without executing

Examples:

# Basic query
perpendicularity ask "What is aspirin?"

# With specific model
perpendicularity ask "What is aspirin?" --model claude

# With custom prompt
perpendicularity ask "Evaluate the toxicity of O=C(Oc1ccccc1C(=O)O)O" --prompt conservative

# Complex query with all options
perpendicularity ask "Which of the following drugs is preferred for further development? 1. CC(=O)OC1=CC=CC=C1C(=O)O (Aspirin) or 2. O=C(CCCCCCC(=O)Nc1ccccc1)NO" \
  --model gemini \
  --agent-type langgraph \
  --max-steps 10 \
  --prompt genomics \
  --config my_config.yaml

# Plain text output (for scripts)
perpendicularity ask "What is aspirin?" --plain > output.txt

# Debug mode
perpendicularity ask "What is aspirin?" --debug

# Dry run (validate config)
perpendicularity ask "Answer this test question" --dry-run

`interactive` - Conversational Mode

Enter an interactive chat session with the agent.

Usage:

perpendicularity interactive [OPTIONS]

Options:

-c, --config PATH - Config file path
-m, --model NAME - Model to use
--agent-type TYPE - Agent type
--max-steps INT - Maximum reasoning steps
--prompt NAME - System prompt
--plain - Force plain text output

Features:

Multi-turn conversations
Context retention (with LangGraph agent)
Rich terminal formatting (automatic)
Command history (↑ ↓ arrows)

Special Commands:

exit or quit - Exit interactive mode
Ctrl+C - Exit
Ctrl+D - Exit

Example Session:

$ perpendicularity interactive --model ollama_qwen14b

Initializing Perpendicularity...

Agent ready!
Type:  langgraph
Model: ollama_qwen32b
Tools: 65

Type 'exit' or 'quit' to end.

You → hat is the SMILES for aspirin?
Thinking...
The SMILES (Simplified Molecular Input Line Entry System) notation for aspirin is `O=C(Oc1ccccc1C(=O)O)O`. This string represents the molecular structure of aspirin, which consists of a benzene ring with a carboxylic acid group and an acetyl group attached.
You → Evaluate lipophilicity of O=C(Oc1ccccc1C(=O)O)O
Thinking...
Aspirin shows moderate hepatotoxicity (score: 0.45).
You → exit

👋 Goodbye!

`api` - Start Web Server

Start the FastAPI web server with React frontend.

Usage:

perpendicularity api [OPTIONS]

Options:

-c, --config PATH - Config file path
--host TEXT - Host to bind to (default: 0.0.0.0)
-p, --port INT - Port to bind to (default: 8000)
--reload - Enable auto-reload (development)
--workers INT - Number of worker processes (default: 1)
--log-level LEVEL - Log level: debug, info, warning, error (default: info)

Examples:

# Start server (default settings)
perpendicularity api
# Access at http://localhost:8000

# Development mode with auto-reload
perpendicularity api --reload --log-level debug

# Production with multiple workers
perpendicularity api --workers 4 --log-level warning

# Custom port
perpendicularity api --port 3000

# Custom config
perpendicularity api --config production_config.yaml --workers 4

Server Info:

Frontend: http://localhost:8000
API Docs: http://localhost:8000/docs
Health Check: http://localhost:8000/api/health

See API Guide for API endpoints and Frontend Guide for UI details.

`list-models` - Show Available Models

List all models configured in your agent_config.yaml.

Usage:

perpendicularity list-models [OPTIONS]

Options:

-c, --config PATH - Config file path

Example:

$ perpendicularity list-models

 Configured Models
┏━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ Model Name               ┃ Type         ┃ Name                     ┃ Max Tokens ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ gemini                   │ gemini       │ gemini-2.5-flash         │ 8192       │
│ gemini_pro               │ gemini       │ gemini-2.0-pro           │ 8192       │
│ claude                   │ anthropic    │ claude-sonnet-4-20250514 │ 8192       │
│ claude_opus              │ anthropic    │ claude-opus-4-20250514   │ 8192       │
│ ollama_qwen14b (default) │ openai       │ qwen2.5:14b-instruct     │ 4096       │
│ ollama_deepseek          │ openai       │ deepseek-r1:8b           │ 4096       │
│ ollama_qwen7b            │ openai       │ qwen2.5:7b-instruct      │ 4096       │
│ ollama_mistral           │ openai       │ mistral:7b-instruct      │ 4096       │
│ ollama_qwen32b           │ openai       │ qwen2.5:32b-instruct     │ 4096       │
│ ollama_command_r         │ openai       │ command-r:35b            │ 4096       │
│ ollama_llama             │ openai       │ llama3.1:8b              │ 4096       │
│ hf_qwen14b               │ transformers │ hf_qwen14b               │ 4096       │
│ hf_deepseek              │ transformers │ hf_deepseek              │ 4096       │
│ hf_qwen32b               │ transformers │ hf_qwen32b               │ 4096       │
│ hf_mistral               │ transformers │ hf_mistral               │ 4096       │
│ hf_txgemmachat           │ transformers │ hf_txgemmachat           │ 4096       │
│ hf_command_r             │ transformers │ hf_command_r             │ 4096       │
└──────────────────────────┴──────────────┴──────────────────────────┴────────────┘

`list-tools` - Show Available Prompts

List all tools loaded from MCP servers.

Usage:

perpendicularity list-tools [OPTIONS]

Options:

-c, --config PATH - Config file path

Example:

$ perpendicularity list-tools

                                                    Available MCP Tools
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Tool Name                                     ┃ Server      ┃ Description                                                     ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ get_overlapping_features                      │ genomic_ops │                                                                 │
│ list_species                                  │ genomic_ops │ List all available species from UCSC.                           │
│ list_assemblies                               │ genomic_ops │ Get assemblies for a given species (exact or fuzzy match)       │
│ list_ucsc_tracks                              │ genomic_ops │ List all UCSC genome browser tracks for a given assembly/gen... │
│ lift_over_coordinates                         │ genomic_ops │ Convert genomic coordinates between assemblies using UCSC li... │
│ txgemma_chat                                  │ txgemma     │ Ask TxGemma Chat model a question about drug discovery, mole... │
│ PAMPA_NCATS                                   │ txgemma     │ **PAMPA NCATS**                                                 │
│                                               │             │                                                                 │
│                                               │             │ Instructions: Answer the following question...                  │
│ ClinTox                                       │ txgemma     │ **ClinTox**                                                     │
│                                               │             │                                                                 │
│                                               │             │ Instructions: Answer the following question abo...              │
│ DAVIS                                         │ txgemma     │ **DAVIS**                                                       │
│                                               │             │                                                                 │
└───────────────────────────────────────────────┴─────────────┴─────────────────────────────────────────────────────────────────┘

🎨 Output Modes

Rich Mode (Automatic)

When running in a terminal (TTY), Perpendicularity automatically uses rich formatting:

Features:

✅ Colored output
✅ Formatted tables
✅ Syntax highlighting
✅ Progress spinners
✅ Step-by-step reasoning display
✅ Markdown rendering

Example:

perpendicularity ask "What is aspirin?"
# Automatically detects TTY and uses rich formatting

Plain Mode (Automatic)

When output is piped or redirected, automatically switches to plain text:

Features:

✅ No ANSI color codes
✅ Simple text format
✅ Parseable output
✅ Script-friendly

Example:

perpendicularity ask "What is aspirin?" > output.txt
# Automatically uses plain text

perpendicularity ask "What is aspirin?" | grep "acid"
# Automatically uses plain text

Force Plain Mode

Override automatic detection:

perpendicularity ask "What is aspirin?" --plain
# Always uses plain text, even in terminal

🔧 Global Options

Available on all commands:

--version              # Show version
--help                # Show help message
-c, --config PATH     # Specify config file
--debug               # Enable debug logging

Examples:

# Show version
perpendicularity --version
# Output: 0.1.0

# Show help
perpendicularity --help
perpendicularity ask --help
perpendicularity api --help

# Use custom config
perpendicularity ask "question" --config /path/to/config.yaml

# Debug mode
perpendicularity ask "question" --debug

📚 Common Workflows

Development Workflow

# 1. Test config is valid
perpendicularity ask "This is a test question" --dry-run

# 2. List available models
perpendicularity list-models

# 3. Quick test with local model
perpendicularity ask "What is aspirin?" --model ollama_qwen14b

# 4. Interactive exploration
perpendicularity interactive --model ollama_qwen14b

Research Workflow

# 1. Exploratory query
perpendicularity ask "Which of the following drugs is preferred for further development? 1. CC(=O)OC1=CC=CC=C1C(=O)O (Aspirin) or 2. O=C(CCCCCCC(=O)Nc1ccccc1)NO" --prompt exploratory

# 2. Detailed genomic analysis
perpendicularity ask "For genomic locus chr15:61857240-61862199, get gene annotations in humans, evaluate therapeutic relevance, and suggest any drugs that may act on these genes." \
  --prompt genomics \
  --max-steps 10

# 3. Safety evaluation
perpendicularity ask "Evaluate safety of O=C(CCCCCCC(=O)Nc1ccccc1)NO" --prompt conservative

# 4. Save results
perpendicularity ask "Evaluate alternative modes of action for O=C(CCCCCCC(=O)Nc1ccccc1)NO" --plain > results.txt

Batch Processing

# Process multiple queries from file
cat queries.txt | while read query; do
  perpendicularity ask "$query" --plain >> results.txt
done

# Parallel processing
cat queries.txt | parallel perpendicularity ask {} --plain

# With specific model for all
cat queries.txt | xargs -I {} perpendicularity ask "{}" \
  --model gemini \
  --plain \
  >> results.txt

🎓 Advanced Usage

Environment Variables

Override config with environment variables:

# Set API keys
export GOOGLE_API_KEY="your-key"
export ANTHROPIC_API_KEY="your-key"

# Set config path
export PERPENDICULARITY_CONFIG="/path/to/config.yaml"
perpendicularity api  # Uses config from env var

🔍 Troubleshooting

Config File Errors

# Validate config
perpendicularity ask "Which of the following drugs is preferred for further development? 1. CC(=O)OC1=CC=CC=C1C(=O)O (Aspirin) or 2. O=C(CCCCCCC(=O)Nc1ccccc1)NO" --dry-run

# Use different config
perpendicularity ask "Which of the following drugs is preferred for further development? 1. CC(=O)OC1=CC=CC=C1C(=O)O (Aspirin) or 2. O=C(CCCCCCC(=O)Nc1ccccc1)NO" --config /path/to/config.yaml

# Check config syntax
python -c "import yaml; yaml.safe_load(open('config/agent_config.yaml'))"

Model Not Found

# List available models
perpendicularity list-models

# Check spelling (case-sensitive!)
perpendicularity ask "Which of the following drugs is preferred for further development? 1. CC(=O)OC1=CC=CC=C1C(=O)O (Aspirin) or 2. O=C(CCCCCCC(=O)Nc1ccccc1)NO" --model gemini     # ✅
perpendicularity ask "Which of the following drugs is preferred for further development? 1. CC(=O)OC1=CC=CC=C1C(=O)O (Aspirin) or 2. O=C(CCCCCCC(=O)Nc1ccccc1)NO" --model Gemini     # ❌

# For Ollama models, ensure pulled
ollama list
ollama pull qwen2.5:14b-instruct

API Server Won't Start

# Check port availability
lsof -i :8000

# Use different port
perpendicularity api --port 3000

# Check logs
perpendicularity api --log-level debug

📊 Exit Codes

Code	Meaning
0	Success
1	General error
2	Configuration error
130	Interrupted (Ctrl+C)

Example:

perpendicularity ask "Which of the following drugs is preferred for further development? 1. CC(=O)OC1=CC=CC=C1C(=O)O (Aspirin) or 2. O=C(CCCCCCC(=O)Nc1ccccc1)NO"
echo $?  # Check exit code

💡 Tips & Best Practices

1. Use Appropriate Output Mode

# Interactive work - let rich mode shine
perpendicularity ask "Which of the following drugs is preferred for further development? 1. CC(=O)OC1=CC=CC=C1C(=O)O (Aspirin) or 2. O=C(CCCCCCC(=O)Nc1ccccc1)NO"

# Scripts - force plain mode
perpendicularity ask "Which of the following drugs is preferred for further development? 1. CC(=O)OC1=CC=CC=C1C(=O)O (Aspirin) or 2. O=C(CCCCCCC(=O)Nc1ccccc1)NO" --plain > output.txt

2. Start with Dry Run

# Validate before running
perpendicularity ask "Which of the following drugs is preferred for further development? 1. CC(=O)OC1=CC=CC=C1C(=O)O (Aspirin) or 2. O=C(CCCCCCC(=O)Nc1ccccc1)NO" --dry-run --model claude

3. Use Short Model Names

# Configured in agent_config.yaml as shortcuts
perpendicularity ask "Which of the following drugs is preferred for further development? 1. CC(=O)OC1=CC=CC=C1C(=O)O (Aspirin) or 2. O=C(CCCCCCC(=O)Nc1ccccc1)NO" --model qwen  # Instead of qwen2.5:14b-instruct

4. Leverage Prompts

# Different prompts for different tasks
perpendicularity ask "Which of the following drugs is preferred for further development? 1. CC(=O)OC1=CC=CC=C1C(=O)O (Aspirin) or 2. O=C(CCCCCCC(=O)Nc1ccccc1)NO" --prompt conservative
perpendicularity ask "Evaluate alternative modes of action for O=C(CCCCCCC(=O)Nc1ccccc1)N" --prompt exploratory
perpendicularity ask "For genomic locus chr15:61857240-61862199, get gene annotations in humans, evaluate therapeutic relevance, and suggest any drugs that may act on these genes." --prompt genomics

5. Save Complex Commands

# Create aliases in ~/.bashrc
alias pask='perpendicularity ask --model ollama_qwen14b --plain'
alias pint='perpendicularity interactive --model ollama_qwen14b'

# Use them
pask "Which of the following drugs is preferred for further development? 1. CC(=O)OC1=CC=CC=C1C(=O)O (Aspirin) or 2. O=C(CCCCCCC(=O)Nc1ccccc1)NO"
pint

📚 See Also

Getting Started - Installation and first steps
Models Guide - Model selection
Agents Guide - LangGraph vs ReAct
Configuration Reference - All config options
API Guide - Web API reference

Master the CLI for maximum productivity! 🚀

For questions, see Troubleshooting or open an issue.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CLI Guide

📖 Overview

🎯 Quick Reference

📝 Commands

`ask` - Single Question

`interactive` - Conversational Mode

`api` - Start Web Server

`list-models` - Show Available Models

`list-tools` - Show Available Prompts

🎨 Output Modes

Rich Mode (Automatic)

Plain Mode (Automatic)

Force Plain Mode

🔧 Global Options

📚 Common Workflows

Development Workflow

Research Workflow

Batch Processing

🎓 Advanced Usage

Environment Variables

🔍 Troubleshooting

Config File Errors

Model Not Found

API Server Won't Start

📊 Exit Codes

💡 Tips & Best Practices

1. Use Appropriate Output Mode

2. Start with Dry Run

3. Use Short Model Names

4. Leverage Prompts

5. Save Complex Commands

📚 See Also

FilesExpand file tree

CLI_GUIDE.md

Latest commit

History

CLI_GUIDE.md

File metadata and controls

CLI Guide

📖 Overview

🎯 Quick Reference

📝 Commands

ask - Single Question

interactive - Conversational Mode

api - Start Web Server

list-models - Show Available Models

list-tools - Show Available Prompts

🎨 Output Modes

Rich Mode (Automatic)

Plain Mode (Automatic)

Force Plain Mode

🔧 Global Options

📚 Common Workflows

Development Workflow

Research Workflow

Batch Processing

🎓 Advanced Usage

Environment Variables

🔍 Troubleshooting

Config File Errors

Model Not Found

API Server Won't Start

📊 Exit Codes

💡 Tips & Best Practices

1. Use Appropriate Output Mode

2. Start with Dry Run

3. Use Short Model Names

4. Leverage Prompts

5. Save Complex Commands

📚 See Also

`ask` - Single Question

`interactive` - Conversational Mode

`api` - Start Web Server

`list-models` - Show Available Models

`list-tools` - Show Available Prompts