Skip to content

quickstart.md

Latest commit

 

History

History
158 lines (122 loc) · 3.19 KB

quickstart.md

File metadata and controls

158 lines (122 loc) · 3.19 KB

PID Pal Quickstart

Get running in under 5 minutes. No API keys required for basic usage.

1. Install

Option A: Pre-built binary (recommended)

# Download from releases
wget https://github.com/MSNYC/pidpal/releases/latest/download/pidpal-linux-x86_64
chmod +x pidpal-linux-x86_64
sudo mv pidpal-linux-x86_64 /usr/local/bin/pidpal

2. Try Your First Command

Option A: Guided Mode (Recommended for Beginners)

Just run pidpal with no arguments to start the interactive wizard:

pidpal

On your first run, PID Pal offers a short orientation you can skip if you prefer.

You'll see a friendly menu:

==================================================
  Welcome to PID Pal!
  Your friendly process explainer
==================================================

What would you like to do?

  1. Explain a process (enter a PID)
  2. List top processes (by resource usage)
  3. Search for a process (by name)
  4. Help & Settings
  5. Exit

Enter your choice (1-5):

Try option 2 to see your top processes, then pick one to explain!

Option B: Direct Command

If you know the PID, explain it directly:

pidpal 1

Expected output:

╭─ systemd (PID 1)
│
│ System and service manager for Linux
│
│ What it does:
│   System and service manager for Linux
│   Parent relationship: Root of the process tree.
│   Executable: /sbin/init.
│   ...
│
│ Why it's running:
│   This process is part of the operating system and likely started at boot.
│
│ ✓ This is a core system process.
│
│ When to pay attention:
│   This process typically doesn't require user attention.
│
│ Resources:
│   CPU: 0.1% | Memory: 0.3% | User: root
╰─

3. Try Different Modes

Verbose mode - more technical details:

pidpal 1 --verbose

Quiet mode - just the summary:

pidpal 1 --quiet

JSON output - for scripting:

pidpal 1 --json

4. (Optional) Enable LLM Explanations

For richer, more conversational explanations, add an API key:

# Install LLM dependencies
pip install "pidpal[llm]"

# Choose one:
export ANTHROPIC_API_KEY="your-key-here"
# or
export OPENAI_API_KEY="your-key-here"

Then run pidpal normally - it will automatically use the LLM for better explanations.

Note: When an API key is present, PID Pal enables basic usage logging by default. You can disable it with:

export PIDPAL_OBSERVABILITY="off"

To explicitly disable LLM usage:

pidpal 1 --no-llm

5. Common Use Cases

List top processes (no need for external tools):

pidpal --top 10

Search for a process by name:

pidpal --filter firefox

Identify an unfamiliar process:

# Find PID with ps or pgrep
ps aux | grep -i firefox
pidpal 12345

Check what's using high CPU:

# Use PID Pal's built-in sorting
pidpal --top 10 --sort cpu

Export process info for logging:

pidpal $(pgrep nginx | head -1) --json > nginx_info.json

Next Steps