Deepnote research: our notes on building agents
Get started

Deepnote CLI

Install the Deepnote CLI and use it to run, inspect, convert, sync and publish Deepnote projects from your terminal

The Deepnote CLI is a command-line tool for working with Deepnote projects outside the browser. It reads and writes the open .deepnote file format, runs notebooks locally or in Deepnote Cloud, mirrors a whole workspace to your machine, and publishes apps and Streamlit apps to a project. It is open source and lives in the deepnote/deepnote repository.

Use the CLI when you want to:

  • Run notebooks from scripts, cron jobs, CI or AI coding agents instead of clicking Run in the editor.
  • Keep notebooks in Git and inspect, diff, lint or validate .deepnote files in pull requests.
  • Convert between .ipynb, .py, .qmd and .deepnote.
  • Mirror your Deepnote Cloud workspace locally with deepnote sync and push edits back.
  • Publish an app or a Streamlit app to a project with deepnote publish or deepnote streamlit publish.
  • Give AI coding agents the Deepnote skill. deepnote install-skills gives Claude Code, Codex, Cursor, Gemini CLI and other agents the .deepnote format and CLI reference, so they can write notebooks and check their work with deepnote lint and deepnote run -o llm.

Installation

The CLI is published to npm as @deepnote/cli and runs on Node.js.

npm install -g @deepnote/cli
# or
pnpm add -g @deepnote/cli
# or run it without installing
npx @deepnote/cli --help

If you would rather not install Node.js, pip install deepnote-cli bundles a native binary and exposes the same deepnote command.

Running notebooks locally with deepnote run additionally needs a Python interpreter with the deepnote-toolkit package (pip install "deepnote-toolkit[server]"). The CLI picks up a .venv or venv next to the notebook automatically, or point it at an interpreter with --python.

Authentication

Commands that talk to Deepnote Cloud (run --cloud, schedule, sync, publish, static-site access, streamlit publish, integrations pull) need an API key. Create one in your workspace under Settings & members → Security → API keys (see the Deepnote API docs) and pass it in one of three ways:

MethodExampleWhen to use
Environment variableexport DEEPNOTE_TOKEN="<your-token>"Interactive shells, CI secrets
.env fileDEEPNOTE_TOKEN=<your-token> in .envProject directories you sync or run from
--token flagdeepnote sync ./workspace --token "<your-token>"One-off commands

Prefer the environment variable or a .env file: a token passed as --token ends up in your shell history. Without a token, cloud commands exit with code 2 and print these options.

inspect, cat, lint, validate, convert and run without --cloud work on local files and need no token. deepnote open, and the --open flag on run and convert, upload the file to Deepnote Cloud and open it in your browser, where you sign in; they need no token either.

Commands

CommandWhat it does
deepnote run [path]Run a .deepnote, .ipynb, .py or .qmd file locally, or in Deepnote Cloud with --cloud
deepnote inspect [path]Show project metadata: name, ID, notebooks and block counts
deepnote cat <path>Print block contents, optionally filtered by notebook or block type
deepnote diff <path1> <path2>Compare two .deepnote files and show structural differences
deepnote lint [path]Check for undefined variables, circular dependencies, missing integrations and inputs
deepnote validate <path>Validate a .deepnote file against the schema
deepnote stats <path>Block counts, lines of code and imported modules
deepnote analyze <path>Quality score, structure analysis and suggestions
deepnote dag show|vars|downstream <path>Analyze block dependencies and variable flow
deepnote convert <path>Convert between .ipynb, .py, .qmd and .deepnote
deepnote split <path>Split a multi-notebook .deepnote file into one file per notebook
deepnote open <path>Upload a .deepnote file to Deepnote Cloud and open it in the browser
deepnote schedule <path>Create or update a recurring run in Deepnote Cloud
deepnote sync [dir]Mirror your workspace to a local directory and push notebook edits back
deepnote publish <dir>Publish a local build directory as an app hosted by a project
deepnote static-site accessEnable or disable access to a published app without redeploying
deepnote streamlit publish <entrypoint>Serve a Python file already in the project as a Streamlit app
deepnote integrations pull|add|editManage the local database integrations file used by run
deepnote install-skillsInstall the Deepnote skill for Claude Code, Cursor and other AI coding assistants
deepnote completion <shell>Generate shell completion scripts

Every command accepts --help. The full reference with all options, output schemas and examples is the package README on npm.

Examples

# Run the first .deepnote file in the current directory
deepnote run

# Run a notebook in Deepnote Cloud with an input value
DEEPNOTE_TOKEN=... deepnote run report.deepnote --cloud --input name="Alice"

# Convert a Jupyter notebook to the Deepnote format
deepnote convert notebook.ipynb

# Check a project for issues before committing it
deepnote lint my-project.deepnote

# Schedule a daily run in Deepnote Cloud
deepnote schedule report.deepnote --daily --at 09:00

# Mirror your whole workspace to ./workspace
deepnote sync ./workspace

# Publish a Vite build to a project
deepnote publish ./dist --project-id <project-id>

Scripting and automation

The CLI is built for scripts and AI agents.

  • Exit codes are consistent across commands: 0 success, 1 runtime error, 2 invalid usage (bad arguments, missing file, missing token).
  • Machine-readable output is available with -o json on most commands. -o toon emits TOON, a compact format for LLMs, and -o llm picks the best of the two for each command.
  • -q, --quiet suppresses progress output; errors still go to stderr.
  • Colors follow the NO_COLOR and FORCE_COLOR conventions, and --no-color disables them explicitly.
# Fail a CI step if the notebook has lint errors
deepnote lint my-project.deepnote -o json || exit 1

Related