> ## Documentation Index
> Fetch the complete documentation index at: https://developers.notion.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ntn CLI commands for custom blocks

> The ntn commands for developing and deploying custom blocks.

<Warning>
  Custom blocks are in private alpha:

  * Do not discuss publicly or share with anyone outside your workspace.
  * Access must be enabled per workspace. Installing the SDK does not grant access.
  * These APIs may experience breaking changes without notice.
</Warning>

## Custom blocks

Use these commands to preview custom blocks, prepare sample data, and insert deployed blocks into Notion. Custom blocks deploy with their worker through `ntn workers deploy`. See the [custom blocks quickstart](/custom-blocks/quickstart) for the full workflow.

| Command | Purpose |
| - | - |
| [`dev`](#dev) | Preview custom blocks locally. |
| [`sample`](#sample) | Save Notion data for local previews. |
| [`make`](#make) | Insert a deployed custom block into a page or block. |

### dev

Run a local dev shell for the custom blocks in a worker:

```zsh theme={null}
ntn workers customblocks dev
```

Run the command from the worker root, or supply the worker's path:

```zsh theme={null}
ntn workers customblocks dev ./my-example-worker --port 3000
```

| Argument or flag | Description |
| - | - |
| `[path]` | Path to the worker directory. Defaults to the current directory. |
| `--port <port>` | Port for the dev shell UI. |
| `--block-base-port <port>` | Base port for the individual block dev servers. |
| `-- <arguments>` | Pass additional arguments directly to the dev shell. |

The dev shell runs through the [`@notionhq/custom-blocks-dev-shell`](https://www.npmjs.com/package/@notionhq/custom-blocks-dev-shell) package. The CLI detects your worker's package manager and starts the package with `npx`, `pnpm dlx`, or `bunx`.

See [previewing before deploy](/custom-blocks/guides/preview) to connect sample data and configure property mappings.

### sample

Save a data source's schema and sample rows as a local JSON file for the dev shell:

```zsh theme={null}
ntn workers customblocks sample "<data-source-id-or-url>" --out data/issues.json
```

The command accepts a data source ID, database ID, or Notion URL. By default, it saves up to 10 rows to `data/<key>.json`. The key comes from the data source's name.

| Argument or flag | Description |
| - | - |
| `<id-or-url>` | Data source ID, database ID, or Notion URL to sample. |
| `--limit <count>` | Maximum number of rows to save, from 1 to 50. Defaults to 10. |
| `--out <file>` | Output file. Defaults to `data/<key>.json`. |
| `--schema-only` | Save the schema without rows. Cannot combine with `--row-only`, `--limit`, `--sort`, `--filter`, or `--filter-file`. |
| `--row-only` | Save rows without changing the schema. Requires an existing sample file. |
| `--sort "<property> [asc\|desc]"` | Sort the sample rows. Defaults to ascending order. Repeat the flag for multiple sorts, in priority order. |
| `--filter <json>` | Filter rows with Notion filter JSON. |
| `--filter-file <path>` | Read Notion filter JSON from a file, or use `-` for standard input. Cannot combine with `--filter`. |
| `--overwrite` | Replace existing content. With `--row-only`, replace the rows and keep the existing schema. |

Restart the dev shell after changing sample files. See [previewing before deploy](/custom-blocks/guides/preview) to connect the sample source to your block.

### make

Insert a deployed custom block into a Notion page or block. Run this command from the deployed worker root:

```zsh theme={null}
ntn workers customblocks make --key custom --target "<page-id-or-url>"
```

| Flag | Description |
| - | - |
| `--key <key>` | Select the deployed block by its declaration key. |
| `--target <id-or-url>` | Destination page or block ID, or its Notion URL. |

If the block declares data sources, configure its bindings in Notion before it renders. See [binding a block to Notion data](/custom-blocks/guides/data-sources).

## Place custom blocks on pages

Use `ntn pages create` with a `<custom-block definition-id="…" />` tag in the page content. See [Place custom blocks with markdown](/custom-blocks/guides/markdown) for a complete example and App definition-key syntax.

## Related commands

These are already documented in the [CLI command reference](/cli/reference/commands) and are the commands you use most when working on a custom block.

| Command | Role |
| :- | :- |
| `ntn workers new [directory] --template <id>` | Scaffold a project. Custom block templates: `custom`, `habit-tracker`, `org-chart`, `whiteboard`. |
| `ntn workers deploy` | Build the block's source and publish it with the worker. |
| `ntn workers capabilities list` | List the worker's deployed capabilities, including custom blocks. |