SignalPilot Installer CLI

This installer CLI is a bootstrap installer that sets up the SignalPilot-AI Jupyter extension in one command.

The CLI is NOT the product. It's a convenience installer. The SignalPilot Jupyter extension (agentic harness) is the actual product.

What You're Installing

SignalPilot is a Jupyter-native AI agentic harness that investigates data by connecting to your organizational context:

Four core capabilities:

• 🔌 Multi-Source Context — Auto-connects to db warehouse, dbt lineage, query history, Slack threads, Jira tickets, and past investigations via MCP
• 🔄 Long-Running Agent Loop — Plans, executes, iterates until task complete with analyst-in-the-loop approval (not single-shot completions)
• 🧠 Multi-Session Memory — Remembers past hypotheses, validated assumptions, known data quirks across investigations
• 📚 Skills & Rules — Custom analysis patterns (skills) + team coding standards (rules) + business logic

Security: Zero data retention • Read-only access • Local-first execution • SOC 2 in progress

Quick Install

Prerequisites: macOS, Linux, or Windows (WSL) • Internet connection

Don't have uv? Install it first (takes 10 seconds):

curl -LsSf https://astral.sh/uv/install.sh | sh

Install SignalPilot:

uvx signalpilot

What happens:

• Creates ~/SignalPilotHome workspace with starter notebooks
• Installs isolated Python 3.12 + Jupyter Lab + SignalPilot extension
• Installs data packages (pandas, numpy, matplotlib, seaborn, plotly)
• Optimizes Jupyter cache for fast startup
• Launches Jupyter Lab at http://localhost:8888

Time: ~2 minutes

Why uv?

• 10-100x faster than pip/conda for package installation
• SignalPilot runs on it — native integration with kernel
• Modern Python package management with better dependency resolution

Check Version

uvx signalpilot version

Shows the installed CLI version with the SignalPilot logo.

Launch Jupyter Lab Anytime

Once installed, start Jupyter Lab with:

uvx signalpilot lab

What this does:

• Opens Jupyter Lab in your current directory
• Uses home environment from ~/SignalPilotHome/.venv
• SignalPilot extension pre-loaded
• Opens browser at http://localhost:8888

⚠️ Smart Detection: If a local .venv with jupyter is detected in your current directory, you'll see a red warning. Use --project flag to use it instead.

Keeping SignalPilot Updated

SignalPilot automatically checks for updates when you launch Jupyter Lab. When an update is available, you'll see a notification:

For minor updates:

╭─────────────── 📦 SignalPilot Update ───────────────╮
│ Update Available: 0.11.8 (installed: 0.11.7)        │
│ Run 'sp upgrade' to update                          │
╰──────────────────────────────────────────────────────╯

For major updates:

╭─────────────── 📦 SignalPilot Update ───────────────╮
│ Important Update: 0.12.0 (installed: 0.11.7)        │
│ This is a MAJOR update                              │
╰──────────────────────────────────────────────────────╯
Upgrade now? [y/n] (n):

Manual Upgrade

Upgrade both the CLI and library anytime:

uvx signalpilot upgrade

Upgrade your project's local environment:

cd /path/to/project
uvx signalpilot upgrade --project

How Upgrade Works

The upgrade command is context-aware:

Context	CLI Upgrade	Library Upgrade
uvx users	Clears uvx cache (no permanent install)	uv pip install --upgrade
Tool users (uv tool install)	uv tool install --force + clears cache	uv pip install --upgrade

Why? uvx users prefer ephemeral execution without permanent installations. The CLI detects this by checking if ~/.local/bin/signalpilot exists.

Cache invalidation: uvx --refresh is unreliable (known uv issue), so we use uv cache clean signalpilot which reliably clears the uvx cache. Next uvx signalpilot run fetches the fresh version.

Note: Update checks happen in the background and never slow down Jupyter startup. You can disable them in ~/SignalPilotHome/.signalpilot/config.toml if desired.

📖 Full upgrade guide: docs/UPGRADE-USER-GUIDE.md

What Gets Installed

Python Packages:

• signalpilot-ai — AI agent integration (the actual product)
• jupyterlab — Modern Jupyter interface
• pandas, numpy — Data manipulation
• matplotlib, seaborn, plotly — Visualization
• python-dotenv, tomli — Configuration utilities

Directory Structure:

~/SignalPilotHome/
├── user-skills/       # Custom analysis patterns
├── user-rules/        # Team coding standards
├── team-workspace/    # Shared notebooks (git-tracked)
├── pyproject.toml     # Python project config
├── start-here.ipynb   # Quick start guide
└── .venv/             # Python environment

Working in Different Modes

SignalPilot offers three ways to launch Jupyter Lab:

Default Mode (Current Folder + Home Environment)

cd ~/projects/my-analysis
uvx signalpilot lab

What this does:

• Opens Jupyter Lab in your current directory
• Uses home environment from ~/SignalPilotHome/.venv
• Perfect for quick exploration without setting up new environment

⚠️ Warning: If you have a local .venv with jupyter, you'll see a red warning prompting you to use --project flag.

Project Mode (Current Folder + Local Environment)

cd ~/projects/custom-analytics
uvx signalpilot lab --project

What this does:

• Opens Jupyter Lab in your current directory
• Uses local .venv in that directory (fails if missing)
• Great for project-specific work with custom dependencies

Requirements:

• A .venv must exist in current directory
• Must have jupyterlab and signalpilot-ai installed

Create project environment:

mkdir ~/projects/custom-analytics && cd ~/projects/custom-analytics
uv venv --seed --python 3.12
source .venv/bin/activate
uv pip install jupyterlab signalpilot-ai pandas numpy matplotlib plotly
uvx signalpilot lab --project

Home Mode (SignalPilotHome Workspace + Home Environment)

uvx signalpilot lab --home
# Or use the shortcut:
uvx signalpilot home

What this does:

• Opens Jupyter Lab in ~/SignalPilotHome directory
• Uses home environment from ~/SignalPilotHome/.venv
• Default workspace with all your skills, rules, and team notebooks

Pass Jupyter Lab Arguments

You can pass any Jupyter Lab flags after the command:

# Custom port
uvx signalpilot lab --port=8889

# Disable browser auto-open
uvx signalpilot lab --no-browser

# Combine with mode flags
uvx signalpilot lab --project --port=8889
uvx signalpilot home --no-browser

# Bind to all interfaces (remote access)
uvx signalpilot lab --ip=0.0.0.0 --port=9999

All standard jupyter lab arguments work.

Alternative Installation Methods

Option 1: Run with uvx (Recommended)

uvx signalpilot

No permanent installation needed. Perfect for most users. Always gets the latest version.

Option 2: Install with uv tool

uv tool install signalpilot
sp init

Installs sp command globally. Use sp lab, sp home to launch later.

Note: Global installations don't auto-update. Reinstall periodically:

uv tool install --force signalpilot

Option 3: Install with pip

pip install signalpilot
sp init

Works but slower than uv (10-100x). May have dependency conflicts.

Requirements

• Python 3.10 or higher
• uv package manager (recommended)

Links

• Homepage
• Full Documentation
• Installation Guide
• 5-Minute Quickstart
• GitHub

License

MIT License - See LICENSE file for details