CLI Commands

Complete reference for the SignalPilot command-line interface.

The CLI is a bootstrap installer that sets up the SignalPilot-AI Jupyter extension. The extension itself (not the CLI) is the actual product.

Command Syntax

Using uvx signalpilot (recommended)

Run SignalPilot without installation using uvx:

# Initialize workspace (first-time setup)
uvx signalpilot

# Check version
uvx signalpilot version

# Launch Jupyter Lab
uvx signalpilot lab              # Current directory + home environment
uvx signalpilot lab --home       # Home directory + home environment
uvx signalpilot lab --project    # Current directory + local .venv

# Shortcuts
uvx signalpilot home             # Same as: lab --home

# Upgrade
uvx signalpilot upgrade          # Upgrade home environment + CLI
uvx signalpilot upgrade --project # Upgrade local .venv

# Jupyter Lab arguments also work
uvx signalpilot lab --port=8889  # Example: custom port

Using sp (after global install)

Install globally with uv tool install signalpilot to use the shorter sp command:

sp init           # Same as: uvx signalpilot
sp version        # Same as: uvx signalpilot version
sp lab            # Same as: uvx signalpilot lab
sp lab --home     # Same as: uvx signalpilot lab --home
sp home           # Same as: uvx signalpilot home
sp upgrade        # Same as: uvx signalpilot upgrade

All uvx signalpilot commands and arguments work identically with sp. See Alternative Installation Methods for global installation.

Core Commands

`uvx signalpilot` (or `sp init`)

Initialize SignalPilot workspace and launch Jupyter Lab.

uvx signalpilot

What it does:

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

First-time setup only. After installation, use uvx signalpilot lab to launch.

`uvx signalpilot version`

Check the installed CLI version.

uvx signalpilot version

Shows the installed CLI version with the SignalPilot logo.

`uvx signalpilot lab`

Launch Jupyter Lab with SignalPilot.

uvx signalpilot lab [OPTIONS]

Default behavior:

Opens Jupyter Lab in your current directory
Uses home environment from ~/SignalPilotHome/.venv
Opens browser at http://localhost:8888

Smart Detection: If a local .venv with jupyter is detected, you’ll see a red warning prompting you to use --project flag.

SignalPilot Options

--home

flag

Launch in ~/SignalPilotHome directory with home environment.

uvx signalpilot lab --home

--project

flag

Use local .venv in current directory. Requires .venv with jupyterlab and signalpilot-ai installed.

cd ~/projects/my-project
uvx signalpilot lab --project

Jupyter Lab Arguments

SignalPilot passes through standard Jupyter Lab arguments:

uvx signalpilot lab --port=8889        # Custom port (default: 8888)
uvx signalpilot lab --no-browser       # Don't open browser automatically
uvx signalpilot lab --ip=0.0.0.0       # Allow remote access (default: localhost)

Advanced Jupyter Lab configuration

Server configuration:

# Disable authentication
uvx signalpilot lab --ServerApp.token='' --ServerApp.password=''

# Allow CORS from any origin
uvx signalpilot lab --ServerApp.allow_origin='*'

# Set custom root directory
uvx signalpilot lab --ServerApp.root_dir=/path/to/notebooks

# Enable debug mode
uvx signalpilot lab --debug

See Jupyter Lab documentation for all available server configuration options.

`uvx signalpilot home`

Shortcut for uvx signalpilot lab --home.

uvx signalpilot home [OPTIONS]

Opens Jupyter Lab in ~/SignalPilotHome directory with home environment. Example:

# Open home workspace without browser
uvx signalpilot home --no-browser

`uvx signalpilot upgrade`

Upgrade SignalPilot CLI and Jupyter extension.

uvx signalpilot upgrade [--project]

Default (home environment):

uvx signalpilot upgrade

Project environment:

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

Upgrades the local .venv in the current directory instead of home environment.

How Upgrade Works

The upgrade command updates two components:

CLI tool (signalpilot) — The installer/launcher you run from terminal
Jupyter extension (signalpilot-ai) — The actual product inside your .venv

What happens when you run uvx signalpilot upgrade:

Detect installation type

Checks if ~/.local/bin/signalpilot exists to determine if you installed globally with uv tool install or run ephemerally with uvx.

Upgrade CLI

uvx users: Clears uvx cache with uv cache clean signalpilot. Next uvx signalpilot fetches fresh version.
Tool users: Runs uv tool install --force signalpilot + clears cache.

Upgrade Jupyter extension

Runs uv pip install --upgrade signalpilot-ai in your target environment (~/SignalPilotHome/.venv or project .venv).

Summary table:

Installation Type	CLI Upgrade	Library Upgrade
uvx (ephemeral)	`uv cache clean signalpilot`	`uv pip install --upgrade signalpilot-ai`
uv tool (global)	`uv tool install --force` + cache clean	`uv pip install --upgrade signalpilot-ai`

Why this approach?

Why context-aware? uvx users prefer ephemeral execution without permanent installations. The CLI respects this by only clearing cache rather than installing globally.Why not uvx --refresh? The --refresh flag is unreliable (known uv issue). uv cache clean signalpilot reliably ensures the next uvx signalpilot run fetches the latest version from PyPI.What’s preserved? Your workspace, notebooks, skills, rules, and configuration remain untouched. Only the CLI and extension binaries are updated.

