marimo CLI 完全指南從 edit 到 export 的命令行工具箱【免費(fèi)下載鏈接】marimoA 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.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/ma/marimomarimo 是一個(gè)以純 Python 文件形式存儲、支持響應(yīng)式執(zhí)行與 SQL 查詢的交互式筆記本框架而marimo命令行工具則是驅(qū)動這一切的入口。本文以倉庫內(nèi) docs/cli.md 生成的 CLI 參考文檔為主線結(jié)合 marimo/_cli/cli.py 及其子命令源碼系統(tǒng)梳理marimo全部命令、參數(shù)與底層實(shí)現(xiàn)幫助你從雙擊圖標(biāo)升級為終端驅(qū)動的完整工作流編輯、運(yùn)行、轉(zhuǎn)換、導(dǎo)出、檢查與配置。一、命令總覽與全局選項(xiàng)marimoCLI 基于 Click 構(gòu)建入口定義于 marimo/_cli/cli.py頂層命令組包含以下子命令命令作用marimo edit創(chuàng)建或編輯筆記本啟動可交互的編輯服務(wù)器marimo new創(chuàng)建空白筆記本或用 AI 從提示詞生成筆記本marimo run以只讀應(yīng)用模式運(yùn)行筆記本marimo tutorial打開內(nèi)置教程marimo recover從 JSON 恢復(fù)文件還原筆記本marimo convert將 Jupyter / Markdown / Python 腳本轉(zhuǎn)換為 marimo 筆記本marimo export導(dǎo)出為 HTML、腳本、Markdown、ipynb、PDF、WASM HTMLmarimo config查看與描述配置marimo check靜態(tài)檢查與格式化 marimo 文件marimo development開發(fā)者工具OpenAPI、進(jìn)程管理、預(yù)覽等marimo shell-completion安裝 bash/zsh/fish 自動補(bǔ)全marimo env打印環(huán)境信息所有命令共享四個(gè)全局選項(xiàng)源碼見 marimo/_cli/cli.py-l, --log-level日志級別取DEBUG/INFO/WARN/ERROR/CRITICAL默認(rèn)WARN-q, --quiet抑制標(biāo)準(zhǔn)輸出-y, --yes對所有提示自動回答 yes便于非交互式運(yùn)行-d, --development-mode開發(fā)模式會開啟 DEBUG 日志并啟用服務(wù)器自動重載。此外可通過--version查看版本號-h / --help查看幫助。查看版本會直接輸出純版本號如0.x.x方便腳本解析。二、marimo edit創(chuàng)建與編輯筆記本marimo edit是日常使用頻率最高的命令用法marimo edit # 啟動 marimo 筆記本服務(wù)器 marimo edit notebook.py # 創(chuàng)建或編輯 notebook.py marimo edit . # 以當(dāng)前目錄為工作區(qū)啟動 cat notebook.py | marimo edit # 支持 Unix 管道風(fēng)格從源碼看edit 的實(shí)現(xiàn) 會依次完成從 stdin 讀取內(nèi)容Unix 管道、校驗(yàn)文件名、創(chuàng)建不存在的空文件、檢查模塊正確性、解析沙箱模式、檢查共享內(nèi)存可用性最后調(diào)用start()啟動SessionMode.EDIT模式的服務(wù)器。常用參數(shù)參數(shù)默認(rèn)值說明-p, --port自動分配綁定端口--host127.0.0.1綁定主機(jī)部署到公網(wǎng)時(shí)改為0.0.0.0--headlessFalse不自動打開瀏覽器--watchFalse監(jiān)聽文件變化在其他編輯器中保存后自動重載代碼--base-url服務(wù)器基礎(chǔ)路徑必須以/開頭且不能以/結(jié)尾例如/marimo--proxyNone反向代理地址若與--base-url路徑?jīng)_突會直接報(bào)錯(cuò)校驗(yàn)邏輯見 cli_validators.py--token / --no-token啟用會話式身份認(rèn)證不設(shè)密碼時(shí)自動生成隨機(jī) token--token-passwordNone指定認(rèn)證 token 密碼--token-password-fileNone從文件讀取 token 密碼傳-表示從 stdin 讀取與--token-password互斥--allow-originsNone允許的 CORS 來源可重復(fù)傳入*表示全部--sandbox / --no-sandbox自動在隔離環(huán)境中運(yùn)行依賴通過 PEP 723 內(nèi)聯(lián)元數(shù)據(jù)跟蹤并自動安裝要求安裝 uv--trusted / --untrusted自動--untrusted時(shí)在 Docker 容器中運(yùn)行遠(yuǎn)程托管的筆記本--timeoutNone全局超時(shí)無連接達(dá)到指定分鐘數(shù)后關(guān)閉服務(wù)器浮點(diǎn)數(shù)--session-ttlNoneWebSocket 斷開后等待多少秒關(guān)閉會話None表示不自動關(guān)閉--skew-protection / --no-skew-protection啟用版本錯(cuò)位保護(hù)中間件防止前后端版本不一致引發(fā)問題--skip-update-checkFalse跳過新版本檢查也可用環(huán)境變量MARIMO_SKIP_UPDATE_CHECK1關(guān)閉特殊工作模式從 URL 打開若NAME是 URLmarimo 會先把筆記本下載到臨時(shí)文件再打開編輯目錄傳入目錄會啟動多文件工作區(qū)配合--sandbox時(shí)為每個(gè)筆記本創(chuàng)建獨(dú)立 venv多文件沙箱要求安裝pyzmq否則會提示marimo[sandbox]共享內(nèi)存檢查編輯模式依賴進(jìn)程間共享內(nèi)存若不可用會給出錯(cuò)誤提示如 Docker 中需掛載/dev/shm并建議改用marimo run。三、marimo new新建與 AI 生成筆記本marimo new用于創(chuàng)建筆記本或借助 AI 從提示詞生成marimo new # 創(chuàng)建空白筆記本 marimo new prompt.txt # 從文件中的提示詞生成 marimo new Plot an interactive 3D surface with matplotlib. cat prompt.txt | marimo new # 支持從 stdin 讀取提示詞無提示詞時(shí)啟動EmptyWorkspace的編輯服務(wù)器有提示詞時(shí)實(shí)現(xiàn) 會調(diào)用marimo._ai.text_to_notebook生成筆記本內(nèi)容寫入臨時(shí).py文件并注冊atexit清理支持--port、--host、--headless、--token、--base-url、--sandbox、--timeout等與edit一致的參數(shù)。四、marimo run以只讀應(yīng)用模式運(yùn)行marimo run把筆記本當(dāng)作只讀應(yīng)用發(fā)布用戶無法編輯代碼適合分享與部署marimo run notebook.py marimo run folder another_folder # 多文件 / 畫廊模式 marimo run app.py -- --arg value # 向筆記本傳遞 CLI 參數(shù)關(guān)鍵參數(shù)參數(shù)默認(rèn)值說明--include-codeFalse是否把源碼發(fā)送給客戶端。默認(rèn)不發(fā)送瀏覽器中無法查看代碼--session-ttl120WebSocket 斷開后等待秒數(shù)再關(guān)閉會話--watchFalse監(jiān)聽文件變化并重載應(yīng)用安裝 watchdog 時(shí)用它否則每秒輪詢一次--check / --no-check啟用運(yùn)行前是否做靜態(tài)檢查多文件模式下顯式指定--check會報(bào)錯(cuò)--show-tracebacks / --no-show-tracebacks自動異常時(shí)是否在彈窗中顯示詳細(xì)回溯--execute-opengraph-generatorsFalse對受信任的筆記本執(zhí)行 OpenGraph 元數(shù)據(jù)生成器--redirect-console-to-browserFalse把控制臺日志重定向到瀏覽器控制臺--sandbox自動與edit相同的隔離執(zhí)行語義run支持同時(shí)傳入多個(gè)路徑純文件列表或目錄會進(jìn)入畫廊模式FixedFilesWorkspace單一目錄配合--watch則使用DirectoryWorkspace以便動態(tài)反映文件增刪。多筆記本運(yùn)行同樣需要pyzmq。--之后的所有內(nèi)容會原樣傳給筆記本通過parse_args解析后注入cli_args例如marimo run app.py -- --arg value中--arg value會成為筆記本的參數(shù)。五、marimo tutorial與marimo recover教程marimo tutorial intro marimo tutorial --help # 列出全部教程tutorial接收內(nèi)置教程名稱在tutorial_order中定義把教程模板寫入臨時(shí)文件后以編輯模式打開。恢復(fù)崩潰丟失的筆記本當(dāng)前端與內(nèi)核斷開時(shí)marimo 會把未保存的單元格變更自動保存為 JSON 恢復(fù)文件。recover將該 JSON 還原為.py筆記本源碼并打印到 stdoutmarimo recover notebook_recovery.json recovered_notebook.py實(shí)現(xiàn)上直接調(diào)用codegen.recover見 marimo/_ast/codegen.py。六、marimo convert導(dǎo)入既有筆記本convert支持三種輸入格式實(shí)現(xiàn)見 marimo/_cli/convert/commands.py.ipynbJupyter 筆記本本地或 GitHub 托管轉(zhuǎn)換時(shí)剝離輸出.md/.qmd僅轉(zhuǎn)換帶{python}代碼圍欄的代碼塊.py若已是合法 marimo 筆記本則跳過否則按 py:percent 格式轉(zhuǎn)換需要 jupytext保留頂層注釋與 docstring。marimo convert your_nb.ipynb -o your_nb.py marimo convert your_nb.md -o your_nb.py marimo convert script.py -o your_nb.py不傳-o時(shí)轉(zhuǎn)換結(jié)果打印到 stdout可組合全局選項(xiàng)marimo -q -y convert script.py -o your_nb.py轉(zhuǎn)換后建議marimo edit your_nb.py打開檢查。注意由于 marimo 是響應(yīng)式執(zhí)行模型跨單元格修改變量的代碼如多個(gè)單元格中修改同一個(gè) DataFrame可能需要重構(gòu)。七、marimo export導(dǎo)出與發(fā)布導(dǎo)出命令組由 marimo/_cli/export/commands.py 定義共 8 個(gè)子命令。導(dǎo)出時(shí)可通過--傳遞 CLI 參數(shù)給筆記本用--watch監(jiān)聽變更自動重新導(dǎo)出-f / --force強(qiáng)制覆蓋已存在的輸出文件否則會交互式詢問。HTMLmarimo export html notebook.py -o notebook.html--include-code / --no-include-code默認(rèn)包含是否把代碼嵌入 HTML-o, --output不傳時(shí) HTML 打印到 stdout執(zhí)行全部單元格后生成靜態(tài) HTML是發(fā)布到任意靜態(tài)托管的常用方式。腳本marimo export script notebook.py -o notebook.script.py按拓?fù)湫虬压P記本拍平成單一 Python 腳本。包含頂層async代碼的筆記本無法導(dǎo)出為腳本會拋出UnsupportedAsyncCodeError。Markdownmarimo export md notebook.py -o notebook.md導(dǎo)出為代碼圍欄式 Markdown 文檔。--flavor指定 Markdown 風(fēng)味取值見MarkdownFlavorName省略時(shí)由輸出文件擴(kuò)展名推斷。Jupytermarimo export ipynb notebook.py -o notebook.ipynb--sorttopological默認(rèn)或top-down排序單元格--include-outputs / --no-include-outputs默認(rèn)關(guān)閉運(yùn)行筆記本并把輸出寫入 ipynb需要安裝nbformat。PDFmarimo export pdf notebook.py -o notebook.pdf--include-outputs / --include-inputs控制是否運(yùn)行并包含輸出、是否包含代碼輸入--webpdf / --no-webpdf默認(rèn)用 Chromium 的 WebPDF 導(dǎo)出關(guān)閉時(shí)先嘗試 pandoc TeX失敗再回退 WebPDF--rasterize-outputs默認(rèn)開啟把 marimo 部件 HTML 與 Vega 輸出柵格化為 PNG 回退--raster-scale為柵格截圖縮放因子1.0–4.0默認(rèn) 4.0--raster-server可選static默認(rèn)更快或live輸出依賴實(shí)時(shí) Python 連接時(shí)使用--asslides推薦--as導(dǎo)出預(yù)設(shè)slides生成 reveal.js 幻燈片風(fēng)格 PDF依賴nbformat、nbconvert柵格化還需要playwright缺失時(shí)會提示安裝命令。WASMmarimo export html-wasm notebook.py -o notebook.wasm.html--moderun只讀或edit可編輯必填--show-coderun 模式下是否默認(rèn)顯示代碼--execute / --no-execute執(zhí)行筆記本并內(nèi)嵌輸出作為預(yù)覽與--watch互斥執(zhí)行前還會用MW前綴規(guī)則做 WASM 兼容性 lint--include-cloudflare同時(shí)生成 Cloudflare Worker 配置index.js與wrangler.jsonc便于部署導(dǎo)出產(chǎn)物在瀏覽器中用 Pyodide 運(yùn)行完全自包含但必須通過 HTTP 服務(wù)訪問file://無法運(yùn)行生成目錄中還會寫入.nojekyll文件避免 GitHub Pages 干擾資源解析本地預(yù)覽可用python -m http.server --directory out_dir。八、marimo config配置管理配置命令組marimo/_cli/config/commands.py包含marimo config show # 顯示當(dāng)前生效配置 marimo config describe # 打印全部配置項(xiàng)的文檔show先確保用戶配置存在然后展示兩部分——來自最近pyproject.toml的項(xiàng)目級覆蓋如有與用戶級配置均以高亮 TOML 輸出并標(biāo)注來源路徑describe通過反射遍歷marimo._config.config.MarimoConfig的類型注解與 docstring遞歸打印所有配置選項(xiàng)的類型與說明是編寫配置文件的權(quán)威參考。九、marimo check靜態(tài)檢查與格式化marimo check # 檢查當(dāng)前目錄**/*.py、**/*.md、**/*.qmd marimo check notebook.py --fix # 自動修復(fù) marimo check . --strict # 有警告即以非零退出碼退出 marimo check --format json # 輸出 JSON 診斷結(jié)果 marimo check --select MB,MR001 # 僅啟用指定規(guī)則/前綴 marimo check --ignore MF004,MF007參數(shù)說明實(shí)現(xiàn)見 marimo/_cli/cli.py 的check命令--fix原地修復(fù)文件--unsafe-fixes啟用可能改變代碼行為的修復(fù)如刪除空單元格--strict存在修復(fù)或問題時(shí)返回非零退出碼CI 友好-v / -q是否打印詳細(xì)消息默認(rèn)詳細(xì)JSON 格式下輸出始終走 stdout--ignore-scripts忽略無法識別為 marimo 筆記本的文件--format full | json診斷輸出格式--select/--ignore按規(guī)則碼或前綴如MB、MR001、MF004覆蓋配置逗號分隔。命令結(jié)束后會匯總Updated N files./Found N issues.并依據(jù)錯(cuò)誤或--strict決定退出碼。規(guī)則體系詳見 marimo/_lint 目錄與 docs/guides/lint_rules 文檔。十、其他實(shí)用命令環(huán)境信息marimo env以 JSON 打印系統(tǒng)環(huán)境信息Python 版本、操作系統(tǒng)、依賴狀態(tài)等排查問題時(shí)首選。Shell 自動補(bǔ)全marimo shell-completion根據(jù)$SHELL環(huán)境變量判斷 shell輸出對應(yīng)的補(bǔ)全啟用命令bash 寫入.bashrczsh 寫入.zshrcfish 寫入.config/fish/completions/marimo.fish不支持的 shell 會報(bào)錯(cuò)。開發(fā)者工具marimo development隱藏命令組marimo development openapi打印完整 OpenAPI schema由msgspec與 Starlette 的SchemaGenerator動態(tài)生成見 marimo/_cli/development/commands.pymarimo development ps list/marimo development ps killall列出 / 殺掉本機(jī)所有 marimo 進(jìn)程依賴 psutilmarimo development inline-packages用啟發(fā)式方法從文件 import 推斷 PyPI 包名并執(zhí)行uv add --script內(nèi)聯(lián)到 PEP 723 元數(shù)據(jù)要求 uv標(biāo)準(zhǔn)庫模塊會被過濾marimo development print-routes打印服務(wù)器全部路由marimo development preview file.py --port 8080運(yùn)行筆記本并把輸出渲染為靜態(tài) HTML在本地 HTTP 服務(wù)器上預(yù)覽。十一、非交互式與腳本化使用建議結(jié)合全局選項(xiàng)marimo可以完全融入 CI/CD 與自動化流程# 靜默檢查 嚴(yán)格退出碼 marimo -q check . --strict # 轉(zhuǎn)換 自動確認(rèn)覆蓋 marimo -y convert nb.ipynb -o nb.py # 一鍵導(dǎo)出部署產(chǎn)物 marimo export html-wasm nb.py -o dist/ --mode run --execute -f # 只讀運(yùn)行并指定端口 marimo run --port 8080 --headless --no-token app.py關(guān)鍵約束提醒--token-password-file -會占用 stdin與管道輸入互斥export --watch必須搭配-o指定輸出文件pdf的柵格化選項(xiàng)要求--include-outputsWASM 導(dǎo)出產(chǎn)物必須經(jīng) HTTP 服務(wù)訪問。理解這些邊界就能把marimo的編輯、運(yùn)行、轉(zhuǎn)換、檢查、導(dǎo)出能力串聯(lián)成一條完整的自動化流水線?！久赓M(fèi)下載鏈接】marimoA 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.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/ma/marimo創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考