https://github.com/nitaiaharoni1/notion-cli
A powerful command-line interface for Notion built with pure bash. No dependencies - just bash, curl, and python3. Supports all major Notion API endpoints (API version 2025-09-03).
https://github.com/nitaiaharoni1/notion-cli
api automation bash cli command-line notion notion-api productivity
Last synced: 3 months ago
JSON representation
A powerful command-line interface for Notion built with pure bash. No dependencies - just bash, curl, and python3. Supports all major Notion API endpoints (API version 2025-09-03).
- Host: GitHub
- URL: https://github.com/nitaiaharoni1/notion-cli
- Owner: nitaiaharoni1
- License: mit
- Created: 2025-12-22T08:03:56.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-12-22T14:01:01.000Z (6 months ago)
- Last Synced: 2025-12-23T20:28:08.937Z (6 months ago)
- Topics: api, automation, bash, cli, command-line, notion, notion-api, productivity
- Language: Shell
- Size: 30.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Notion CLI
A powerful, lightweight command-line interface for Notion built with pure bash. No Node.js or Python dependencies required - just bash, curl, and python3.
**API Version:** 2025-09-03 (latest as of December 2025)
## Features
- 🔍 **Search** pages and databases
- 📄 **Create and manage pages** (create, update, archive, restore, move)
- 🗄️ **Database operations** (list, query, create, update)
- 📊 **Data source operations** (new in API 2025-09-03)
- 🧱 **Block operations** (get, create, update, delete blocks)
- 💬 **Comments** (create and list comments)
- 👥 **User management** (list workspace users)
- 🔐 **Secure token storage** (uses `~/.notion_token` with proper permissions)
## Installation
### Quick Install (One Command)
```bash
curl -fsSL https://raw.githubusercontent.com/nitaiaharoni1/notion-cli/main/install.sh | bash
```
### Using Homebrew
```bash
brew tap nitaiaharoni1/notion-cli
brew install notion-cli
```
After installation, add to your shell config (`~/.zshrc` or `~/.bashrc`):
```bash
source $(brew --prefix)/bin/notion
```
Then reload your shell: `source ~/.zshrc`
### Manual Installation
1. Download the script:
```bash
curl -o notion-cli.sh https://raw.githubusercontent.com/nitaiaharoni1/notion-cli/main/notion-cli.sh
```
2. Make it executable:
```bash
chmod +x notion-cli.sh
```
3. Move to a directory in your PATH:
```bash
mkdir -p ~/.local/bin
mv notion-cli.sh ~/.local/bin/notion-cli.sh
```
4. Add to your shell configuration (`~/.zshrc` or `~/.bashrc`):
```bash
export PATH="$HOME/.local/bin:$PATH"
source ~/.local/bin/notion-cli.sh
```
5. Reload your shell:
```bash
source ~/.zshrc # or source ~/.bashrc
```
## Setup
### Quick Setup (Recommended)
After installation, run:
```bash
notion init
```
This will guide you through:
- Getting a Notion integration token
- Storing it securely
- Testing the connection
### Manual Setup
### 1. Get a Notion Integration Token
1. Go to [Notion Integrations](https://www.notion.so/my-integrations)
2. Click **"+ New integration"**
3. Give it a name (e.g., "Notion CLI")
4. Select your workspace
5. Copy the **Internal Integration Token** (starts with `secret_`)
6. **Important:** Share the pages/databases you want to access with this integration in Notion
### 2. Store Your Token Securely
```bash
echo 'secret_your-token-here' > ~/.notion_token
chmod 600 ~/.notion_token
```
## Usage
### Basic Commands
```bash
# Show your integration info
notion me
# Search for pages/databases
notion search 'My Page'
# Get page details
notion get 'page-id-here'
# Create a new page
notion create 'parent-page-id' 'New Page Title'
# Update page property
notion update 'page-id' 'Status' 'Done'
# Update page title
notion update-title 'page-id' 'New Title'
# Archive a page
notion archive 'page-id'
# Restore an archived page
notion restore 'page-id'
# Move page to new parent
notion move 'page-id' 'new-parent-id'
# Get page property value
notion get-property 'page-id' 'property-id'
```
### Database Operations
```bash
# List all databases
notion databases
# Get database details
notion get-database 'database-id'
# Create a new database
notion create-database 'parent-page-id' 'My Database'
# Update database title
notion update-database 'database-id' 'New Title'
# Query a database
notion query 'database-id' 20
```
### Data Sources (API 2025-09-03+)
```bash
# Get data source details
notion get-datasource 'ds-id'
# Query a data source
notion query-datasource 'ds-id' 20
# Create a data source
notion create-datasource 'database-id' 'New Data Source'
# Update data source
notion update-datasource 'ds-id' 'New Title'
# List data source templates
notion datasource-templates 'ds-id'
```
### Block Operations
```bash
# Get page blocks/children
notion blocks 'page-id' 20
# Get a single block
notion get-block 'block-id'
# Append a block to a page
notion append-block 'page-id' 'paragraph' 'This is new content'
# Update block content
notion update-block 'block-id' 'Updated content'
# Delete (archive) a block
notion delete-block 'block-id'
```
### Comments
```bash
# Add a comment to a page
notion comment 'page-id' 'This is my comment'
# List comments on a page
notion comments 'page-id'
# Get a specific comment
notion get-comment 'comment-id'
```
### Users
```bash
# List workspace users
notion users
# Get specific user details
notion get-user 'user-id'
```
## Examples
### Quick Note Creation
```bash
# First, find a parent page ID
notion search 'My Notes'
# Then create a child page
notion create 'parent-page-id' 'Quick Note'
```
### Database Query
```bash
# List databases to find the one you want
notion databases
# Query the database
notion query 'database-id' 50
```
### Add Content to a Page
```bash
# Add a paragraph
notion append-block 'page-id' 'paragraph' 'Hello World!'
# Add a heading
notion append-block 'page-id' 'heading_1' 'My Heading'
# Add a bullet point
notion append-block 'page-id' 'bulleted_list_item' 'First bullet'
```
### Update Page Status
```bash
# Update a property (e.g., Status field)
notion update 'page-id' 'Status' 'In Progress'
```
## All Commands Reference
| Category | Command | Description |
|----------|---------|-------------|
| **Setup** | `init` | Initial setup and token configuration |
| **Setup** | `me` | Show your integration user information |
| **Pages** | `search` | Search pages and databases |
| **Pages** | `get` | Get page details |
| **Pages** | `create` | Create a new page |
| **Pages** | `update` | Update page property |
| **Pages** | `update-title` | Update page title |
| **Pages** | `archive` | Archive a page |
| **Pages** | `restore` | Restore an archived page |
| **Pages** | `move` | Move page to new parent |
| **Pages** | `get-property` | Get page property value |
| **Databases** | `databases` | List all databases |
| **Databases** | `get-database` | Get database details |
| **Databases** | `create-database` | Create a new database |
| **Databases** | `update-database` | Update database title |
| **Databases** | `query` | Query a database |
| **Data Sources** | `get-datasource` | Get data source details |
| **Data Sources** | `query-datasource` | Query a data source |
| **Data Sources** | `create-datasource` | Create a data source |
| **Data Sources** | `update-datasource` | Update data source |
| **Data Sources** | `datasource-templates` | List data source templates |
| **Blocks** | `blocks` | Get page blocks/children |
| **Blocks** | `get-block` | Get a single block |
| **Blocks** | `append-block` | Append block children |
| **Blocks** | `update-block` | Update block content |
| **Blocks** | `delete-block` | Delete (archive) a block |
| **Comments** | `comment` | Create a comment on a page |
| **Comments** | `comments` | List comments on a page |
| **Comments** | `get-comment` | Get a specific comment |
| **Users** | `users` | List workspace users |
| **Users** | `get-user` | Get specific user details |
## Requirements
- Bash 4.0+
- curl
- python3
- macOS or Linux
## Troubleshooting
### "unauthorized" or "invalid" errors
- Make sure your token is correct and starts with `secret_`
- Ensure you've shared the pages/databases with your integration in Notion
- Check that your integration has the necessary capabilities
### "object_not_found" errors
- Verify the page/database ID is correct
- Make sure the page/database is shared with your integration
- Check that you're using the correct ID format (with or without dashes)
### Token not found
- Ensure `~/.notion_token` exists and has correct permissions (`chmod 600`)
- Or set `NOTION_TOKEN` environment variable
- Run `notion init` to set up your token
## API Version
This CLI uses the Notion API version **2025-09-03** (latest as of December 2025). API versions are only updated for backwards-incompatible changes. Check https://developers.notion.com/reference/versioning for the latest version.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Author
Created by [Nitai Aharoni](https://github.com/nitaiaharoni)
## Support
For issues and feature requests, please use the [GitHub Issues](https://github.com/nitaiaharoni/notion-cli/issues) page.