Auto-Update System

SignalPilot automatically checks for updates when you launch Jupyter Lab.

Minor Updates

Non-breaking updates show a notification:

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

Major Updates

Breaking changes prompt for immediate upgrade:

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

Disable Auto-Check

Edit ~/SignalPilotHome/.signalpilot/config.toml:

[updates]
check_for_updates = false

Update checks run in the background and never slow down Jupyter startup.

Working Modes

SignalPilot offers three launch modes:

Default Mode
Home Mode
Project Mode

Current directory + Home environment

cd ~/projects/analysis
uvx signalpilot lab

Use when:

Quick exploration in any folder
Don’t need custom dependencies
Want to use stable home environment

Shows warning if local .venv with jupyter detected.

SignalPilotHome + Home environment

uvx signalpilot lab --home
# Or:
uvx signalpilot home

Use when:

Working in your main SignalPilot workspace
Accessing skills, rules, team notebooks
Need all your configured tools

Current directory + Local environment

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

Use when:

Project has custom dependencies
Need isolated Python packages
Different Python version than home (3.10+)

Setup:

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

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/
├── data/              # Put local files here for @mentions
├── user-skills/       # Custom analysis patterns
├── user-rules/        # Team coding standards
├── team-workspace/    # Shared notebooks (git-tracked)
├── demo-project/      # Example notebooks
├── start-here.ipynb   # Quick start guide
├── pyproject.toml     # Python project config
└── .venv/             # Python environment

Alternative Installation Methods

Option 1: Run with uvx (Recommended)

uvx signalpilot

No permanent installation needed. Perfect for most users.

Option 2: Install with uv tool

uv tool install signalpilot
sp init

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

Global installations don’t auto-update. Reinstall periodically:

uv tool install --force signalpilot

Option 3: Install with pip

pip install signalpilot
sp init

pip is 10-100x slower than uv and may have dependency conflicts. We recommend uv for best experience.

Troubleshooting Commands

Check Installation

# Verify uv is installed
uv --version

# Go to Home + Turn on venv
cd ~/SignalPilotHome && source .venv/bin/activate

# Check Python version
python --version

# List Jupyter extensions
jupyter labextension list | grep signalpilot

Expected output:

signalpilot-ai v1.0.0 enabled OK

Debug Jupyter Startup

# Check if port is in use
lsof -i :8888  # macOS/Linux
netstat -ano | findstr :8888  # Windows

# Start with verbose logging
uvx signalpilot lab --debug

Requirements

Python 3.10 or higher
uv package manager (recommended)

Next Steps

Installation Guide

Complete setup walkthrough

Quickstart Tutorial

First analysis in 5 minutes

Troubleshooting

Common issues and solutions

Configuration

Customize SignalPilot behavior

Introduction

Getting Started

Integrations

Core Concepts

Installer CLI Commands

CLI Commands

Command Syntax

Using uvx signalpilot (recommended)

Using sp (after global install)

Core Commands

`uvx signalpilot` (or `sp init`)

`uvx signalpilot version`

`uvx signalpilot lab`

SignalPilot Options

Jupyter Lab Arguments

`uvx signalpilot home`

`uvx signalpilot upgrade`

How Upgrade Works

Auto-Update System

Minor Updates

Major Updates

Disable Auto-Check

Working Modes

What Gets Installed

Python Packages

Directory Structure

Alternative Installation Methods

Option 1: Run with uvx (Recommended)

Option 2: Install with uv tool

Option 3: Install with pip

Troubleshooting Commands

Check Installation

Debug Jupyter Startup

Requirements

Next Steps

Installation Guide

Quickstart Tutorial

Troubleshooting

Configuration

Introduction

Getting Started

Integrations

Core Concepts

​CLI Commands

​Command Syntax

​Using uvx signalpilot (recommended)

​Using sp (after global install)

​Core Commands

​uvx signalpilot (or sp init)

​uvx signalpilot version

​uvx signalpilot lab

​SignalPilot Options

​Jupyter Lab Arguments

​uvx signalpilot home

​uvx signalpilot upgrade

​How Upgrade Works

​Auto-Update System

​Minor Updates

​Major Updates

​Disable Auto-Check

​Working Modes

​What Gets Installed

​Python Packages

​Directory Structure

​Alternative Installation Methods

​Option 1: Run with uvx (Recommended)

​Option 2: Install with uv tool

​Option 3: Install with pip

​Troubleshooting Commands

​Check Installation

​Debug Jupyter Startup

​Requirements

​Next Steps

Installation Guide

Quickstart Tutorial

Troubleshooting

Configuration

CLI Commands

Command Syntax

Using uvx signalpilot (recommended)

Using sp (after global install)

Core Commands

`uvx signalpilot` (or `sp init`)

`uvx signalpilot version`

`uvx signalpilot lab`

SignalPilot Options

Jupyter Lab Arguments

`uvx signalpilot home`

`uvx signalpilot upgrade`

How Upgrade Works

Auto-Update System

Minor Updates

Major Updates

Disable Auto-Check

Working Modes

What Gets Installed

Python Packages

Directory Structure

Alternative Installation Methods

Option 1: Run with uvx (Recommended)

Option 2: Install with uv tool

Option 3: Install with pip

Troubleshooting Commands

Check Installation

Debug Jupyter Startup

Requirements

Next Steps