Skip to main content

Command-Line Interface (CLI)

Automated notebook operations, batch processing, and CI/CD integration.

These tools enable scriptable workflows that complement the UI for interactive use.

Overview​

  • Automated Workflows: Notebook operations in scripts and pipelines
  • Batch Processing: Process multiple notebooks consistently
  • CI/CD Integration: Incorporate AI agents into build/test pipelines
  • Remote Execution: Run agents independently from notebook kernels

Available CLI Tools​

Jupyter AI Agents currently provides the following command-line tools:

Architecture​

Same framework as the UI:

  • Pydantic AI: Type-safe agent orchestration
  • LangChain: Complex workflow management (optional)
  • MCP Tools: Jupyter MCP Server capabilities
  • Jupyter Clients: Direct notebook and kernel integration

Deployment Modes​

Where agents run:

  • Local Execution: Agent runs on the same machine as Jupyter server
  • Remote Execution: Agent runs on separate compute resources
  • Containerized: Agent runs in isolated containers for reproducibility

Interaction Modes​

How agents are triggered:

  • On-Demand: Executed explicitly via CLI commands
  • Event-Driven: React to notebook or kernel changes
  • Scheduled: Run periodically via cron or schedulers

Common Use Cases​

Automated Analysis​

# Generate analysis notebook from data file
jupyter-ai-agent analyze data.csv --output analysis.ipynb

Error Debugging​

# Analyze and fix errors in a notebook
jupyter-ai-agent debug notebook.ipynb --fix-errors

Batch Operations​

# Execute specific cells across multiple notebooks
jupyter-ai-agent execute notebooks/*.ipynb --cell-range 0-5

CI/CD Validation​

# Validate notebooks before commit
jupyter-ai-agent validate *.ipynb --check-execution

Chat vs CLI​

Choose the right tool for your needs:

FeatureChat InterfaceCLI Tools
InteractionNatural language, conversationalCommand-line, scriptable
Use CaseInteractive development, explorationAutomation, batch processing
FeedbackReal-time visual feedbackCommand output, logs
IntegrationJupyterLab UIScripts, CI/CD pipelines
Learning CurveMinimal, conversationalRequires command syntax

When to Use Chat​

  • Interactive notebook development
  • Exploring data and generating code
  • Learning and experimentation
  • Getting immediate visual feedback

When to Use CLI​

  • Automating repetitive tasks
  • Processing multiple notebooks
  • Integrating with build pipelines
  • Running scheduled operations
  • Scripting complex workflows

Creating Custom CLI Agents​

You can create custom CLI agents by extending the base agent class and adding custom tools.

info

Custom agent development uses Pydantic AI for modern, type-safe agent creation, with optional LangChain integration for complex workflows.

🚧 A comprehensive guide for creating custom agents is under development and will be available soon.

Basic Example​

from pydantic_ai import Agent
from jupyter_ai_agents.tools import get_jupyter_tools

# Create a custom agent
agent = Agent(
    model='anthropic:claude-sonnet-4-5',
    system_prompt='You are a data analysis expert.',
    tools=get_jupyter_tools()
)

# Add custom tools
@agent.tool
def custom_analysis(data: str) -> str:
    """Custom analysis tool."""
    # Your analysis logic here
    return "Analysis result"

# Run the agent
result = agent.run_sync('Analyze the data in notebook.ipynb')

Installation​

The CLI tools are included when you install Jupyter AI Agents:

pip install jupyter_ai_agents

Configuration​

CLI agents can be configured via:

  • Environment variables: ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.
  • Configuration files: .jupyter/jupyter_ai_agents_config.json
  • Command-line arguments: Tool-specific options

What's Next​

We're expanding CLI capabilities:

  • 🔧 More specialized agents (refactoring, documentation, testing)
  • 📊 Advanced analysis and reporting tools
  • 🔌 Plugin system for custom CLI commands
  • ⚙️ Enhanced configuration and customization options
  • 🚀 Performance optimizations for large-scale processing

Check our GitHub Issues to see planned features!

Learn More​