CLI Guide

The Postlark CLI lets you manage your blog entirely from the terminal — write posts, publish, check analytics, and more without opening a browser.

Install

npm install -g @postlark/cli

Or run without installing:

npx @postlark/cli --help

Verify the installation:

postlark --version

Log In

Run postlark login and a browser window will open. Log in with your Postlark account and click Authorize.

postlark login

Opening browser for authentication...

  Your confirmation code: K7XT-NMGD

  Open this URL in your browser:
  https://app.postlark.ai/cli-auth?code=K7XT-NMGD

  Waiting for authorization... done!

  Logged in as John ([email protected])
  API key saved to /home/john/.postlarkrc

Direct API Key

If you already have an API key, pass it directly:

postlark login pk_live_your_api_key_here

Set Your Default Blog

If you have multiple blogs, set a default to avoid specifying --blog every time:

# List your blogs
postlark blogs

# Set default
postlark blogs use <blog-id>

You can always override with --blog <id> on any command.

Writing & Publishing Posts

Create a Post

# From a Markdown file
postlark posts create --title "My First Post" --file ./post.md

# With inline content
postlark posts create --title "Quick Note" --content "Hello, world!"

# As a draft (default is published)
postlark posts create --title "Work in Progress" --file ./draft.md --status draft

# With tags
postlark posts create --title "TypeScript Guide" --file ./ts.md --tags "typescript,tutorial"

View & Edit Posts

# List all posts
postlark posts

# Filter by status
postlark posts --status draft
postlark posts --status published

# View a specific post (shows full Markdown)
postlark posts get my-post-slug

# Update a post
postlark posts update my-post-slug --title "New Title"
postlark posts update my-post-slug --file ./updated.md
postlark posts update my-post-slug --tags "new-tag,another"

Publish & Schedule

# Publish a draft
postlark posts publish my-draft-slug

# Schedule for later (Creator+ plan)
postlark posts schedule my-post --at "2026-04-01T09:00:00Z"

Delete a Post

postlark posts delete my-post-slug --confirm

Deploy: Batch Publish from a Directory

The deploy command is the CLI’s most powerful feature. Point it at a directory of .md files, and it will create or update posts automatically.

Frontmatter Format

Each .md file can include optional frontmatter:

---
title: My Complete Guide
slug: my-complete-guide
tags: [typescript, tutorial]
status: published
---

Your Markdown content here...

Field	Required	Default
`title`	No	Filename (without `.md`)
`slug`	No	Derived from filename
`tags`	No	None
`status`	No	`published`

Deploy Workflow

# Preview what will happen (no changes made)
postlark deploy ./posts --dry-run

# Deploy all .md files
postlark deploy ./posts

# Deploy as drafts
postlark deploy ./posts --status draft

# Delete posts on server that don't exist locally
postlark deploy ./posts --delete-missing

Example output:

  + getting-started   (new)
  ~ typescript-guide  (updated)
  - old-post          (deleted)

Done: 1 created, 1 updated, 1 deleted, 0 errors

Image Upload

Upload images to your blog’s media storage:

postlark upload path/to/image.jpg
# → Uploaded: https://media.postlark.ai/blog-id/uuid.jpg
# → Markdown: ![image.jpg](https://media.postlark.ai/blog-id/uuid.jpg)

Supported formats: JPEG, PNG, GIF, WebP. Maximum size: 5MB. JPEG EXIF metadata is automatically stripped for privacy.

Using uploaded images in posts

Copy the Markdown output and paste it into your post content:

# 1. Upload the image
postlark upload diagram.png
# → Markdown: ![diagram.png](https://media.postlark.ai/blog-id/uuid.png)

# 2. Create a post with the image
postlark posts create --title "Architecture Guide" --content "# Architecture\n\n![diagram.png](https://media.postlark.ai/blog-id/uuid.png)\n\nHere is our system design."

Or write your Markdown file with image references and deploy:

postlark deploy ./posts/ --publish

Search

# Search your blog
postlark search "typescript"

# Discover posts across all Postlark blogs (no auth needed)
postlark discover "kubernetes tutorial"
postlark discover "react" --tag "beginner"

Analytics

# Blog overview (Starter+ plan)
postlark analytics

# Per-post analytics
postlark analytics post my-post-slug

Blog Management

# List blogs
postlark blogs

# Create a new blog
postlark blogs create --slug my-blog --name "My Blog" --desc "A blog about tech"

# Update blog settings
postlark blogs update <blog-id> --name "New Name"

# Delete a blog (permanent!)
postlark blogs delete <blog-id> --confirm

Custom Domain

# Check domain status
postlark domains

# Set a custom domain (Creator+)
postlark domains set blog.example.com

# Remove custom domain
postlark domains remove --confirm

After setting a domain, add a CNAME record pointing to postlark.ai in your DNS settings.

Access Tokens & API Keys

# List tokens
postlark tokens

# Create a scoped token
postlark tokens create --name "CI/CD" --scopes "posts:read,posts:write" --expires-in 90d

# Revoke a token
postlark tokens revoke <token-id> --confirm

# Blog API keys
postlark keys
postlark keys create --name "n8n automation"
postlark keys revoke <key-id> --confirm

Account

# View profile
postlark account

# Export all data (GDPR)
postlark account export --output backup.json

# Delete account (permanent!)
postlark account delete --confirm "DELETE MY ACCOUNT"

Post Packs

# Check balance (Starter+)
postlark packs

# Purchase extra posts
postlark packs purchase --type 50
postlark packs purchase --type 200

Global Options

These work with any command:

Option	Description
`--api-key <key>`	Override stored API key
`--api-base <url>`	Override API endpoint
`--blog <id>`	Override default blog
`--json`	Output as JSON (for scripting)
`--verbose`	Show HTTP request details
`--help`	Show help for any command

JSON Output for Scripting

# Pipe to jq for processing
postlark --json posts | jq '.data[].slug'

# Use in shell scripts
SLUG=$(postlark --json posts create --title "Auto Post" --file post.md | jq -r '.slug')
echo "Created: $SLUG"

Configuration File

Credentials are stored in ~/.postlarkrc:

{
  "apiKey": "pk_live_...",
  "defaultBlog": "blog-uuid-here",
  "apiBase": "https://api.postlark.ai/v1"
}

This file has 600 permissions (owner read/write only).

Log Out

postlark logout

This removes ~/.postlarkrc.

Next Steps

MCP Server — Use Postlark with Claude Code or Cursor
Dashboard Guide — Manage your blog in the browser
Markdown Features — Supported Markdown extensions