Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

internal: docs for commands (#7597)

Myles Scolnicke2cf0b4fac47
diff --git a/marimo/_runtime/commands.py b/marimo/_runtime/commands.py
index 51cde2d60b..ec0d9a2574 100644
--- a/marimo/_runtime/commands.py
+++ b/marimo/_runtime/commands.py
@@ -33,6 +33,11 @@ if TYPE_CHECKING:
def kebab_case(name: str) -> str:
+ """Convert PascalCase to kebab-case.
+
+ Removes 'Command' suffix and converts to kebab-case for discriminated union tags.
+ Handles acronyms by keeping consecutive uppercase letters together.
+ """
if name.endswith("Command"):
name = name[:-7] # Remove 'Command' (7 characters)
if not name:
@@ -48,6 +53,14 @@ def kebab_case(name: str) -> str:
class Command(
msgspec.Struct, rename="camel", tag_field="type", tag=kebab_case
):
+ """Base class for runtime commands.
+
+ Discriminated union base using msgspec for serialization. Command subclasses
+ are automatically tagged with their kebab-case name and serialized with
+ camelCase field names. The "type" tag discriminates between commands during
+ deserialization for type-safe routing.
+ """
+
pass
@@ -60,10 +73,20 @@ SerializedCLIArgs = dict[str, ListOrValue[Primitive]]
@dataclass
class HTTPRequest(Mapping[str, Any]):
- """
- A class that mimics the Request object from Starlette or FastAPI.
-
- It is a subset and pickle-able version of the Request object.
+ """Serializable HTTP request representation.
+
+ Mimics Starlette/FastAPI Request but is pickle-able and contains only a safe
+ subset of data. Excludes session and auth to prevent exposing sensitive data.
+
+ Attributes:
+ url: Serialized URL with path, port, scheme, netloc, query, hostname.
+ base_url: Serialized base URL.
+ headers: Request headers (marimo-specific headers excluded).
+ query_params: Query parameters mapped to lists of values.
+ path_params: Path parameters from the URL route.
+ cookies: Request cookies.
+ meta: User-defined storage for custom data.
+ user: User info from authentication middleware (e.g., is_authenticated, username).
"""
url: dict[str, Any] # Serialized URL
@@ -72,7 +95,7 @@ class HTTPRequest(Mapping[str, Any]):
query_params: dict[str, list[str]] # Raw query params
path_params: dict[str, Any]
cookies: dict[str, str]
- meta: dict[str, Any]
+ meta: dict[str, Any] # User-defined storage
user: Any
# We don't include session or auth because they may contain
@@ -147,6 +170,15 @@ class HTTPRequest(Mapping[str, Any]):
class DebugCellCommand(Command):
+ """Enter debugger mode for a cell.
+
+ Starts the Python debugger (pdb) for the specified cell.
+
+ Attributes:
+ cell_id: Cell to debug.
+ request: HTTP request context if available.
+ """
+
cell_id: CellId_t
# incoming request, e.g. from Starlette or FastAPI
request: Optional[HTTPRequest] = None
@@ -156,6 +188,18 @@ class DebugCellCommand(Command):
class ExecuteCellCommand(Command):
+ """Execute a single cell.
+
+ Executes a cell with the provided code. Dependent cells may be
+ re-executed based on the reactive execution mode.
+
+ Attributes:
+ cell_id: Cell to execute.
+ code: Python code to execute.
+ request: HTTP request context if available.
+ timestamp: Unix timestamp when command was created.
+ """
+
cell_id: CellId_t
code: str
# incoming request, e.g. from Starlette or FastAPI
@@ -170,10 +214,31 @@ class ExecuteCellCommand(Command):
class ExecuteStaleCellsCommand(Command):
+ """Execute all stale cells.
+
+ Cells become stale when their dependencies change but haven't been
+ re-executed yet. Brings the notebook to a consistent state.
+
+ Attributes:
+ request: HTTP request context if available.
+ """
+
request: Optional[HTTPRequest] = None
class ExecuteCellsCommand(Command):
+ """Execute multiple cells in a batch.
+
+ Executes multiple cells with their corresponding code. The kernel manages
+ dependency tracking and reactive execution.
+
+ Attributes:
+ cell_ids: Cells to execute.
+ codes: Python code for each cell. Must match length of cell_ids.
+ request: HTTP request context if available.
+ timestamp: Unix timestamp when command was created.
+ """
+
# ids of cells to run
cell_ids: list[CellId_t]
# code to register/run for each cell
@@ -188,6 +253,11 @@ class ExecuteCellsCommand(Command):
@property
def execution_requests(self) -> list[ExecuteCellCommand]:
+ """Convert to individual cell execution commands.
+
+ Returns:
+ List of ExecuteCellCommand instances, one per cell.
+ """
return [
ExecuteCellCommand(
cell_id=cell_id,
@@ -205,6 +275,18 @@ class ExecuteCellsCommand(Command):
class SyncGraphCommand(Command):
+ """Synchronize the kernel graph with file manager state.
+
+ Used when the notebook file changes externally (e.g., file reload or version control).
+ Updates changed cells, deletes removed cells, and optionally executes modified cells.
+
+ Attributes:
+ cells: All cells known to file manager, mapping cell_id to code.
+ run_ids: Cells to execute or update.
+ delete_ids: Cells to delete from the graph.
+ timestamp: Unix timestamp when command was created.
+ """
+
# ids of cells known to filemanager
cells: dict[CellId_t, str]
# From the list of ALL cells that filemanager knows about,
@@ -216,6 +298,11 @@ class SyncGraphCommand(Command):
@property
def execution_requests(self) -> list[ExecuteCellCommand]:
+ """Convert run_ids to individual cell execution commands.
+
+ Returns:
+ List of ExecuteCellCommand instances for cells to execute.
+ """
return [
ExecuteCellCommand(
cell_id=cell_id,
@@ -228,16 +315,47 @@ class SyncGraphCommand(Command):
class ExecuteScratchpadCommand(Command):
+ """Execute code in the scratchpad.
+
+ The scratchpad is a temporary execution environment that doesn't affect
+ the notebook's cells or dependencies. Runs in an isolated cell with a copy
+ of the global namespace, useful for experimentation.
+
+ Attributes:
+ code: Python code to execute.
+ request: HTTP request context if available.
+ """
+
code: str
# incoming request, e.g. from Starlette or FastAPI
request: Optional[HTTPRequest] = None
class RenameNotebookCommand(Command):
+ """Rename or move the notebook file.
+
+ Updates the notebook's filename in the kernel metadata.
+
+ Attributes:
+ filename: New filename or path for the notebook.
+ """
+
filename: str
class UpdateUIElementCommand(Command):
+ """Update UI element values.
+
+ Triggered when users interact with UI elements (sliders, inputs, dropdowns, etc.).
+ Updates element values and re-executes dependent cells.
+
+ Attributes:
+ object_ids: UI elements to update.
+ values: New values for the elements. Must match length of object_ids.
+ request: HTTP request context if available.
+ token: Unique request identifier for deduplication.
+ """
+
object_ids: list[UIElementId]
values: list[Any]
# Incoming request, e.g. from Starlette or FastAPI
@@ -263,6 +381,15 @@ class UpdateUIElementCommand(Command):
ids_and_values: list[tuple[UIElementId, Any]],
request: Optional[HTTPRequest] = None,
) -> UpdateUIElementCommand:
+ """Create command from list of (id, value) tuples.
+
+ Args:
+ ids_and_values: UI element IDs and their new values.
+ request: HTTP request context if available.
+
+ Returns:
+ UpdateUIElementCommand instance.
+ """
if not ids_and_values:
return UpdateUIElementCommand(
object_ids=[], values=[], request=request
@@ -276,10 +403,26 @@ class UpdateUIElementCommand(Command):
@property
def ids_and_values(self) -> list[tuple[UIElementId, Any]]:
+ """UI element IDs and values as tuples.
+
+ Returns:
+ List of (id, value) tuples.
+ """
return list(zip(self.object_ids, self.values))
class InvokeFunctionCommand(Command):
+ """Invoke a function from a UI element.
+
+ Called when a UI element needs to invoke a Python function.
+
+ Attributes:
+ function_call_id: Unique identifier for this call.
+ namespace: Namespace where the function is registered.
+ function_name: Function to invoke.
+ args: Keyword arguments for the function.
+ """
+
function_call_id: RequestId
namespace: str
function_name: str
@@ -289,8 +432,16 @@ class InvokeFunctionCommand(Command):
return f"InvokeFunctionCommand(id={self.function_call_id}, fn={self.namespace}.{self.function_name})"
-class AppMetadata(Command):
- """Hold metadata about the app, like its filename."""
+class AppMetadata(msgspec.Struct, rename="camel"):
+ """Application runtime metadata.
+
+ Attributes:
+ query_params: Query parameters from the URL when running as a web app.
+ cli_args: Command-line arguments passed when starting the app.
+ app_config: Application-level configuration.
+ argv: Full argument vector if available.
+ filename: Path to the notebook file.
+ """
query_params: SerializedQueryParams
cli_args: SerializedCLIArgs
@@ -301,11 +452,28 @@ class AppMetadata(Command):
class UpdateCellConfigCommand(Command):
+ """Update cell configuration.
+
+ Updates cell-level settings like disabled state, hide code, etc.
+
+ Attributes:
+ configs: Cell IDs mapped to their config updates. Each config dict
+ can contain partial updates.
+ """
+
# Map from Cell ID to (possibly partial) CellConfig
configs: dict[CellId_t, dict[str, Any]]
class UpdateUserConfigCommand(Command):
+ """Update user configuration.
+
+ Updates global marimo configuration (runtime settings, display options, editor preferences).
+
+ Attributes:
+ config: Complete user configuration.
+ """
+
# MarimoConfig TypedDict
config: MarimoConfig
@@ -314,6 +482,17 @@ class UpdateUserConfigCommand(Command):
class CreateNotebookCommand(Command):
+ """Instantiate and initialize a notebook.
+
+ Sent when a notebook is first loaded. Contains all cells and initial UI element values.
+
+ Attributes:
+ execution_requests: ExecuteCellCommand for each notebook cell.
+ set_ui_element_value_request: Initial UI element values.
+ auto_run: Whether to automatically execute cells on instantiation.
+ request: HTTP request context if available.
+ """
+
execution_requests: tuple[ExecuteCellCommand, ...]
set_ui_element_value_request: UpdateUIElementCommand
auto_run: bool
@@ -321,14 +500,40 @@ class CreateNotebookCommand(Command):
class DeleteCellCommand(Command):
+ """Delete a cell from the notebook.
+
+ Removes cell from the dependency graph and cleans up its variables.
+ Dependent cells may become stale.
+
+ Attributes:
+ cell_id: Cell to delete.
+ """
+
cell_id: CellId_t
class StopKernelCommand(Command):
+ """Stop kernel execution.
+
+ Signals the kernel to stop processing and shut down gracefully.
+ Used when closing a notebook or terminating a session.
+ """
+
pass
class CodeCompletionCommand(Command):
+ """Request code completion suggestions.
+
+ Sent when the user requests autocomplete. Provides code context up to
+ the cursor position for the language server.
+
+ Attributes:
+ id: Unique identifier for this request.
+ document: Source code up to the cursor position.
+ cell_id: Cell where completion is requested.
+ """
+
id: RequestId
document: str
"""Source code found in the cell up to the cursor position."""
@@ -339,6 +544,17 @@ class CodeCompletionCommand(Command):
class InstallPackagesCommand(Command):
+ """Install Python packages.
+
+ Installs missing packages using the specified package manager. Triggered
+ automatically on import errors or manually by the user.
+
+ Attributes:
+ manager: Package manager to use ('pip', 'conda', 'uv', etc.).
+ versions: Package names mapped to version specifiers. Empty version
+ means install latest.
+ """
+
# TODO: index URL (index/channel/...)
manager: str
@@ -349,6 +565,19 @@ class InstallPackagesCommand(Command):
class PreviewDatasetColumnCommand(Command):
+ """Preview a dataset column.
+
+ Retrieves and displays data from a single column (dataframe or SQL table).
+ Used by the data explorer UI.
+
+ Attributes:
+ source_type: Data source type ('dataframe', 'sql', etc.).
+ source: Source identifier (connection string or variable name).
+ table_name: Table or dataframe variable name.
+ column_name: Column to preview.
+ fully_qualified_table_name: Full database.schema.table name for SQL.
+ """
+
# The source type of the dataset
source_type: DataTableSource
# The source of the dataset
@@ -365,7 +594,18 @@ class PreviewDatasetColumnCommand(Command):
class PreviewSQLTableCommand(Command):
- """Preview table details in an SQL database"""
+ """Preview SQL table details.
+
+ Retrieves metadata and sample data for a table. Used by the SQL editor
+ and data explorer.
+
+ Attributes:
+ request_id: Unique identifier for this request.
+ engine: SQL engine ('postgresql', 'mysql', 'duckdb', etc.).
+ database: Database containing the table.
+ schema: Schema containing the table.
+ table_name: Table to preview.
+ """
request_id: RequestId
engine: str
@@ -375,7 +615,17 @@ class PreviewSQLTableCommand(Command):
class ListSQLTablesCommand(Command):
- """Preview list of tables in an SQL schema"""
+ """List tables in an SQL schema.
+
+ Retrieves names of all tables and views in a schema. Used by the SQL
+ editor for table selection.
+
+ Attributes:
+ request_id: Unique identifier for this request.
+ engine: SQL engine ('postgresql', 'mysql', 'duckdb', etc.).
+ database: Database to query.
+ schema: Schema to list tables from.
+ """
request_id: RequestId
engine: str
@@ -384,13 +634,30 @@ class ListSQLTablesCommand(Command):
class ListDataSourceConnectionCommand(Command):
- """Fetch a datasource connection"""
+ """List data source schemas.
+
+ Retrieves available schemas for a data source engine.
+
+ Attributes:
+ engine: Data source engine identifier.
+ """
engine: str
class ValidateSQLCommand(Command):
- """Validate an SQL query against the engine"""
+ """Validate an SQL query.
+
+ Checks if an SQL query is valid by parsing against a dialect (no DB connection)
+ or validating against an actual database.
+
+ Attributes:
+ request_id: Unique identifier for this request.
+ query: SQL query to validate.
+ only_parse: If True, only parse using dialect. If False, validate against DB.
+ engine: SQL engine (required if only_parse is False).
+ dialect: SQL dialect for parsing (required if only_parse is True).
+ """
request_id: RequestId
query: str
@@ -402,29 +669,72 @@ class ValidateSQLCommand(Command):
class ListSecretKeysCommand(Command):
+ """List available secret keys.
+
+ Retrieves secret names without exposing values.
+
+ Attributes:
+ request_id: Unique identifier for this request.
+ """
+
request_id: RequestId
class ModelMessage(msgspec.Struct, rename="camel"):
+ """Widget model state update message.
+
+ State changes for anywidget models, including state dict and binary buffer paths.
+
+ Attributes:
+ state: Model state updates.
+ buffer_paths: Paths within state dict pointing to binary buffers.
+ """
+
state: dict[str, Any]
buffer_paths: list[list[Union[str, int]]]
class UpdateWidgetModelCommand(Command):
+ """Update anywidget model state.
+
+ Updates widget model state for bidirectional Python-JavaScript communication.
+
+ Attributes:
+ model_id: Widget model identifier.
+ message: Model message with state updates and buffer paths.
+ buffers: Base64-encoded binary buffers referenced by buffer_paths.
+ """
+
model_id: WidgetModelId
message: ModelMessage
buffers: Optional[list[str]] = None
class RefreshSecretsCommand(Command):
+ """Refresh secrets from the secrets store.
+
+ Reloads secrets from the provider without restarting the kernel.
+ """
+
pass
class ClearCacheCommand(Command):
+ """Clear all cached data.
+
+ Clears all cache contexts, freeing memory and disk space.
+ Affects all cells using the @cache decorator.
+ """
+
pass
class GetCacheInfoCommand(Command):
+ """Retrieve cache statistics.
+
+ Collects cache usage info across all contexts (hit/miss rates, time saved, disk usage).
+ """
+
pass
@@ -463,3 +773,8 @@ CommandMessage = Union[
# Kernel operations
StopKernelCommand,
]
+"""Union of all command messages.
+
+All commands that can be sent to the kernel.
+
+"""
diff --git a/packages/openapi/api.yaml b/packages/openapi/api.yaml
index b4aca18315..df078a81d8 100644
--- a/packages/openapi/api.yaml
+++ b/packages/openapi/api.yaml
@@ -559,6 +559,8 @@ components:
title: ChatRequest
type: object
ClearCacheCommand:
+ description: "Clear all cached data.\n\n Clears all cache contexts, freeing\
+ \ memory and disk space.\n Affects all cells using the @cache decorator."
properties:
type:
enum:
@@ -573,6 +575,11 @@ components:
title: ClearCacheRequest
type: object
CodeCompletionCommand:
+ description: "Request code completion suggestions.\n\n Sent when the user\
+ \ requests autocomplete. Provides code context up to\n the cursor position\
+ \ for the language server.\n\n Attributes:\n id: Unique identifier\
+ \ for this request.\n document: Source code up to the cursor position.\n\
+ \ cell_id: Cell where completion is requested."
properties:
cellId:
type: string
@@ -781,6 +788,12 @@ components:
title: CopyNotebookRequest
type: object
CreateNotebookCommand:
+ description: "Instantiate and initialize a notebook.\n\n Sent when a notebook\
+ \ is first loaded. Contains all cells and initial UI element values.\n\n \
+ \ Attributes:\n execution_requests: ExecuteCellCommand for each notebook\
+ \ cell.\n set_ui_element_value_request: Initial UI element values.\n\
+ \ auto_run: Whether to automatically execute cells on instantiation.\n\
+ \ request: HTTP request context if available."
properties:
autoRun:
type: boolean
@@ -1123,6 +1136,9 @@ components:
title: DatasourcesConfig
type: object
DebugCellCommand:
+ description: "Enter debugger mode for a cell.\n\n Starts the Python debugger\
+ \ (pdb) for the specified cell.\n\n Attributes:\n cell_id: Cell\
+ \ to debug.\n request: HTTP request context if available."
properties:
cellId:
type: string
@@ -1153,6 +1169,9 @@ components:
title: DebugCellRequest
type: object
DeleteCellCommand:
+ description: "Delete a cell from the notebook.\n\n Removes cell from the\
+ \ dependency graph and cleans up its variables.\n Dependent cells may become\
+ \ stale.\n\n Attributes:\n cell_id: Cell to delete."
properties:
cellId:
type: string
@@ -1286,6 +1305,11 @@ components:
title: DisplayConfig
type: object
ExecuteCellCommand:
+ description: "Execute a single cell.\n\n Executes a cell with the provided\
+ \ code. Dependent cells may be\n re-executed based on the reactive execution\
+ \ mode.\n\n Attributes:\n cell_id: Cell to execute.\n code:\
+ \ Python code to execute.\n request: HTTP request context if available.\n\
+ \ timestamp: Unix timestamp when command was created."
properties:
cellId:
type: string
@@ -1308,6 +1332,12 @@ components:
title: ExecuteCellCommand
type: object
ExecuteCellsCommand:
+ description: "Execute multiple cells in a batch.\n\n Executes multiple cells\
+ \ with their corresponding code. The kernel manages\n dependency tracking\
+ \ and reactive execution.\n\n Attributes:\n cell_ids: Cells to execute.\n\
+ \ codes: Python code for each cell. Must match length of cell_ids.\n\
+ \ request: HTTP request context if available.\n timestamp: Unix\
+ \ timestamp when command was created."
properties:
cellIds:
items:
@@ -1354,6 +1384,11 @@ components:
title: ExecuteCellsRequest
type: object
ExecuteScratchpadCommand:
+ description: "Execute code in the scratchpad.\n\n The scratchpad is a temporary\
+ \ execution environment that doesn't affect\n the notebook's cells or dependencies.\
+ \ Runs in an isolated cell with a copy\n of the global namespace, useful\
+ \ for experimentation.\n\n Attributes:\n code: Python code to execute.\n\
+ \ request: HTTP request context if available."
properties:
code:
type: string
@@ -1384,6 +1419,10 @@ components:
title: ExecuteScratchpadRequest
type: object
ExecuteStaleCellsCommand:
+ description: "Execute all stale cells.\n\n Cells become stale when their\
+ \ dependencies change but haven't been\n re-executed yet. Brings the notebook\
+ \ to a consistent state.\n\n Attributes:\n request: HTTP request\
+ \ context if available."
properties:
request:
anyOf:
@@ -1757,6 +1796,8 @@ components:
title: FunctionCallResultNotification
type: object
GetCacheInfoCommand:
+ description: "Retrieve cache statistics.\n\n Collects cache usage info across\
+ \ all contexts (hit/miss rates, time saved, disk usage)."
properties:
type:
enum:
@@ -1796,10 +1837,16 @@ components:
title: GoogleAiConfig
type: object
HTTPRequest:
- description: 'A class that mimics the Request object from Starlette or FastAPI.
-
-
- It is a subset and pickle-able version of the Request object.'
+ description: "Serializable HTTP request representation.\n\n Mimics Starlette/FastAPI\
+ \ Request but is pickle-able and contains only a safe\n subset of data.\
+ \ Excludes session and auth to prevent exposing sensitive data.\n\n Attributes:\n\
+ \ url: Serialized URL with path, port, scheme, netloc, query, hostname.\n\
+ \ base_url: Serialized base URL.\n headers: Request headers\
+ \ (marimo-specific headers excluded).\n query_params: Query parameters\
+ \ mapped to lists of values.\n path_params: Path parameters from the\
+ \ URL route.\n cookies: Request cookies.\n meta: User-defined\
+ \ storage for custom data.\n user: User info from authentication middleware\
+ \ (e.g., is_authenticated, username)."
properties:
base_url:
type: object
@@ -1874,6 +1921,11 @@ components:
title: ImportStarError
type: object
InstallPackagesCommand:
+ description: "Install Python packages.\n\n Installs missing packages using\
+ \ the specified package manager. Triggered\n automatically on import errors\
+ \ or manually by the user.\n\n Attributes:\n manager: Package manager\
+ \ to use ('pip', 'conda', 'uv', etc.).\n versions: Package names mapped\
+ \ to version specifiers. Empty version\n means install latest."
properties:
manager:
type: string
@@ -1992,6 +2044,11 @@ components:
title: InvokeAiToolResponse
type: object
InvokeFunctionCommand:
+ description: "Invoke a function from a UI element.\n\n Called when a UI element\
+ \ needs to invoke a Python function.\n\n Attributes:\n function_call_id:\
+ \ Unique identifier for this call.\n namespace: Namespace where the\
+ \ function is registered.\n function_name: Function to invoke.\n \
+ \ args: Keyword arguments for the function."
properties:
args:
type: object
@@ -2336,7 +2393,9 @@ components:
title: LayoutConfig
type: object
ListDataSourceConnectionCommand:
- description: Fetch a datasource connection
+ description: "List data source schemas.\n\n Retrieves available schemas for\
+ \ a data source engine.\n\n Attributes:\n engine: Data source engine\
+ \ identifier."
properties:
engine:
type: string
@@ -2367,7 +2426,12 @@ components:
title: ListPackagesResponse
type: object
ListSQLTablesCommand:
- description: Preview list of tables in an SQL schema
+ description: "List tables in an SQL schema.\n\n Retrieves names of all tables\
+ \ and views in a schema. Used by the SQL\n editor for table selection.\n\
+ \n Attributes:\n request_id: Unique identifier for this request.\n\
+ \ engine: SQL engine ('postgresql', 'mysql', 'duckdb', etc.).\n \
+ \ database: Database to query.\n schema: Schema to list tables\
+ \ from."
properties:
database:
type: string
@@ -2406,6 +2470,9 @@ components:
title: ListSQLTablesRequest
type: object
ListSecretKeysCommand:
+ description: "List available secret keys.\n\n Retrieves secret names without\
+ \ exposing values.\n\n Attributes:\n request_id: Unique identifier\
+ \ for this request."
properties:
requestId:
type: string
@@ -2752,6 +2819,10 @@ components:
title: MissingPackageAlertNotification
type: object
ModelMessage:
+ description: "Widget model state update message.\n\n State changes for anywidget\
+ \ models, including state dict and binary buffer paths.\n\n Attributes:\n\
+ \ state: Model state updates.\n buffer_paths: Paths within state\
+ \ dict pointing to binary buffers."
properties:
bufferPaths:
items:
@@ -2878,6 +2949,13 @@ components:
title: PackageOperationResponse
type: object
PreviewDatasetColumnCommand:
+ description: "Preview a dataset column.\n\n Retrieves and displays data from\
+ \ a single column (dataframe or SQL table).\n Used by the data explorer\
+ \ UI.\n\n Attributes:\n source_type: Data source type ('dataframe',\
+ \ 'sql', etc.).\n source: Source identifier (connection string or variable\
+ \ name).\n table_name: Table or dataframe variable name.\n column_name:\
+ \ Column to preview.\n fully_qualified_table_name: Full database.schema.table\
+ \ name for SQL."
properties:
columnName:
type: string
@@ -2934,7 +3012,12 @@ components:
title: PreviewDatasetColumnRequest
type: object
PreviewSQLTableCommand:
- description: Preview table details in an SQL database
+ description: "Preview SQL table details.\n\n Retrieves metadata and sample\
+ \ data for a table. Used by the SQL editor\n and data explorer.\n\n \
+ \ Attributes:\n request_id: Unique identifier for this request.\n \
+ \ engine: SQL engine ('postgresql', 'mysql', 'duckdb', etc.).\n \
+ \ database: Database containing the table.\n schema: Schema containing\
+ \ the table.\n table_name: Table to preview."
properties:
database:
type: string
@@ -3090,6 +3173,8 @@ components:
title: ReconnectedNotification
type: object
RefreshSecretsCommand:
+ description: "Refresh secrets from the secrets store.\n\n Reloads secrets\
+ \ from the provider without restarting the kernel."
properties:
type:
enum:
@@ -3139,6 +3224,9 @@ components:
title: RemoveUIElementsNotification
type: object
RenameNotebookCommand:
+ description: "Rename or move the notebook file.\n\n Updates the notebook's\
+ \ filename in the kernel metadata.\n\n Attributes:\n filename: New\
+ \ filename or path for the notebook."
properties:
filename:
type: string
@@ -3672,6 +3760,9 @@ components:
title: StdinRequest
type: object
StopKernelCommand:
+ description: "Stop kernel execution.\n\n Signals the kernel to stop processing\
+ \ and shut down gracefully.\n Used when closing a notebook or terminating\
+ \ a session."
properties:
type:
enum:
@@ -3703,6 +3794,13 @@ components:
title: SuccessResponse
type: object
SyncGraphCommand:
+ description: "Synchronize the kernel graph with file manager state.\n\n Used\
+ \ when the notebook file changes externally (e.g., file reload or version\
+ \ control).\n Updates changed cells, deletes removed cells, and optionally\
+ \ executes modified cells.\n\n Attributes:\n cells: All cells known\
+ \ to file manager, mapping cell_id to code.\n run_ids: Cells to execute\
+ \ or update.\n delete_ids: Cells to delete from the graph.\n \
+ \ timestamp: Unix timestamp when command was created."
properties:
cells:
additionalProperties:
@@ -3841,6 +3939,10 @@ components:
title: UpdateCellCodesNotification
type: object
UpdateCellConfigCommand:
+ description: "Update cell configuration.\n\n Updates cell-level settings\
+ \ like disabled state, hide code, etc.\n\n Attributes:\n configs:\
+ \ Cell IDs mapped to their config updates. Each config dict\n \
+ \ can contain partial updates."
properties:
configs:
additionalProperties:
@@ -3895,6 +3997,12 @@ components:
title: UpdateCellIdsRequest
type: object
UpdateUIElementCommand:
+ description: "Update UI element values.\n\n Triggered when users interact\
+ \ with UI elements (sliders, inputs, dropdowns, etc.).\n Updates element\
+ \ values and re-executes dependent cells.\n\n Attributes:\n object_ids:\
+ \ UI elements to update.\n values: New values for the elements. Must\
+ \ match length of object_ids.\n request: HTTP request context if available.\n\
+ \ token: Unique request identifier for deduplication."
properties:
objectIds:
items:
@@ -3952,6 +4060,9 @@ components:
title: UpdateUIElementValuesRequest
type: object
UpdateUserConfigCommand:
+ description: "Update user configuration.\n\n Updates global marimo configuration\
+ \ (runtime settings, display options, editor preferences).\n\n Attributes:\n\
+ \ config: Complete user configuration."
properties:
config:
$ref: '#/components/schemas/MarimoConfig'
@@ -3972,6 +4083,11 @@ components:
title: UpdateUserConfigRequest
type: object
UpdateWidgetModelCommand:
+ description: "Update anywidget model state.\n\n Updates widget model state\
+ \ for bidirectional Python-JavaScript communication.\n\n Attributes:\n\
+ \ model_id: Widget model identifier.\n message: Model message\
+ \ with state updates and buffer paths.\n buffers: Base64-encoded binary\
+ \ buffers referenced by buffer_paths."
properties:
buffers:
anyOf:
@@ -4012,7 +4128,13 @@ components:
title: UpdateWidgetModelRequest
type: object
ValidateSQLCommand:
- description: Validate an SQL query against the engine
+ description: "Validate an SQL query.\n\n Checks if an SQL query is valid\
+ \ by parsing against a dialect (no DB connection)\n or validating against\
+ \ an actual database.\n\n Attributes:\n request_id: Unique identifier\
+ \ for this request.\n query: SQL query to validate.\n only_parse:\
+ \ If True, only parse using dialect. If False, validate against DB.\n \
+ \ engine: SQL engine (required if only_parse is False).\n dialect:\
+ \ SQL dialect for parsing (required if only_parse is True)."
properties:
dialect:
anyOf:
diff --git a/packages/openapi/src/api.ts b/packages/openapi/src/api.ts
index 0f3291b9f3..6be9945861 100644
--- a/packages/openapi/src/api.ts
+++ b/packages/openapi/src/api.ts
@@ -3118,14 +3118,31 @@ export interface components {
/** @default null */
variables?: (string | components["schemas"]["VariableContext"])[] | null;
};
- /** ClearCacheCommand */
+ /**
+ * ClearCacheCommand
+ * @description Clear all cached data.
+ *
+ * Clears all cache contexts, freeing memory and disk space.
+ * Affects all cells using the @cache decorator.
+ */
ClearCacheCommand: {
/** @enum {unknown} */
type: "clear-cache";
};
/** ClearCacheRequest */
ClearCacheRequest: Record<string, any>;
- /** CodeCompletionCommand */
+ /**
+ * CodeCompletionCommand
+ * @description Request code completion suggestions.
+ *
+ * Sent when the user requests autocomplete. Provides code context up to
+ * the cursor position for the language server.
+ *
+ * Attributes:
+ * id: Unique identifier for this request.
+ * document: Source code up to the cursor position.
+ * cell_id: Cell where completion is requested.
+ */
CodeCompletionCommand: {
cellId: string;
document: string;
@@ -3227,7 +3244,18 @@ export interface components {
destination: string;
source: string;
};
- /** CreateNotebookCommand */
+ /**
+ * CreateNotebookCommand
+ * @description Instantiate and initialize a notebook.
+ *
+ * Sent when a notebook is first loaded. Contains all cells and initial UI element values.
+ *
+ * Attributes:
+ * execution_requests: ExecuteCellCommand for each notebook cell.
+ * set_ui_element_value_request: Initial UI element values.
+ * auto_run: Whether to automatically execute cells on instantiation.
+ * request: HTTP request context if available.
+ */
CreateNotebookCommand: {
autoRun: boolean;
executionRequests: components["schemas"]["ExecuteCellCommand"][];
@@ -3407,7 +3435,16 @@ export interface components {
auto_discover_schemas?: boolean | "auto";
auto_discover_tables?: boolean | "auto";
};
- /** DebugCellCommand */
+ /**
+ * DebugCellCommand
+ * @description Enter debugger mode for a cell.
+ *
+ * Starts the Python debugger (pdb) for the specified cell.
+ *
+ * Attributes:
+ * cell_id: Cell to debug.
+ * request: HTTP request context if available.
+ */
DebugCellCommand: {
cellId: string;
/** @default null */
@@ -3421,7 +3458,16 @@ export interface components {
/** @default null */
request?: components["schemas"]["HTTPRequest"] | null;
};
- /** DeleteCellCommand */
+ /**
+ * DeleteCellCommand
+ * @description Delete a cell from the notebook.
+ *
+ * Removes cell from the dependency graph and cleans up its variables.
+ * Dependent cells may become stale.
+ *
+ * Attributes:
+ * cell_id: Cell to delete.
+ */
DeleteCellCommand: {
cellId: string;
/** @enum {unknown} */
@@ -3493,7 +3539,19 @@ export interface components {
/** @enum {unknown} */
theme: "dark" | "light" | "system";
};
- /** ExecuteCellCommand */
+ /**
+ * ExecuteCellCommand
+ * @description Execute a single cell.
+ *
+ * Executes a cell with the provided code. Dependent cells may be
+ * re-executed based on the reactive execution mode.
+ *
+ * Attributes:
+ * cell_id: Cell to execute.
+ * code: Python code to execute.
+ * request: HTTP request context if available.
+ * timestamp: Unix timestamp when command was created.
+ */
ExecuteCellCommand: {
cellId: string;
code: string;
@@ -3503,7 +3561,19 @@ export interface components {
/** @enum {unknown} */
type: "execute-cell";
};
- /** ExecuteCellsCommand */
+ /**
+ * ExecuteCellsCommand
+ * @description Execute multiple cells in a batch.
+ *
+ * Executes multiple cells with their corresponding code. The kernel manages
+ * dependency tracking and reactive execution.
+ *
+ * Attributes:
+ * cell_ids: Cells to execute.
+ * codes: Python code for each cell. Must match length of cell_ids.
+ * request: HTTP request context if available.
+ * timestamp: Unix timestamp when command was created.
+ */
ExecuteCellsCommand: {
cellIds: string[];
codes: string[];
@@ -3520,7 +3590,18 @@ export interface components {
/** @default null */
request?: components["schemas"]["HTTPRequest"] | null;
};
- /** ExecuteScratchpadCommand */
+ /**
+ * ExecuteScratchpadCommand
+ * @description Execute code in the scratchpad.
+ *
+ * The scratchpad is a temporary execution environment that doesn't affect
+ * the notebook's cells or dependencies. Runs in an isolated cell with a copy
+ * of the global namespace, useful for experimentation.
+ *
+ * Attributes:
+ * code: Python code to execute.
+ * request: HTTP request context if available.
+ */
ExecuteScratchpadCommand: {
code: string;
/** @default null */
@@ -3534,7 +3615,16 @@ export interface components {
/** @default null */
request?: components["schemas"]["HTTPRequest"] | null;
};
- /** ExecuteStaleCellsCommand */
+ /**
+ * ExecuteStaleCellsCommand
+ * @description Execute all stale cells.
+ *
+ * Cells become stale when their dependencies change but haven't been
+ * re-executed yet. Brings the notebook to a consistent state.
+ *
+ * Attributes:
+ * request: HTTP request context if available.
+ */
ExecuteStaleCellsCommand: {
/** @default null */
request?: components["schemas"]["HTTPRequest"] | null;
@@ -3715,7 +3805,12 @@ export interface components {
return_value: unknown;
status: components["schemas"]["HumanReadableStatus"];
};
- /** GetCacheInfoCommand */
+ /**
+ * GetCacheInfoCommand
+ * @description Retrieve cache statistics.
+ *
+ * Collects cache usage info across all contexts (hit/miss rates, time saved, disk usage).
+ */
GetCacheInfoCommand: {
/** @enum {unknown} */
type: "get-cache-info";
@@ -3752,9 +3847,20 @@ export interface components {
};
/**
* HTTPRequest
- * @description A class that mimics the Request object from Starlette or FastAPI.
+ * @description Serializable HTTP request representation.
+ *
+ * Mimics Starlette/FastAPI Request but is pickle-able and contains only a safe
+ * subset of data. Excludes session and auth to prevent exposing sensitive data.
*
- * It is a subset and pickle-able version of the Request object.
+ * Attributes:
+ * url: Serialized URL with path, port, scheme, netloc, query, hostname.
+ * base_url: Serialized base URL.
+ * headers: Request headers (marimo-specific headers excluded).
+ * query_params: Query parameters mapped to lists of values.
+ * path_params: Path parameters from the URL route.
+ * cookies: Request cookies.
+ * meta: User-defined storage for custom data.
+ * user: User info from authentication middleware (e.g., is_authenticated, username).
*/
HTTPRequest: {
base_url: Record<string, any>;
@@ -3792,7 +3898,18 @@ export interface components {
/** @enum {unknown} */
type: "import-star";
};
- /** InstallPackagesCommand */
+ /**
+ * InstallPackagesCommand
+ * @description Install Python packages.
+ *
+ * Installs missing packages using the specified package manager. Triggered
+ * automatically on import errors or manually by the user.
+ *
+ * Attributes:
+ * manager: Package manager to use ('pip', 'conda', 'uv', etc.).
+ * versions: Package names mapped to version specifiers. Empty version
+ * means install latest.
+ */
InstallPackagesCommand: {
manager: string;
/** @enum {unknown} */
@@ -3850,7 +3967,18 @@ export interface components {
success: boolean;
toolName: string;
};
- /** InvokeFunctionCommand */
+ /**
+ * InvokeFunctionCommand
+ * @description Invoke a function from a UI element.
+ *
+ * Called when a UI element needs to invoke a Python function.
+ *
+ * Attributes:
+ * function_call_id: Unique identifier for this call.
+ * namespace: Namespace where the function is registered.
+ * function_name: Function to invoke.
+ * args: Keyword arguments for the function.
+ */
InvokeFunctionCommand: {
args: Record<string, any>;
functionCallId: string;
@@ -4027,7 +4155,12 @@ export interface components {
};
/**
* ListDataSourceConnectionCommand
- * @description Fetch a datasource connection
+ * @description List data source schemas.
+ *
+ * Retrieves available schemas for a data source engine.
+ *
+ * Attributes:
+ * engine: Data source engine identifier.
*/
ListDataSourceConnectionCommand: {
engine: string;
@@ -4044,7 +4177,16 @@ export interface components {
};
/**
* ListSQLTablesCommand
- * @description Preview list of tables in an SQL schema
+ * @description List tables in an SQL schema.
+ *
+ * Retrieves names of all tables and views in a schema. Used by the SQL
+ * editor for table selection.
+ *
+ * Attributes:
+ * request_id: Unique identifier for this request.
+ * engine: SQL engine ('postgresql', 'mysql', 'duckdb', etc.).
+ * database: Database to query.
+ * schema: Schema to list tables from.
*/
ListSQLTablesCommand: {
database: string;
@@ -4061,7 +4203,15 @@ export interface components {
requestId: string;
schema: string;
};
- /** ListSecretKeysCommand */
+ /**
+ * ListSecretKeysCommand
+ * @description List available secret keys.
+ *
+ * Retrieves secret names without exposing values.
+ *
+ * Attributes:
+ * request_id: Unique identifier for this request.
+ */
ListSecretKeysCommand: {
requestId: string;
/** @enum {unknown} */
@@ -4228,7 +4378,16 @@ export interface components {
op: "missing-package-alert";
packages: string[];
};
- /** ModelMessage */
+ /**
+ * ModelMessage
+ * @description Widget model state update message.
+ *
+ * State changes for anywidget models, including state dict and binary buffer paths.
+ *
+ * Attributes:
+ * state: Model state updates.
+ * buffer_paths: Paths within state dict pointing to binary buffers.
+ */
ModelMessage: {
bufferPaths: (string | number)[][];
state: Record<string, any>;
@@ -4305,7 +4464,20 @@ export interface components {
error?: string | null;
success: boolean;
};
- /** PreviewDatasetColumnCommand */
+ /**
+ * PreviewDatasetColumnCommand
+ * @description Preview a dataset column.
+ *
+ * Retrieves and displays data from a single column (dataframe or SQL table).
+ * Used by the data explorer UI.
+ *
+ * Attributes:
+ * source_type: Data source type ('dataframe', 'sql', etc.).
+ * source: Source identifier (connection string or variable name).
+ * table_name: Table or dataframe variable name.
+ * column_name: Column to preview.
+ * fully_qualified_table_name: Full database.schema.table name for SQL.
+ */
PreviewDatasetColumnCommand: {
columnName: string;
/** @default null */
@@ -4329,7 +4501,17 @@ export interface components {
};
/**
* PreviewSQLTableCommand
- * @description Preview table details in an SQL database
+ * @description Preview SQL table details.
+ *
+ * Retrieves metadata and sample data for a table. Used by the SQL editor
+ * and data explorer.
+ *
+ * Attributes:
+ * request_id: Unique identifier for this request.
+ * engine: SQL engine ('postgresql', 'mysql', 'duckdb', etc.).
+ * database: Database containing the table.
+ * schema: Schema containing the table.
+ * table_name: Table to preview.
*/
PreviewSQLTableCommand: {
database: string;
@@ -4405,7 +4587,12 @@ export interface components {
/** @enum {unknown} */
op: "reconnected";
};
- /** RefreshSecretsCommand */
+ /**
+ * RefreshSecretsCommand
+ * @description Refresh secrets from the secrets store.
+ *
+ * Reloads secrets from the provider without restarting the kernel.
+ */
RefreshSecretsCommand: {
/** @enum {unknown} */
type: "refresh-secrets";
@@ -4432,7 +4619,15 @@ export interface components {
/** @enum {unknown} */
op: "remove-ui-elements";
};
- /** RenameNotebookCommand */
+ /**
+ * RenameNotebookCommand
+ * @description Rename or move the notebook file.
+ *
+ * Updates the notebook's filename in the kernel metadata.
+ *
+ * Attributes:
+ * filename: New filename or path for the notebook.
+ */
RenameNotebookCommand: {
filename: string;
/** @enum {unknown} */
@@ -4732,7 +4927,13 @@ export interface components {
StdinRequest: {
text: string;
};
- /** StopKernelCommand */
+ /**
+ * StopKernelCommand
+ * @description Stop kernel execution.
+ *
+ * Signals the kernel to stop processing and shut down gracefully.
+ * Used when closing a notebook or terminating a session.
+ */
StopKernelCommand: {
/** @enum {unknown} */
type: "stop-kernel";
@@ -4751,7 +4952,19 @@ export interface components {
/** @default true */
success?: boolean;
};
- /** SyncGraphCommand */
+ /**
+ * SyncGraphCommand
+ * @description Synchronize the kernel graph with file manager state.
+ *
+ * Used when the notebook file changes externally (e.g., file reload or version control).
+ * Updates changed cells, deletes removed cells, and optionally executes modified cells.
+ *
+ * Attributes:
+ * cells: All cells known to file manager, mapping cell_id to code.
+ * run_ids: Cells to execute or update.
+ * delete_ids: Cells to delete from the graph.
+ * timestamp: Unix timestamp when command was created.
+ */
SyncGraphCommand: {
cells: {
[key: string]: string;
@@ -4813,7 +5026,16 @@ export interface components {
/** @enum {unknown} */
op: "update-cell-codes";
};
- /** UpdateCellConfigCommand */
+ /**
+ * UpdateCellConfigCommand
+ * @description Update cell configuration.
+ *
+ * Updates cell-level settings like disabled state, hide code, etc.
+ *
+ * Attributes:
+ * configs: Cell IDs mapped to their config updates. Each config dict
+ * can contain partial updates.
+ */
UpdateCellConfigCommand: {
configs: {
[key: string]: Record<string, any>;
@@ -4843,7 +5065,19 @@ export interface components {
UpdateCellIdsRequest: {
cellIds: string[];
};
- /** UpdateUIElementCommand */
+ /**
+ * UpdateUIElementCommand
+ * @description Update UI element values.
+ *
+ * Triggered when users interact with UI elements (sliders, inputs, dropdowns, etc.).
+ * Updates element values and re-executes dependent cells.
+ *
+ * Attributes:
+ * object_ids: UI elements to update.
+ * values: New values for the elements. Must match length of object_ids.
+ * request: HTTP request context if available.
+ * token: Unique request identifier for deduplication.
+ */
UpdateUIElementCommand: {
objectIds: string[];
/** @default null */
@@ -4866,7 +5100,15 @@ export interface components {
objectIds: string[];
values: unknown[];
};
- /** UpdateUserConfigCommand */
+ /**
+ * UpdateUserConfigCommand
+ * @description Update user configuration.
+ *
+ * Updates global marimo configuration (runtime settings, display options, editor preferences).
+ *
+ * Attributes:
+ * config: Complete user configuration.
+ */
UpdateUserConfigCommand: {
config: components["schemas"]["MarimoConfig"];
/** @enum {unknown} */
@@ -4876,7 +5118,17 @@ export interface components {
UpdateUserConfigRequest: {
config: components["schemas"]["MarimoConfig"];
};
- /** UpdateWidgetModelCommand */
+ /**
+ * UpdateWidgetModelCommand
+ * @description Update anywidget model state.
+ *
+ * Updates widget model state for bidirectional Python-JavaScript communication.
+ *
+ * Attributes:
+ * model_id: Widget model identifier.
+ * message: Model message with state updates and buffer paths.
+ * buffers: Base64-encoded binary buffers referenced by buffer_paths.
+ */
UpdateWidgetModelCommand: {
/** @default null */
buffers?: string[] | null;
@@ -4894,7 +5146,17 @@ export interface components {
};
/**
* ValidateSQLCommand
- * @description Validate an SQL query against the engine
+ * @description Validate an SQL query.
+ *
+ * Checks if an SQL query is valid by parsing against a dialect (no DB connection)
+ * or validating against an actual database.
+ *
+ * Attributes:
+ * request_id: Unique identifier for this request.
+ * query: SQL query to validate.
+ * only_parse: If True, only parse using dialect. If False, validate against DB.
+ * engine: SQL engine (required if only_parse is False).
+ * dialect: SQL dialect for parsing (required if only_parse is True).
*/
ValidateSQLCommand: {
/** @default null */