pull

Overview

The pull command generates or updates the configured TypeScript schema from the databases registered in your NotCMS workspace.

npx notcms pull

init already performs the first pull. Run this standalone command after a database or its properties change.

What it does

Loads NOTCMS_SECRET_KEY and NOTCMS_WORKSPACE_ID
Fetches the current workspace schema from NotCMS
Generates the configured schema module and its nc client
Prints a query for the first database

Options

Option	Description	Default
`-e, --env <PATH>`	Comma-separated environment file paths	`.env,.env.local,.dev.vars`
`--check`	Check whether the schema is current without writing	`false`

--check exits with code 1 when the generated file is missing or out of date, which makes it suitable for CI/CD.

Examples

Update the schema

npx notcms pull

Load credentials from a custom env file

npx notcms --env .env.development pull

Check without writing

npx notcms pull --check

Generated schema

The command generates both the typed schema and a ready-to-use client:

import { Client } from "notcms";
import type { Schema } from "notcms";

export const schema = {
  blog: {
    id: "abc123...",
    properties: {
      title: "title",
      content: "rich_text",
      published: "checkbox",
      publishDate: "date",
      author: "relation",
      tags: "multi_select",
    },
    options: { tags: ["AI", "Web"] },
  },
} as const satisfies Schema;

export const nc = new Client({ schema });

You can add a package script for later updates:

{
  "scripts": {
    "schema:pull": "notcms pull"
  }
}

Schema change summary

A normal pull compares the previous generated schema and reports added or removed databases, changed database IDs, and added, removed, or changed property types. Missing or unsupported manually edited schemas are skipped for comparison and are never executed. --check never writes the file. It omits the summary when the file is current and prints semantic changes when it is stale. Stale pull --check also prints the semantic summary without writing. The first pull and an unsupported previous schema file have distinct messages. Comparison never executes the local module.

Choice types

The CLI automatically requests choice metadata with ?include=options. Older CLIs keep receiving schemas without options, so their generated modules remain compatible with older SDKs. The optional per-database options field contains names for select, status, and multi_select properties. Generated schemas use as const satisfies Schema, so a select or status with options: { language: ["en", "ja"] } becomes "en" | "ja" | null. A multi-select becomes ("en" | "ja")[] | null. These choices also constrain where operands. A known empty option list yields null for select/status and never[] | null for multi-select. Older schemas without options retain string | null or string[] | null. The API omits options until metadata has been fetched; normal database sync or the service backfill populates it. After changing options in Notion, sync the database and run notcms pull again. Pull reports added and removed choices, including metadata becoming available. Types describe the pulled snapshot; the SDK does not coerce or discard an unknown runtime value. Check schemas in CI

Getting Started

Usage

CLI Commands

Examples

Overview

What it does

Options

Examples

Update the schema

Load credentials from a custom env file

Check without writing

Generated schema

Schema change summary

Choice types

​Overview

​What it does

​Options

​Examples

​Update the schema

​Load credentials from a custom env file

​Check without writing

​Generated schema

​Schema change summary

​Choice types

Overview

What it does

Options

Examples

Update the schema

Load credentials from a custom env file

Check without writing

Generated schema

Schema change summary

Choice types