HackMD CLI

Command-line tool for managing HackMD notes and team notes via the HackMD API.

Setup

Install

npm install -g @hackmd/hackmd-cli

Configure Access Token

Create an API token at hackmd.io/settings#api, then configure:

Interactive login (saves to ~/.hackmd/config.json)

hackmd-cli login

Or via environment variable

export HMD_API_ACCESS_TOKEN=YOUR_TOKEN

For HackMD EE instances, also set the API endpoint:

export HMD_API_ENDPOINT_URL=https://your.hackmd-ee.endpoint

Commands

Authentication

hackmd-cli login # Set access token interactively hackmd-cli logout # Clear stored credentials hackmd-cli whoami # Show current user info

Personal Notes

List all notes

hackmd-cli notes

Get specific note

hackmd-cli notes --noteId=<id>

Create note

hackmd-cli notes create --content='# Title' --title='My Note' hackmd-cli notes create --readPermission=owner --writePermission=owner

Create from file/stdin

cat README.md | hackmd-cli notes create

Create with editor

hackmd-cli notes create -e

Update note

hackmd-cli notes update --noteId=<id> --content='# New Content'

Delete note

hackmd-cli notes delete --noteId=<id>

Team Notes

List team notes

hackmd-cli team-notes --teamPath=<team-path>

Create team note

hackmd-cli team-notes create --teamPath=<team-path> --content='# Team Doc'

Update team note

hackmd-cli team-notes update --teamPath=<team-path> --noteId=<id> --content='# Updated'

Delete team note

hackmd-cli team-notes delete --teamPath=<team-path> --noteId=<id>

Teams & History

hackmd-cli teams # List accessible teams hackmd-cli history # List browsing history

Export

hackmd-cli export --noteId=<id> # Export note content to stdout

Permissions

Available permission values:

Permission Type Values

--readPermission

owner , signed_in , guest

--writePermission

owner , signed_in , guest

--commentPermission

disabled , forbidden , owners , signed_in_users , everyone

Output Formats

All list commands support:

--output=json # JSON output --output=yaml # YAML output --output=csv # CSV output (or --csv) --no-header # Hide table headers --no-truncate # Don't truncate long values --columns=id,title # Show specific columns --filter=name=foo # Filter by property --sort=title # Sort by property (prepend '-' for descending) -x, --extended # Show additional columns

Common Workflows

Sync local file to HackMD

Create new note from file

cat doc.md | hackmd-cli notes create --title="My Doc"

Update existing note from file

cat doc.md | hackmd-cli notes update --noteId=<id>

Export note to local file

hackmd-cli export --noteId=<id> > note.md

List notes as JSON for scripting

hackmd-cli notes --output=json | jq '.[] | .id'

Find note by title

hackmd-cli notes --filter=title=README