Introducing hn: The Git-Like CLI for Managing Your Hashnode Blog

Writing a blog should feel like writing code—not filling out forms in a web UI.

hn is a command-line tool that lets you manage your Hashnode blog directly from a Git repository, using familiar developer workflows: staging, planning, snapshots, and explicit publishing. It’s designed to be safe, predictable, and observable, even if your blog grows to dozens or hundreds of posts.

Official GitHub repository: adil-adysh/hashnode-cli

This post walks through all major operations of hn, why they matter, and how they fit into a clear, developer-friendly workflow.

---

Installation

hn can be installed on Windows using Scoop:

# List existing Scoop buckets
scoop bucket list

# Add the hashnode-cli bucket if not present
scoop bucket add hashnode-cli https://github.com/adil-adysh/scoop-bucket.git

# Install hn
scoop install hn

# If already installed, update to the latest version
scoop update hn
`

Once installed, verify:

hn --help

This lists all available commands and flags.

---

Blogging as a State Machine

At its core, hn treats blogging like version control:

• Local Markdown files → where you create content
• Staging area → what you intend to publish
• Ledger (hashnode.sum) → what exists on Hashnode
• Plan & Apply → preview changes before executing

Nothing is published implicitly. Every action is intentional.

---

hn init: Setup Your Repository

Before using hn, initialize your repo:

hn init

This will:

1. Prompt for your Hashnode Personal Access Token (or read it from HASHNODE_TOKEN)
2. Verify the token via the Hashnode API
3. Let you select a publication (one blog per repo)
4. Create a .hashnode directory and blog.yml for CLI-managed state

⚠️ Do not edit files under .hashnode/ manually; they are CLI-owned.

---

Local-First Markdown Workflow

hn works directly with your filesystem:

• Write posts as plain .md files
• Organize them however you like:

2025/07/my-first-post.md
ai/rag-design.md

• Front matter is required for metadata (title, slug, tags, image URL, meta description)
• No hidden metadata inside content
• Repository stays readable and future-proof

Tip: Images are supported via front matter—just generate the URL and add it to the YAML.

---

Staging Posts (hn stage)

Before publishing, posts must be staged:

hn stage ai/rag-design.md

Staging:

• Captures your intent
• Creates a snapshot in .hashnode/snapshots/
• Does not publish

Review staged posts:

hn stage list

Everything is visible, reversible, and safe.

---

Planning Changes (hn plan)

Preview exactly what will happen:

hn plan

The plan shows:

• 🟢 New posts
• 🟡 Updates
• 🔴 Deletes

Example:

🟢 CREATIONS
  ai/rag-design.md
  └─ Reason: New draft (Local-only)

🟡 UPDATES
  2025/07/my-first-post.md
  └─ Reason: Content changed (Snapshot updated)

No side effects. No surprises.

---

Updating Posts

Editing workflow:

1. Edit the Markdown file:

notepad ai/rag-design.md

2. Restage modified file:

hn stage ai/rag-design.md

3. Preview plan:

hn plan

4. Apply changes:

hn apply

---

Deleting Posts

Deletion is explicit:

hn delete ai/rag-design.md
hn apply --yes

• --yes is required to confirm deletes
• Local removal does not affect remote unless staged for deletion
• Prevents accidental data loss

---

Import Existing Posts (hn import)

Sync your local repo with Hashnode:

hn import

• Fetches posts from Hashnode
• Writes them as Markdown files
• Updates hashnode.sum

Safe to run repeatedly; won’t overwrite staged changes.

---

Applying Changes (hn apply)

After staging and planning, apply changes:

hn apply

• Creates new posts
• Updates modified posts
• Deletes staged posts (with --yes)

All operations are logged and visible for traceability.

---

Garbage Collection (hn gc)

Clean up unreferenced snapshots:

hn gc

Keeps your .hashnode/snapshots/ directory tidy and avoids unnecessary storage.

---

Available Commands Overview

hn [command]

Available Commands:
  apply       Apply planned changes
  delete      Mark a file for remote deletion
  gc          Garbage collect unreferenced snapshots
  import      Import posts from Hashnode and sync ledger
  init        Setup hashnode-cli with your account
  plan        Show planned changes
  stage       Manage staging area
  unstage     Remove a file from the stage
  completion  Generate shell autocompletion
  help        Help about any command

Series management is not supported at this time.

---

Final Thoughts

hn brings a Git-like workflow to blogging:

• Edit → Stage → Plan → Apply → Delete
• Explicit intent, predictable updates, and traceable history
• Front matter keeps metadata clear, snapshots protect intent, ledger tracks reality

By treating your blog as a version-controlled system, you stay in Markdown, Git, and full control, without relying on a web UI.

Official GitHub repository: adil-adysh/hashnode-cli