title	CLI reference
description	Command syntax, repository selection, machine output, side effects, and exit codes.

CLI reference

marimo-export plans, prepares, verifies, and manages notebook exports.

marimo-export
  plan
  build
  capture
  inspect
  verify
  observations
    list
    clear
  repository
    status
    prune
  doctor

`plan`

marimo-export plan NOTEBOOK --spec FILE
                   [--repository DIR] [--timeout SECONDS] [--json]

Resolves inferred inputs, normalized states, the default, observations, repository reuse, and missing work. An exact repository match avoids notebook startup. Cold planning executes the initial autorun.

`build`

marimo-export build NOTEBOOK --spec FILE --output DIR
                    [--repository DIR] [--replace]
                    [--timeout SECONDS] [--json | --jsonl]

Prepares missing states, writes the verified export to DIR, and closes the owned notebook process tree. --replace uses native directory exchange where the filesystem supports it and guarded rollback replacement elsewhere. It replaces the complete destination, including files that exist only in the old directory.

`capture`

marimo-export capture SERVER --session ID --spec FILE --output DIR
                      [--repository DIR] [--replace]
                      [--timeout SECONDS] [--json | --jsonl]

Prepares one named live session through the export repository, writes the verified export to DIR, and closes the preparation lease. The server and session remain active. --replace uses the same guarded replacement contract as build.

Live server authentication reads MARIMO_EXPORT_ACCESS_TOKEN and MARIMO_EXPORT_SERVER_TOKEN from the environment.

Plain HTTP is accepted for loopback hosts. Remote servers require HTTPS. Server URLs cannot contain user information, a query string, or a fragment, and the client rejects redirects. MARIMO_EXPORT_ACCESS_TOKEN becomes an Authorization: Bearer credential. MARIMO_EXPORT_SERVER_TOKEN becomes the Marimo-Server-Token header. Explicit Python credentials take precedence over these environment values.

`inspect`

marimo-export inspect NOTEBOOK_OR_SERVER
                      [--session ID]
                      [--timeout SECONDS] [--json]

With a notebook path, executes the initial autorun and inspects one SessionDescription. With a server URL and no session ID, it lists sessions. Add --session ID to inspect one live session.

Human output for a notebook or selected session reports the session ID, notebook filename, document digest, marimo and marimo-export versions, capabilities, and one summary row per definition with its name, kind, Python type, and input eligibility. --json returns the complete SessionDescription, including the session path, implementation digest, cells, input modes, siblings, values, domains, control paths, and input dependencies.

Server inspection reads the live authentication environment variables. The CLI recognizes a server operand by a lowercase http:// or https:// prefix. An uppercase URL scheme is treated as a notebook path before the shared URL validator runs.

`verify`

marimo-export verify EXPORT [--json]

Reads index.json and every declared asset. Human output reports exported states, unique assets, and verified bytes. --json also reports the state-output-pair count as outputs.

`observations list`

marimo-export observations list NOTEBOOK --spec FILE
                                [--repository DIR]
                                [--timeout SECONDS] [--json]

Resolves the notebook plan, then reports its producer identity, inferred inputs, observation revision, and each projected input vector with its fingerprint and revision. Planning can execute the notebook's initial autorun.

`observations clear`

marimo-export observations clear NOTEBOOK --spec FILE
                                 [--repository DIR]
                                 [--timeout SECONDS] [--json]

Resolves the notebook plan, clears its producer observations, and reports the producer identity, prior observation revision, and number removed.

::: danger Producer-wide deletion This command permanently removes the retained canonical vectors and event rows for the plan's producer, including observations created through other specs for that producer. It returns the number of canonical vectors removed. The monotonic producer revision and prepared exports remain. Later successful notebook runs can record new observations through an installed observation ledger. :::

`repository status`

marimo-export repository status [--repository DIR] [--json]

Reports producer, observation, prepared-state, identity, generation, byte, and active-lease counts.

`repository prune`

marimo-export repository prune [--repository DIR] [--dry-run] [--json]

Applies repository retention. --dry-run reports removable prepared states, generations, and bytes. A live prune can also remove producer records and their observation history, which the dry-run result does not report. Active leases protect their artifacts.

