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.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
internal: docs for commands (#7597)
Myles Scolnicke2cf0b4fac47
diff --git a/marimo/_runtime/commands.py b/marimo/_runtime/commands.pyindex 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]]@dataclassclass 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 paramspath_params: dict[str, Any]cookies: dict[str, str]- meta: dict[str, Any]+ meta: dict[str, Any] # User-defined storageuser: 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 FastAPIrequest: 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_tcode: 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] = Noneclass 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 runcell_ids: list[CellId_t]# code to register/run for each cell@@ -188,6 +253,11 @@ class ExecuteCellsCommand(Command):@propertydef 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 filemanagercells: dict[CellId_t, str]# From the list of ALL cells that filemanager knows about,@@ -216,6 +298,11 @@ class SyncGraphCommand(Command):@propertydef 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 FastAPIrequest: Optional[HTTPRequest] = Noneclass 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: strclass 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):@propertydef 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: RequestIdnamespace: strfunction_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: SerializedQueryParamscli_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) CellConfigconfigs: 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 TypedDictconfig: 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: UpdateUIElementCommandauto_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_tclass StopKernelCommand(Command):+ """Stop kernel execution.++ Signals the kernel to stop processing and shut down gracefully.+ Used when closing a notebook or terminating a session.+ """+passclass 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: RequestIddocument: 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 datasetsource_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: RequestIdengine: 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: RequestIdengine: 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: strclass 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: RequestIdquery: 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: RequestIdclass 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: WidgetModelIdmessage: ModelMessagebuffers: Optional[list[str]] = Noneclass RefreshSecretsCommand(Command):+ """Refresh secrets from the secrets store.++ Reloads secrets from the provider without restarting the kernel.+ """+passclass ClearCacheCommand(Command):+ """Clear all cached data.++ Clears all cache contexts, freeing memory and disk space.+ Affects all cells using the @cache decorator.+ """+passclass 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 operationsStopKernelCommand,]+"""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.yamlindex b4aca18315..df078a81d8 100644--- a/packages/openapi/api.yaml+++ b/packages/openapi/api.yaml@@ -559,6 +559,8 @@ components:title: ChatRequesttype: objectClearCacheCommand:+ 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: ClearCacheRequesttype: objectCodeCompletionCommand:+ 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: CopyNotebookRequesttype: objectCreateNotebookCommand:+ 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: DatasourcesConfigtype: objectDebugCellCommand:+ 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: DebugCellRequesttype: objectDeleteCellCommand:+ 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: DisplayConfigtype: objectExecuteCellCommand:+ 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: ExecuteCellCommandtype: objectExecuteCellsCommand:+ 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: ExecuteCellsRequesttype: objectExecuteScratchpadCommand:+ 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: ExecuteScratchpadRequesttype: objectExecuteStaleCellsCommand:+ 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: FunctionCallResultNotificationtype: objectGetCacheInfoCommand:+ 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: GoogleAiConfigtype: objectHTTPRequest:- 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: ImportStarErrortype: objectInstallPackagesCommand:+ 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: InvokeAiToolResponsetype: objectInvokeFunctionCommand:+ 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: LayoutConfigtype: objectListDataSourceConnectionCommand:- 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: ListPackagesResponsetype: objectListSQLTablesCommand:- 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: ListSQLTablesRequesttype: objectListSecretKeysCommand:+ 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: MissingPackageAlertNotificationtype: objectModelMessage:+ 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: PackageOperationResponsetype: objectPreviewDatasetColumnCommand:+ 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: PreviewDatasetColumnRequesttype: objectPreviewSQLTableCommand:- 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: ReconnectedNotificationtype: objectRefreshSecretsCommand:+ 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: RemoveUIElementsNotificationtype: objectRenameNotebookCommand:+ 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: StdinRequesttype: objectStopKernelCommand:+ 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: SuccessResponsetype: objectSyncGraphCommand:+ 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: UpdateCellCodesNotificationtype: objectUpdateCellConfigCommand:+ 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: UpdateCellIdsRequesttype: objectUpdateUIElementCommand:+ 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: UpdateUIElementValuesRequesttype: objectUpdateUserConfigCommand:+ 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: UpdateUserConfigRequesttype: objectUpdateWidgetModelCommand:+ 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: UpdateWidgetModelRequesttype: objectValidateSQLCommand:- 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.tsindex 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 */