# Hackmd CLI > HackMD command-line interface for managing personal/team notes and folders. Use this skill when users want to create, read, update, delete, reorder, or export HackMD notes and folders via CLI, manage team content, list teams, view browsing history, or automate HackMD workflows. Use when this capability is needed. - Skill: `tomevault-io/hackmd-cli` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/hackmd-cli` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/hackmd-cli/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/hackmd-cli --- # HackMD CLI Command-line tool for managing HackMD notes, team notes, personal folders, and team folders via the HackMD API. ## Setup ### Install ```bash npm install -g @hackmd/hackmd-cli ``` ### Configure Access Token Create an API token at [hackmd.io/settings#api](https://hackmd.io/settings#api), then configure: ```bash # 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: ```bash export HMD_API_ENDPOINT_URL=https://your.hackmd-ee.endpoint ``` ## Commands ### Authentication ```bash hackmd-cli login # Set access token interactively hackmd-cli logout # Clear stored credentials hackmd-cli whoami # Show current user info ``` ### Personal Notes ```bash # List all notes hackmd-cli notes # Get specific note hackmd-cli notes --noteId= # Create note hackmd-cli notes create --content='# Title' --title='My Note' hackmd-cli notes create --readPermission=owner --writePermission=owner # Create note inside a folder hackmd-cli notes create --parentFolderId= --content='# Title' # 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= --content='# New Content' # Move note into a folder hackmd-cli notes update --noteId= --parentFolderId= # Delete note hackmd-cli notes delete --noteId= ``` ### Team Notes ```bash # List team notes hackmd-cli team-notes --teamPath= # Create team note hackmd-cli team-notes create --teamPath= --content='# Team Doc' # Create team note inside a folder hackmd-cli team-notes create --teamPath= --parentFolderId= --content='# Team Doc' # Update team note hackmd-cli team-notes update --teamPath= --noteId= --content='# Updated' # Move team note into a folder hackmd-cli team-notes update --teamPath= --noteId= --parentFolderId= # Delete team note hackmd-cli team-notes delete --teamPath= --noteId= ``` ### Personal Folders ```bash # List all folders hackmd-cli folders # Get specific folder hackmd-cli folders --folderId= # Create folder hackmd-cli folders create --name='Docs' # Create nested folder hackmd-cli folders create --name='Docs' --parentFolderId= # Create folder with metadata hackmd-cli folders create --name='Docs' --description='Project docs' --icon=1F600 --color='#4F46E5' # Update folder hackmd-cli folders update --folderId= --name='Updated Docs' # Delete folder hackmd-cli folders delete --folderId= # Get / update folder order hackmd-cli folders order hackmd-cli folders order --order='{"root":["folder-id-1","folder-id-2"]}' ``` ### Team Folders ```bash # List all team folders hackmd-cli team-folders --teamPath= # Get specific team folder hackmd-cli team-folders --teamPath= --folderId= # Create team folder hackmd-cli team-folders create --teamPath= --name='Team Docs' # Create nested team folder hackmd-cli team-folders create --teamPath= --name='Team Docs' --parentFolderId= # Create team folder with metadata hackmd-cli team-folders create --teamPath= --name='Team Docs' --description='Project docs' --icon=1F600 --color='#4F46E5' # Update team folder hackmd-cli team-folders update --teamPath= --folderId= --name='Updated Team Docs' # Delete team folder hackmd-cli team-folders delete --teamPath= --folderId= # Get / update team folder order hackmd-cli team-folders order --teamPath= hackmd-cli team-folders order --teamPath= --order='{"root":["folder-id-1","folder-id-2"]}' ``` ### Teams & History ```bash hackmd-cli teams # List accessible teams hackmd-cli history # List browsing history ``` ### Export ```bash hackmd-cli export --noteId= # 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` | ## Folder Flags ```bash --parentFolderId= # Put note/folder inside another folder --icon=1F600 # Emoji unified codepoint string --color='#4F46E5' # Hex color string --order='{"root":["id1","id2"]}' # Folder ordering JSON ``` ## Output Formats All list commands support: ```bash --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 --columns=id,name,color --filter=name=foo # Filter by property --sort=title # Sort by property (prepend '-' for descending) --sort=name -x, --extended # Show additional columns ``` ## Common Workflows ### Sync local file to HackMD ```bash # Create new note from file and verify cat doc.md | hackmd-cli notes create --title="My Doc" # Confirm creation by retrieving the note hackmd-cli notes --filter=title="My Doc" # Update existing note from file and verify cat doc.md | hackmd-cli notes update --noteId= hackmd-cli export --noteId= | head -5 ``` ### Create a folder and put a note inside it ```bash hackmd-cli folders create --name='Docs' hackmd-cli notes create --parentFolderId= --title='My Note' ``` ### Create a nested folder ```bash hackmd-cli folders create --name='Parent' hackmd-cli folders create --name='Child' --parentFolderId= ``` ### Move an existing note into a folder ```bash hackmd-cli notes update --noteId= --parentFolderId= ``` ### Organize team docs in team folders ```bash hackmd-cli team-folders create --teamPath= --name='Team Docs' hackmd-cli team-notes create --teamPath= --parentFolderId= --content='# Team Note' ``` ### Export note to local file ```bash hackmd-cli export --noteId= > note.md ``` ### List notes as JSON for scripting ```bash hackmd-cli notes --output=json | jq '.[] | .id' ``` ### Find note by title ```bash hackmd-cli notes --filter=title=README ``` ## Error Handling Common errors and fixes: | Error | Cause | Fix | |-------|-------|-----| | `Unauthorized` | Invalid or expired token | Re-run `hackmd-cli login` or update `HMD_API_ACCESS_TOKEN` | | `Not Found` | Wrong `noteId` or `teamPath` | Verify the ID with `hackmd-cli notes` or `hackmd-cli teams` | | `Forbidden` | Insufficient permissions | Check note permissions with `hackmd-cli notes --noteId= -x` | --- > Source: [hackmdio/hackmd-cli](https://github.com/hackmdio/hackmd-cli) — distributed by [TomeVault](https://tomevault.io).