Repository navigation
Releases: radityajay/notionctl
Releases · radityajay/notionctl
Release list
v1.3.1
v1.3.0
v1.2.0
v1.1.0
v1.0.1
v1.0.0 — Stable Release
🎉 notionctl v1.0.0
Declarative Notion database management is now stable.
Commands
| Command | Description |
|---|---|
notionctl init |
Generate starter config |
notionctl import |
Import existing databases from Notion |
notionctl plan |
Preview changes |
notionctl apply |
Create/update/destroy databases |
notionctl diff |
Detect drift from manual Notion edits |
notionctl sync |
Pull Notion state back into YAML |
notionctl validate |
Validate config offline (CI-friendly) |
Highlights
- 19 property types — 100% Notion API coverage
- Symbolic relations — reference databases by name, not UUID
- Destroy detection — databases removed from YAML are auto-detected and archived
- Drift detection — compare remote Notion vs local config
- Structured errors — user-friendly messages with retry for rate limits (429) and server errors (5xx)
- 4 templates — CRM, inventory, project tracker, bug tracker
- CI/CD ready —
--auto-approveflag,validatecommand, example GitHub Actions workflows
Getting Started
go install github.com/radityajay/notionctl@v1.0.0
export NOTION_TOKEN="secret_..."
notionctl init
notionctl plan
notionctl applyFull Changelog
v0.9.0 — Config Validation Command
What's New
New notionctl validate command — check your config without connecting to Notion.
Usage
$ notionctl validate
✓ notionctl.yaml is valid (3 database(s), 24 total properties)
$ notionctl validate -c templates/bug-tracker.yaml
✓ templates/bug-tracker.yaml is valid (3 database(s), 33 total properties)- No
NOTION_TOKENrequired - Exits 1 on invalid config — CI-friendly
- Validates: syntax, property types, relation references, formula/rollup config
Full Changelog
v0.8.0 — Drift Detection with notionctl diff
What's New
New notionctl diff command — detect when someone edits your Notion databases directly and your config drifts out of sync.
Usage
notionctl diffExample Output
✓ "Projects" — in sync
⚠ "Tasks" — drifted
+ property "NewCol" (checkbox): in config but not in Notion
- property "OldCol" (rich_text): in Notion but not in config
~ property "Priority": options in config but not remote: [Low]
○ "Archive" — not deployed
What It Detects
- Properties added/removed in Notion but not in config
- Property type mismatches
- Config drift: number format, select/multi_select/status options, formula expressions, unique_id prefix
Full Changelog
v0.7.0 — Destroy Databases Removed from Config
What's New
Databases removed from your YAML config are now detected and can be archived from Notion.
Destroy Flow
- Remove a database from
notionctl.yaml notionctl planshows- destroy "DatabaseName"notionctl applyprompts for confirmation per database- Database is archived in Notion (recoverable from trash) and removed from state
CI Support
notionctl apply --auto-approveSkips all confirmation prompts — useful for automated pipelines.
Full Changelog
v0.6.0 — Structured Error Handling with Retry
What's New
User-friendly error messages and automatic retry for transient failures.
Error Handling
| Status | Before | After |
|---|---|---|
| 401 | Raw JSON dump | check that NOTION_TOKEN is set and valid |
| 403 | Raw JSON dump | share the page with your integration |
| 404 | Raw JSON dump | verify the page/database ID exists |
| 429 | Immediate failure | Auto-retry with backoff, then clear message |
| 5xx | Raw JSON dump | Auto-retry, then Notion server error — try again |
Retry Logic
- Exponential backoff: 1s → 2s → 4s
- Max 3 retries for 429 (rate limit) and 5xx (server errors)
- Non-retryable errors (401, 403, 404) fail immediately with actionable hints
For Developers
New APIError type with helper functions:
if notion.IsRateLimit(err) { /* ... */ }
if notion.IsUnauthorized(err) { /* ... */ }
apiErr, ok := notion.IsAPIError(err)