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

> Master the open-notebook CLI with our complete command reference and examples. Automate SurrealDB operations directly from your terminal. Get started now.

- Repository: [Luis Novo/open-notebook](https://github.com/lfnovo/open-notebook)
- Tags: api-reference
- Published: 2026-06-13

---

**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.

```bash
pip install -e .

```

Once installed, verify the CLI is accessible by running:

```bash
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:

```bash
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`](https://github.com/lfnovo/open-notebook/blob/main/commands/example_commands.py), [`commands/embedding_commands.py`](https://github.com/lfnovo/open-notebook/blob/main/commands/embedding_commands.py), and [`commands/podcast_commands.py`](https://github.com/lfnovo/open-notebook/blob/main/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:

```bash
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`](https://github.com/lfnovo/open-notebook/blob/main/commands/example_commands.py), the `process_text_command` function accepts a text string and operation type.

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

```

**Output:**

```json
{
  "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`](https://github.com/lfnovo/open-notebook/blob/main/commands/example_commands.py) as `analyze_data_command`:

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

```

**Output:**

```json
{
  "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`](https://github.com/lfnovo/open-notebook/blob/main/commands/embedding_commands.py):

```bash
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.

```python
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`](https://github.com/lfnovo/open-notebook/blob/main/commands/example_commands.py), [`commands/embedding_commands.py`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/example_commands.py), while `embed_note` handles AI embeddings via [`embedding_commands.py`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/commands/__init__.py), example commands like `process_text` live in [`commands/example_commands.py`](https://github.com/lfnovo/open-notebook/blob/main/commands/example_commands.py), embedding logic is in [`commands/embedding_commands.py`](https://github.com/lfnovo/open-notebook/blob/main/commands/embedding_commands.py), and podcast generation is in [`commands/podcast_commands.py`](https://github.com/lfnovo/open-notebook/blob/main/commands/podcast_commands.py).