Opening the repository attempts maintenance recovery before either mode. When another process holds the maintenance transaction lock, opening continues without that pass. Recovery can create the repository, adjust permissions, quarantine a corrupt catalog, or retire an invalid artifact. The CLI uses the default RepositoryLimits policy.

`doctor`

marimo-export doctor [--repository DIR] [--json]

Reports the effective repository, Python executable and version, marimo-export version, and pinned marimo adapter compatibility. A failed compatibility check returns exit code 4.

Common options

Option	Contract
`--spec FILE`	Strict JSON or YAML ExportSpec
`--repository DIR`	Export repository for one command
`--timeout SECONDS`	Positive finite startup, inactivity, or preparation-reservation timeout, default `30`
`--json`	One terminal JSON success or failure object
`--jsonl`	Progress records followed by one terminal JSON Lines record

Repository precedence is:

--repository DIR
MARIMO_EXPORT_REPOSITORY
the operating system cache directory

marimo-export --version prints the installed command version and exits.

Output contracts

Human results use standard output. Human progress, warnings, and errors use standard error.

JSON success wraps the command-specific result:

{ "ok": true, "result": { "states": 2, "outputs": 2, "assets": 0, "bytes_verified": 0 } }

Most JSON failures use an error envelope:

{ "error": { "code": "...", "message": "..." }, "ok": false }

JSON Lines progress:

{
  "progress": {
    "cache": null,
    "completed": 0,
    "elapsed_seconds": null,
    "kind": "state_started",
    "message": null,
    "state": "weekly",
    "total": 1
  },
  "type": "progress"
}

JSON Lines success:

{ "ok": true, "result": {}, "type": "result" }

JSON Lines failure:

{ "error": { "code": "...", "message": "..." }, "ok": false, "type": "error" }

Progress objects include every ProgressEvent field. Unused fields are null. --json suppresses progress. --json and --jsonl are mutually exclusive. Machine modes write one compact sorted-key object per line to standard output.

The command redacts configured access and server tokens, plus rejected credential-like argument values, from progress, messages, detail keys, and detail values. Rendered failure messages are limited to 2,048 characters. Treat the remaining machine output under the application's normal secret-handling policy.

doctor --json always returns its diagnostic record under result. A failed compatibility check sets ok to false, returns exit code 4, and keeps the individual check result available for automation.

Command result records

Command	Stable `result` content
`plan`	Complete `ExportPlan` record
`build`, `capture`	Complete `ExportResult` record
`inspect NOTEBOOK`	`SessionDescription` record
`inspect SERVER`	`sessions` array with ID, filename, and path
`inspect SERVER --session ID`	`SessionDescription` record
`verify`	State, output, asset, and verified-byte counts
`observations list`	Producer, inputs, revision, and observed vectors
`observations clear`	Producer, prior revision, and removed-vector count
`repository status`	Repository counts, accounted bytes, and active artifact leases
`repository prune`	Retired state, generation, and byte counts
`doctor`	Repository, Python, package, and marimo compatibility facts

Use the Python records and errors reference for planning, result, warning, and error field contracts.

Exit codes

Exit	Meaning
`0`	Success
`1`	Unexpected internal failure
`2`	Arguments or local value shape
`3`	Environment, transport, or live session
`4`	Export planning or marimo compatibility
`5`	State execution or output materialization
`6`	Export or asset integrity
`7`	Filesystem or export repository
`130`	Interrupted
`141`	Closed output pipe

Build and capture provides the complete producer workflow.

Navigation Menu

Uh oh!

CLI reference

`plan`

`build`

`capture`

`inspect`

`verify`

`observations list`

`observations clear`

`repository status`

`repository prune`

`doctor`

Common options

Output contracts

Command result records

Exit codes

Uh oh!

FilesExpand file tree

cli.md

Latest commit

History

cli.md

File metadata and controls

CLI reference

plan

build

capture

inspect

verify

observations list

observations clear

repository status

repository prune

doctor

Common options

Output contracts

Command result records

Exit codes

`plan`

`build`

`capture`

`inspect`

`verify`

`observations list`

`observations clear`

`repository status`

`repository prune`

`doctor`