How to Use the open-notebook CLI: Complete Command Reference and Examples

The open-notebook CLI provides a command-line interface to invoke Surreal-Commands directly from your terminal using JSON payloads, enabling automation and scripting without HTTP API calls.

The open-notebook repository by lfnovo ships with a lightweight command-line interface that exposes the same backend functionality available through the API. This CLI, built on the surreal-commands framework, allows you to execute Pydantic-validated commands directly from your shell, making it ideal for automation pipelines and local testing.

Installing the open-notebook CLI

The CLI is installed automatically when you set up the Python package. After cloning the repository and installing dependencies, the entry point becomes available on your system PATH.

pip install -e .

Once installed, verify the CLI is accessible by running:

open_notebook --help

Discovering Available Commands

All CLI commands are defined in the open_notebook/commands/ package and registered automatically with the surreal-commands runner. To see a complete list of available commands:

open_notebook commands list

This outputs a table of registered commands such as process_text, analyze_data, embed_note, and generate_podcast. The command discovery scans the source files—including commands/example_commands.py, commands/embedding_commands.py, and commands/podcast_commands.py—for functions decorated with @command(...).

Running Commands with JSON Payloads

Each command expects a JSON-encoded payload that matches its Pydantic input model. The generic syntax follows this pattern:

open_notebook commands run <command-name> '<json-payload>'

Processing Text Content

The process_text command demonstrates basic text transformations. Located in commands/example_commands.py, the process_text_command function accepts a text string and operation type.

open_notebook commands run process_text '{"text":"Hello world","operation":"uppercase"}'

Output:

{
  "success": true,
  "original_text": "Hello world",
  "processed_text": "HELLO WORLD",
  "processing_time": 0.0012
}

Analyzing Numerical Data

To compute statistics on a dataset, use the analyze_data command implemented in commands/example_commands.py as analyze_data_command:

open_notebook commands run analyze_data '{"numbers":[1,2,3,4,5],"analysis_type":"basic"}'

Output:

{
  "success": true,
  "analysis_type": "basic",
  "count": 5,
  "sum": 15.0,
  "average": 3.0,
  "min_value": 1.0,
  "max_value": 5.0,
  "processing_time": 0.0009
}

Embedding Notes and Sources

For AI-powered workflows, trigger embedding generation via commands/embedding_commands.py:

open_notebook commands run embed_note '{"note_id":"note-123"}'

This forwards the request to the embedding service defined in the embedding pipeline, utilizing the same backend logic as the HTTP API.

Common CLI Flags

The surreal-commands runner supports several useful flags:

• --help — Displays usage information for a specific command, showing available parameters and expected input types.
• --json — Forces pretty-printed JSON output (enabled by default for most commands).

Programmatic Integration

Because the CLI is a thin wrapper around core functions, you can bypass the shell entirely and call commands directly from Python. This mirrors exactly what the CLI does under the hood while providing full access to return types and error handling.

from open_notebook.commands import process_text_command
from open_notebook.commands.example_commands import TextProcessingInput

payload = TextProcessingInput(text="Hello", operation="uppercase")
result = await process_text_command(payload)
print(result.processed_text)  # Output: HELLO

This approach is useful for building custom automation scripts or integrating open-notebook functionality into larger applications without subprocess overhead.

Summary

• Installation: The open_notebook entry point installs automatically with the Python package via pip install -e .
• Discovery: Use open_notebook commands list to see all registered commands from commands/example_commands.py, commands/embedding_commands.py, and related modules.
• Execution: Run commands with open_notebook commands run <name> '<json-payload>' where payloads match Pydantic models.
• Key Commands: process_text and analyze_data provide examples in example_commands.py, while embed_note handles AI embeddings via embedding_commands.py.
• Integration: Import functions like process_text_command directly for programmatic use without CLI overhead.

Frequently Asked Questions

How do I install the open-notebook CLI?

Install the CLI by cloning the lfnovo/open-notebook repository and running pip install -e . or using Poetry. The open_notebook command becomes available on your PATH immediately after installation, requiring no additional configuration.

What input format does the CLI expect?

The open-notebook CLI expects JSON-encoded payloads that match the Pydantic input models defined for each command. For example, the process_text command requires a JSON object with text and operation keys, such as '{"text":"hello","operation":"uppercase"}'.

Can I use CLI commands in Python scripts instead of the terminal?

Yes. Since the CLI is a thin wrapper around core functions, you can import commands directly from open_notebook.commands and call them programmatically. For instance, import process_text_command from commands/example_commands.py and pass Pydantic models like TextProcessingInput to execute logic without subprocess calls.

Where are the CLI commands defined in the source code?

Commands are defined in the open_notebook/commands/ directory. Entry points are registered in commands/__init__.py, example commands like process_text live in commands/example_commands.py, embedding logic is in commands/embedding_commands.py, and podcast generation is in commands/podcast_commands.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}