# Chalk CLI Reference: Notebooks
source: https://docs.chalk.ai/cli#notebooks

Create, edit, and run [notebooks](https://docs.chalk.ai/docs/chalk-notebooks) from the command line — the full loop of adding cells, executing them, and reading their output, so a script or an agent can drive a notebook while you watch it in the dashboard.

## `chalk notebook list`
source: https://docs.chalk.ai/cli?command=notebook_list

```bash
chalk notebook list
```

List notebooks in the current environment, newest first, with the id and dashboard URL for each.

**Flags**

- `--limit <limit>` (int, default `20`)
  Maximum number of notebooks to return.
- `--cursor <cursor>` (string)
  Pagination cursor from a previous `chalk notebook list` response.

**Example**

```
$ chalk notebook list
$ chalk notebook list --limit 50 --json
```

## `chalk notebook create`
source: https://docs.chalk.ai/cli?command=notebook_create

```bash
chalk notebook create
```

Create an empty notebook and print its id and dashboard URL.

Open the URL in a browser to watch the notebook while the CLI edits and runs it.

**Flags**

- `--title <title>` (string)
  Title for the new notebook.
- `--description <description>` (string)
  Description for the new notebook.

**Example**

```
$ chalk notebook create --title "Fraud exploration"
$ chalk notebook create --title "Scratch" --json
```

## `chalk notebook get`
source: https://docs.chalk.ai/cli?command=notebook_get

```bash
chalk notebook get [notebook-id]
```

Read a notebook: its metadata and its cells in order, optionally with each cell's most recent output.

With `--with-results`, an offline query's dataset display is checked once and reported as-is (e.g. `WORKING` with no preview yet) rather than waiting for it to finish. Pass `--wait-offline-query` to poll until it completes instead.

**Arguments**

- `notebook-id` (string)
  The notebook to read.

**Flags**

- `-n, --notebook <notebook>` (string)
  The notebook id. May also be given as the first positional argument.
- `--with-results <with-results>` (bool, default `false`)
  Also include each cell's most recent persisted output.
- `--source <source>` (bool, default `true`)
  Include each cell's source. Pass `--source=false` for a compact listing.
- `--max-output-bytes <max-output-bytes>` (int, default `8000`)
  Maximum bytes of output text to return per cell. Truncation is reported in the output. Use `0` for no limit.
- `--wait-offline-query <wait-offline-query>` (bool, default `false`)
  Poll until any in-progress offline query finishes, instead of reporting its current status immediately.

**Example**

```
$ chalk notebook get <notebook-id>
$ chalk notebook get <notebook-id> --with-results --json
```

## `chalk notebook url`
source: https://docs.chalk.ai/cli?command=notebook_url

```bash
chalk notebook url [notebook-id]
```

Print the dashboard URL for a notebook.

Useful for handing a human a link to watch while a script or agent drives the notebook — edits and run output appear in an open tab as they happen.

**Arguments**

- `notebook-id` (string)
  The notebook to link to.

**Flags**

- `-n, --notebook <notebook>` (string)
  The notebook id. May also be given as the first positional argument.

**Example**

```
$ chalk notebook url <notebook-id>
```

## `chalk notebook delete`
source: https://docs.chalk.ai/cli?command=notebook_delete

```bash
chalk notebook delete [notebook-id]
```

Delete a notebook. Its run history is retained server-side under the usual retention policy.

**Arguments**

- `notebook-id` (string)
  The notebook to delete.

**Flags**

- `-n, --notebook <notebook>` (string)
  The notebook id. May also be given as the first positional argument.

**Example**

```
$ chalk notebook delete <notebook-id>
```

## `chalk notebook cell list`
source: https://docs.chalk.ai/cli?command=notebook_cell_list

```bash
chalk notebook cell list [notebook-id]
```

List a notebook's cells in order, with the index, id, name, kind, and source of each.

**Arguments**

- `notebook-id` (string)
  The notebook to list cells for.

**Flags**

- `-n, --notebook <notebook>` (string)
  The notebook id. May also be given as the first positional argument.

**Example**

```
$ chalk notebook cell list <notebook-id>
```

## `chalk notebook cell add`
source: https://docs.chalk.ai/cli?command=notebook_cell_add

```bash
chalk notebook cell add [notebook-id]
```

Add a cell to a notebook.

With `--run`, the cell is executed immediately and its output is included in the result, which is usually what you want: it collapses add, run, wait, and read into a single call.

**Arguments**

- `notebook-id` (string)
  The notebook to add a cell to.

**Flags**

- `-n, --notebook <notebook>` (string)
  The notebook id. May also be given as the first positional argument.
- `--kind <kind>` (string, default `python`)
  Cell kind: `python`, `sql`, `markdown`, or `text`.
- `-s, --source <source>` (string)
  The cell's source. Use `-` to read it from stdin, which avoids shell quoting for multi-line code.
- `--name <name>` (string)
  Optional cell name. Names appear in the dashboard and can be used to select the cell later.
- `--datasource <datasource>` (string)
  Datasource name for a SQL cell. Use `chalk` for Chalk SQL. New SQL cells default to Chalk SQL; edits preserve the current datasource when omitted.
- `--result-variable <result-variable>` (string)
  Python variable that receives a Python or SQL cell's result. On edit, pass an empty value to clear the binding.
- `--after <after>` (string)
  Insert after this cell (id, name, or index). Defaults to appending at the end.
- `--before <before>` (string)
  Insert before this cell (id, name, or index).
- `--run <run>` (bool, default `false`)
  Run the cell immediately after adding it and include its output in the result.
- `--scope <scope>` (string, default `cell`)
  Cells to include for a single-cell run: `cell`, `upstream`, `downstream`, or `auto`. Multi-cell runs always execute the exact selected set in document order.
- `--max-staleness <duration>` (string)
  Maximum age of cached SQL results. Use `0` to require fresh results. Omit to inherit the configured notebook, environment, and team cache policy.
- `--no-cache <no-cache>` (bool, default `false`)
  Require fresh SQL results. Shorthand for `--max-staleness=0`.
- `--timeout <timeout>` (string, default `5m0s`)
  How long to wait for the run to finish (e.g. `2m`). On timeout the run keeps going server-side and the partial result is returned.
- `--max-output-bytes <max-output-bytes>` (int, default `8000`)
  Maximum bytes of output text to return per cell. Truncation is reported in the output. Use `0` for no limit.

**Example**

```
$ chalk notebook cell add <notebook-id> --kind python --source 'print(1 + 1)' --run

# Multi-line source without shell quoting problems
$ cat model.py | chalk notebook cell add <notebook-id> --source - --run

# Place a cell relative to an existing one
$ chalk notebook cell add <notebook-id> --kind sql --datasource chalk --result-variable rows --source 'select 1' --after 2
```

## `chalk notebook cell edit`
source: https://docs.chalk.ai/cli?command=notebook_cell_edit

```bash
chalk notebook cell edit [notebook-id] [cell]
```

Edit a cell's source or result configuration.

Omitted fields are preserved. Use `--datasource chalk` to select Chalk SQL, and use an empty `--result-variable=` to clear a result binding. The cell keeps its name and position. With `--run`, the edited cell runs immediately and its output is included in the result.

**Arguments**

- `notebook-id` (string)
  The notebook containing the cell.
- `cell` (string)
  The cell to edit: id, name, or 1-based index.

**Flags**

- `-n, --notebook <notebook>` (string)
  The notebook id. May also be given as the first positional argument.
- `-c, --cell <cell>` (string)
  The cell to act on: its id, its name, or its 1-based index. May also be given as the second positional argument.
- `-s, --source <source>` (string)
  The cell's source. Use `-` to read it from stdin, which avoids shell quoting for multi-line code.
- `--datasource <datasource>` (string)
  Datasource name for a SQL cell. Use `chalk` for Chalk SQL. New SQL cells default to Chalk SQL; edits preserve the current datasource when omitted.
- `--result-variable <result-variable>` (string)
  Python variable that receives a Python or SQL cell's result. On edit, pass an empty value to clear the binding.
- `--run <run>` (bool, default `false`)
  Run the cell immediately after adding it and include its output in the result.
- `--scope <scope>` (string, default `cell`)
  Cells to include for a single-cell run: `cell`, `upstream`, `downstream`, or `auto`. Multi-cell runs always execute the exact selected set in document order.
- `--max-staleness <duration>` (string)
  Maximum age of cached SQL results. Use `0` to require fresh results. Omit to inherit the configured notebook, environment, and team cache policy.
- `--no-cache <no-cache>` (bool, default `false`)
  Require fresh SQL results. Shorthand for `--max-staleness=0`.
- `--timeout <timeout>` (string, default `5m0s`)
  How long to wait for the run to finish (e.g. `2m`). On timeout the run keeps going server-side and the partial result is returned.
- `--max-output-bytes <max-output-bytes>` (int, default `8000`)
  Maximum bytes of output text to return per cell. Truncation is reported in the output. Use `0` for no limit.

**Example**

```
$ chalk notebook cell edit <notebook-id> 2 --source 'print(2 + 2)' --run
$ chalk notebook cell edit <notebook-id> --cell <cell-id> --source -
$ chalk notebook cell edit <notebook-id> 2 --datasource chalk --result-variable orders
```

## `chalk notebook cell move`
source: https://docs.chalk.ai/cli?command=notebook_cell_move

```bash
chalk notebook cell move [notebook-id] [cell]
```

Move a cell before or after another cell. Cell order determines run order for whole-notebook runs.

**Arguments**

- `notebook-id` (string)
  The notebook containing the cell.
- `cell` (string)
  The cell to move: id, name, or 1-based index.

**Flags**

- `-n, --notebook <notebook>` (string)
  The notebook id. May also be given as the first positional argument.
- `-c, --cell <cell>` (string)
  The cell to act on: its id, its name, or its 1-based index. May also be given as the second positional argument.
- `--after <after>` (string)
  Insert after this cell (id, name, or index). Defaults to appending at the end.
- `--before <before>` (string)
  Insert before this cell (id, name, or index).

**Example**

```
$ chalk notebook cell move <notebook-id> 3 --before 1
```

## `chalk notebook cell delete`
source: https://docs.chalk.ai/cli?command=notebook_cell_delete

```bash
chalk notebook cell delete [notebook-id] [cell]
```

Delete a cell from a notebook.

**Arguments**

- `notebook-id` (string)
  The notebook containing the cell.
- `cell` (string)
  The cell to delete: id, name, or 1-based index.

**Flags**

- `-n, --notebook <notebook>` (string)
  The notebook id. May also be given as the first positional argument.
- `-c, --cell <cell>` (string)
  The cell to act on: its id, its name, or its 1-based index. May also be given as the second positional argument.

**Example**

```
$ chalk notebook cell delete <notebook-id> 2
```

## `chalk notebook run`
source: https://docs.chalk.ai/cli?command=notebook_run

```bash
chalk notebook run [notebook-id] [cell...]
```

Run one cell, several cells, or the whole notebook, and wait for the output.

Waiting is the default because it is almost always what a caller wants: one command starts the run, follows it, and prints each cell's status and output.

A cell that raises is not treated as a command failure — its traceback is the result you asked for, so it comes back with status ERROR and a zero exit code. Only a failure to start or follow the run is an error. Check `status` in the output (or `--json`) to branch on whether the code actually worked.

If the notebook's kernel is still cold, the run waits for it to come up rather than failing.

**Arguments**

- `notebook-id` (string)
  The notebook to run.
- `cell...` (string)
  Cells to run: ids, names, or 1-based indexes. Omit with --all.

**Flags**

- `-n, --notebook <notebook>` (string)
  The notebook id. May also be given as the first positional argument.
- `-c, --cell <cell>` (string[], default `[]`)
  Cell to run: its id, name, or 1-based index. May be repeated to run an exact set of cells.
- `--all <all>` (bool, default `false`)
  Run every runnable cell in the notebook, in document order.
- `--compute-size <size>` (string)
  Kernel compute size to use. If omitted, use the notebook's saved profile. Changing the size restarts a live kernel.

  Available sizes:

  - xs: 1 vCPU · 2 GiB
  - s: 2 vCPU · 4 GiB
  - m: 4 vCPU · 8 GiB
  - l: 4 vCPU · 16 GiB
  - xl: 4 vCPU · 32 GiB
  - 2xl: 8 vCPU · 64 GiB
  - 4xl: 16 vCPU · 128 GiB
- `-y, --yes <yes>` (bool, default `false`)
  Skip confirmation before restarting a running kernel to change its compute size.
- `--scope <scope>` (string, default `cell`)
  Cells to include for a single-cell run: `cell`, `upstream`, `downstream`, or `auto`. Multi-cell runs always execute the exact selected set in document order.
- `--max-staleness <duration>` (string)
  Maximum age of cached SQL results. Use `0` to require fresh results. Omit to inherit the configured notebook, environment, and team cache policy.
- `--no-cache <no-cache>` (bool, default `false`)
  Require fresh SQL results. Shorthand for `--max-staleness=0`.
- `--no-wait <no-wait>` (bool, default `false`)
  Return as soon as the run starts instead of waiting for it to finish. The run id can be followed later with `chalk notebook results`.
- `--timeout <timeout>` (string, default `5m0s`)
  How long to wait for the run to finish (e.g. `2m`). On timeout the run keeps going server-side and the partial result is returned.
- `--kernel-timeout <kernel-timeout>` (string, default `3m0s`)
  How long to wait for a cold kernel to become ready before running. Set `0` to fail immediately if the kernel is not ready.
- `--max-output-bytes <max-output-bytes>` (int, default `8000`)
  Maximum bytes of output text to return per cell. Truncation is reported in the output. Use `0` for no limit.

**Example**

```
# Run one cell by index and wait
$ chalk notebook run <notebook-id> 1

# Run everything
$ chalk notebook run <notebook-id> --all

# Run an exact set of cells
$ chalk notebook run <notebook-id> 1 3
$ chalk notebook run <notebook-id> --cell "Load data" --cell Train

# Run one cell together with its upstream dependencies, without cached SQL
$ chalk notebook run <notebook-id> Train --scope upstream --no-cache

# Start a long run and come back to it
$ chalk notebook run <notebook-id> --all --no-wait
```

## `chalk notebook interrupt`
source: https://docs.chalk.ai/cli?command=notebook_interrupt

```bash
chalk notebook interrupt [notebook-id]
```

Interrupt a notebook run. Queued cells are canceled and the executing cell is interrupted in the kernel.

**Arguments**

- `notebook-id` (string)
  The notebook whose run should be interrupted.

**Flags**

- `-n, --notebook <notebook>` (string)
  The notebook id. May also be given as the first positional argument.
- `--run <run>` (string)
  The run to interrupt. Defaults to the notebook's most recent run.

**Example**

```
$ chalk notebook interrupt <notebook-id>
```

## `chalk notebook results`
source: https://docs.chalk.ai/cli?command=notebook_results

```bash
chalk notebook results [notebook-id] [cell]
```

Read the most recent persisted output for a notebook's cells.

This reads what is stored, so it works for runs this process did not start — including a run kicked off with `--no-wait`, or one started from the dashboard or by an agent.

An offline query's dataset display is checked once and reported as-is (e.g. `WORKING` with no preview yet), the same way inspecting it yourself would show. Pass `--wait-offline-query` to instead poll until it finishes.

**Arguments**

- `notebook-id` (string)
  The notebook to read results for.
- `cell` (string)
  Optional cell to limit to: id, name, or 1-based index.

**Flags**

- `-n, --notebook <notebook>` (string)
  The notebook id. May also be given as the first positional argument.
- `-c, --cell <cell>` (string)
  The cell to act on: its id, its name, or its 1-based index. May also be given as the second positional argument.
- `--max-output-bytes <max-output-bytes>` (int, default `8000`)
  Maximum bytes of output text to return per cell. Truncation is reported in the output. Use `0` for no limit.
- `--wait-offline-query <wait-offline-query>` (bool, default `false`)
  Poll until any in-progress offline query finishes, instead of reporting its current status immediately.

**Example**

```
$ chalk notebook results <notebook-id>
$ chalk notebook results <notebook-id> 2 --json
$ chalk notebook results <notebook-id> --wait-offline-query
```

## `chalk notebook dependencies`
source: https://docs.chalk.ai/cli?command=notebook_dependencies

```bash
chalk notebook dependencies [notebook-id]
```

List the Python packages installed in a notebook's running kernel.

The package names and versions come from the hosted kernel itself, not this machine's Python environment or the project's dependency files. The command does not execute any cells. The CLI tries the package request immediately; if the kernel is unavailable, it starts the kernel, waits for readiness, and retries.

**Arguments**

- `notebook-id` (string)
  The notebook whose installed packages to list.

**Flags**

- `-n, --notebook <notebook>` (string)
  The notebook id. May also be given as the first positional argument.
- `--kernel-timeout <kernel-timeout>` (string, default `3m0s`)
  How long to wait for the notebook kernel to become ready before listing packages.

**Example**

```
$ chalk notebook dependencies <notebook-id>
$ chalk notebook dependencies <notebook-id> --json
```

## `chalk notebook kernel status`
source: https://docs.chalk.ai/cli?command=notebook_kernel_status

```bash
chalk notebook kernel status [notebook-id]
```

Show the current state of a notebook's kernel, optionally waiting for it to become ready.

**Arguments**

- `notebook-id` (string)
  The notebook whose kernel to inspect.

**Flags**

- `-n, --notebook <notebook>` (string)
  The notebook id. May also be given as the first positional argument.
- `--wait-ready <wait-ready>` (bool, default `false`)
  Wait until the kernel is ready before returning.
- `--wait-timeout <wait-timeout>` (string, default `3m0s`)
  How long to wait when `--wait-ready` is set.

**Example**

```
$ chalk notebook kernel status <notebook-id>
$ chalk notebook kernel status <notebook-id> --wait-ready
```

## `chalk notebook kernel start`
source: https://docs.chalk.ai/cli?command=notebook_kernel_start

```bash
chalk notebook kernel start [notebook-id]
```

Start a notebook's kernel. Useful for warming it before a batch of runs, since the first run otherwise waits for provisioning.

**Arguments**

- `notebook-id` (string)
  The notebook whose kernel to start.

**Flags**

- `-n, --notebook <notebook>` (string)
  The notebook id. May also be given as the first positional argument.
- `--compute-size <size>` (string)
  Kernel compute size to use. If omitted, use the notebook's saved profile. Changing the size restarts a live kernel.

  Available sizes:

  - xs: 1 vCPU · 2 GiB
  - s: 2 vCPU · 4 GiB
  - m: 4 vCPU · 8 GiB
  - l: 4 vCPU · 16 GiB
  - xl: 4 vCPU · 32 GiB
  - 2xl: 8 vCPU · 64 GiB
  - 4xl: 16 vCPU · 128 GiB
- `-y, --yes <yes>` (bool, default `false`)
  Skip confirmation before restarting a running kernel to change its compute size.

**Example**

```
$ chalk notebook kernel start <notebook-id>
$ chalk notebook kernel start <notebook-id> --compute-size m --yes
```

## `chalk notebook kernel stop`
source: https://docs.chalk.ai/cli?command=notebook_kernel_stop

```bash
chalk notebook kernel stop [notebook-id]
```

Stop a notebook's kernel, discarding its in-memory state and freeing its compute.

**Arguments**

- `notebook-id` (string)
  The notebook whose kernel to stop.

**Flags**

- `-n, --notebook <notebook>` (string)
  The notebook id. May also be given as the first positional argument.

**Example**

```
$ chalk notebook kernel stop <notebook-id>
```
