Notion PowerShell Module

Notion Module Logo

Notion - A class-based PowerShell module for interacting with Notion

PowerShell Gallery Version PowerShell Gallery Downloads Platform GitHub Issues

⚠ Work in progress - not all features are implemented yet, if you are missing something, or experience any issues, please open an issue on GitHub.

Notion, is an online knowledge management tool in which you can structure your requirements yourself or be inspired by countless templates and formats. Unfortunately, there was no PowerShell module that offers the full power of the API.

In order to ensure the smoothest possible interaction with the API, the specifications were implemented with PowerShell classes. This means that classes are used in the background for all cmdlets. You can also create your own Notion objects directly using the classes provided.

Prerequisites

Getting started

To get started either:

# PowerShellGet 2.x
Install-Module -Name Notion -Repository PSGallery

# PowerShellGet 3.x
Install-PSResource -Name Notion

# Connect to Notion
$BearerToken = Read-Host -Prompt "Enter your Notion Bearer Token" -AsSecureString
Connect-Notion -BearerToken $BearerToken

Or download it via the Microsoft PowerShell Gallery

Documentation

Documentation is available in the Wiki.

Issues

Please open a github issue here.

Contributing

Contributing

Please check out common DSC Community contributing guidelines.

Running the Tests

If want to know how to run this module’s tests you can look at the Testing Guidelines

Branch Model

The branch model is based on the GitFlow model.

flowchart TD
    B[Dev] --> |Release|A[main]
    C[Features] --> |PreRelease|B
    D[Hotfix] --> |Release|A
    E[Bugfix] --> |PreRelease|B

GitVersion install

    #eventually you need to install the nuget.org source
    #dotnet nuget add source https://api.nuget.org/v3/index.json -n nuget.org

    dotnet tool install --global GitVersion.Tool --version 5.12.0

Manual Build, Import & Connect

    # Clone the repository
    #when running the first time you also need to resolve the dependencies
    ./build.ps1 -Tasks build -ResolveDependency -UseModuleFast
    $version = (dotnet-gitversion.exe /showvariable MajorMinorPatch)
    $ModuleFile = ".\output\module\Notion\$version\Notion.psd1"
    Import-Module $ModuleFile
    # Import-Module Microsoft.PowerShell.PlatyPS -Force
    # New-MarkdownCommandHelp -ModuleInfo (Get-Module Notion) -OutputFolder .\docs -WithModulePage -HelpVersion "$version" -Force
    $BearerToken = Read-Host -Prompt "Enter your Notion Bearer Token" -AsSecureString

    Connect-Notion -BearerToken $BearerToken

Wiki

Welcome to the PowerShell Notion Module Wiki

PowerShell Gallery Version PowerShell Gallery Downloads Platform GitHub Issues

Here you will find all the information you need to use Notion.

Please leave comments, feature requests and bug reports for this module in the issues section of this repository.

Find the FAQs here: FAQs

Installation

# Install via PowerShellGet 2.x
Install-Module -Name Notion -Repository PSGallery

# Install via PowerShellGet 3.x
Install-PSResource Notion -Repository PSGallery

How to start with this module?

Before you start with connecting to your Notion teamspace, you need to create an integration, which is allowed to interact with your space.

Follow this link to get a detailed instructions how to create your Notion integration.

Usage

# Import the module
Import-Module -Name Notion

# List all Cmdlets
Get-Command -Module Notion

# List Cmdlets for blocks
Get-Command -Module Notion -Noun NotionBlock

# Connect to Notion (with your integration/bearer token)
$BearerToken = Read-Host -Prompt "Enter your Bearer token" | ConvertTo-Securestring -AsPlainText
Connect-Notion -BearerToken $BearerToken

Idea behind a class based Notion module

There are several attempts to talk to the Notion API out there, but most of them didn’t take care of the correct syntax of the individual configuration of each block/page/database etc. So we decided to create classes for all available Notion objects presented by the API. (there are some objects which are not available right now - end of 2024 like e.g. template)

The charm of Notion classes are this simple use while creating objects.

[notion_block]::new() # creates an empty block object
[notion_page]::new()  # creates a new page object
[notion_emoji]::new() # creates a new emoji object

However, there is also a New-NotionBlock CmdLet available to create a new block object.

New-NotionBookmarkBlock -URL "https://www.example.com" -Caption "Example Bookmark"
New-NotionCalloutBlock -RichText "This is a callout" -Icon "💡"
New-NotionBreadcrumbBlock #new breadcrumb block

If you receive items from the API, the Notion module will automatically convert it into Notion objects (based on the classes) so that the can be used.

Notion Objects

There are several type of Notion object for different purposes.

Find the classes Documentation here: Classes Documentation

General used verbs for those objects

Nesting of those objects

Nested objects

General used verbs for objects

Each of the objects have got individual CmdLets to deal with.

Object: Block
Add-NotionBlockToPage
Get-NotionBlock
Get-NotionBlockChildren
Object: Database
Add-NotionPageToDatabase
Edit-NotionDatabase
Get-NotionDatabase
Move-NotionDatabaseToArchive
New-NotionDatabase
Remove-NotionDatabase
Restore-NotionDatabase
Object: DatabaseProperties
Add-NotionDatabaseProperty
New-NotionDatabaseProperty
Remove-NotionDatabaseProperty
Object: Page
Get-NotionPage
Get-NotionPageChildren
Move-NotionPageToArchive
New-NotionPage
Remove-NotionPage
Restore-NotionPage
Object: PageProperties
Get-NotionPageProperty
Update-NotionPageProperty
Object: User
Get-NotionUser

Classes and Enums

An easy way to generate new blocks is to instantiate them from predefined classes via [classname]::new(). On the querying side the API returns a naked object with properties. The module automatically turns those answers into proper Notion objects (derived from classes)

The enumerations (enums) are predefined values which are valid for a certain properties. e.g. colors

Enums

Classes

Change log

A full list of changes in each version can be found in the change log.

Changes

Changelog for Notion

The format is based on and uses the types of changes according to Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

Fixed

[0.9.1] - 2025-06-24

Fixed

[0.9.0] - 2025-06-24

Added

[0.8.0] - 2025-06-23

Added

Changed

Fixed

Removed

Deprecated

[0.7.0] - 2025-06-19

Added

Changed

Fixed

[0.6.0] - 2025-06-16

Added

Changed

[0.5.0] - 2025-06-15

Added

Changed

Fixed

[0.3.0] - 2025-05-18

Fixed

[0.2.0] - 2025-05-18

Added

Changed

Removed

Fixed

Security