Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .github/workflows/config-test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,9 @@ jobs:
- name: Install dependencies
run: pnpm install --frozen-lockfile

- name: Build CLI for localhost integration tests
run: pnpm run build

- name: Run tests
run: pnpm run test

169 changes: 148 additions & 21 deletions README.md

Large diffs are not rendered by default.

Binary file modified hackmd-cli.skill
Binary file not shown.
41 changes: 37 additions & 4 deletions hackmd-cli/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: hackmd-cli
description: 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.
description: HackMD command-line interface for managing notes, folders, and other v1 API operations. Use for HackMD content, team workflows, exports, or API automation.
---

# HackMD CLI
Expand Down Expand Up @@ -35,6 +35,20 @@ export HMD_API_ENDPOINT_URL=https://your.hackmd-ee.endpoint

## Commands

### Other API operations

Prefer the focused `notes`, `folders`, and other commands when available. For other operations, find the operation ID and parameters, then call it:

```bash
hackmd-cli api operations
hackmd-cli api describe GetTeamNote
hackmd-cli api call GetTeamNote --path teampath=docs --path noteId=abc
hackmd-cli api call CreateNote --body @note.json
hackmd-cli api call UploadNoteImage --path noteId=abc --file image=@photo.png
```

Repeat `--path key=value`, `--query key=value`, or `--header 'Name: value'` as needed. `--body` accepts JSON text, `@file`, or `-` for stdin. `--file image=@path` is for multipart upload; use `--mime` if the extension is unknown. `--include` shows HTTP status and headers. The list comes from the API client bundled with the CLI; older EE servers may not support every operation. Generic writes are not retried automatically. Do not run writes or deletes without the user's authorization.

### Authentication

```bash
Expand All @@ -53,7 +67,7 @@ hackmd-cli notes
hackmd-cli notes --noteId=<id>

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

# Create note inside a folder
Expand All @@ -68,9 +82,12 @@ hackmd-cli notes create -e
# Update note
hackmd-cli notes update --noteId=<id> --content='# New Content'
hackmd-cli notes update --noteId=<id> --title='New title'
hackmd-cli notes update --noteId=<id> --description='New summary'
hackmd-cli notes update --noteId=<id> --clear=description

# Move note into a folder
hackmd-cli notes update --noteId=<id> --parentFolderId=<folder-id>
hackmd-cli notes update --noteId=<id> --root

# Delete note
hackmd-cli notes delete --noteId=<id>
Expand All @@ -82,18 +99,24 @@ hackmd-cli notes delete --noteId=<id>
# List team notes
hackmd-cli team-notes --teamPath=<team-path>

# Get a specific team note
hackmd-cli team-notes --teamPath=<team-path> --noteId=<id>

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

# Create team note inside a folder
hackmd-cli team-notes create --teamPath=<team-path> --parentFolderId=<folder-id> --content='# Team Doc'

# Update team note
hackmd-cli team-notes update --teamPath=<team-path> --noteId=<id> --content='# Updated'
hackmd-cli team-notes update --teamPath=<team-path> --noteId=<id> --title='New title'
hackmd-cli team-notes update --teamPath=<team-path> --noteId=<id> --description='New summary'
hackmd-cli team-notes update --teamPath=<team-path> --noteId=<id> --clear=description

# Move team note into a folder
hackmd-cli team-notes update --teamPath=<team-path> --noteId=<id> --parentFolderId=<folder-id>
hackmd-cli team-notes update --teamPath=<team-path> --noteId=<id> --root

# Delete team note
hackmd-cli team-notes delete --teamPath=<team-path> --noteId=<id>
Expand All @@ -119,6 +142,8 @@ hackmd-cli folders create --name='Docs' --description='Project docs' --icon=1F60

# Update folder
hackmd-cli folders update --folderId=<id> --name='Updated Docs'
hackmd-cli folders update --folderId=<id> --root
hackmd-cli folders update --folderId=<id> --clear=description --clear=icon --clear=color

# Delete folder
hackmd-cli folders delete --folderId=<id>
Expand Down Expand Up @@ -148,6 +173,8 @@ hackmd-cli team-folders create --teamPath=<team-path> --name='Team Docs' --descr

# Update team folder
hackmd-cli team-folders update --teamPath=<team-path> --folderId=<id> --name='Updated Team Docs'
hackmd-cli team-folders update --teamPath=<team-path> --folderId=<id> --root
hackmd-cli team-folders update --teamPath=<team-path> --folderId=<id> --clear=description

# Delete team folder
hackmd-cli team-folders delete --teamPath=<team-path> --folderId=<id>
Expand All @@ -162,6 +189,7 @@ hackmd-cli team-folders order --teamPath=<team-path> --order='{"root":["folder-i
```bash
hackmd-cli teams # List accessible teams
hackmd-cli history # List browsing history
hackmd-cli history --limit=10 # Limit the number of items
```

### Export
Expand All @@ -180,10 +208,15 @@ Available permission values:
| `--writePermission` | `owner`, `signed_in`, `guest` |
| `--commentPermission` | `disabled`, `forbidden`, `owners`, `signed_in_users`, `everyone` |

## Folder Flags
## Note and Folder Update Flags

Omitted fields stay unchanged. `--description=''` sets an empty string; `--clear=description` removes the description. Do not set and clear the same field in one command.

```bash
--parentFolderId=<folder-id> # Put note/folder inside another folder
--root # Move a note/folder to root (update only)
--clear=description # Clear note/folder description (update only)
--clear=icon --clear=color # Clear folder fields (repeatable, update only)
--icon=1F600 # Emoji unified codepoint string
--color='#4F46E5' # Hex color string
--order='{"root":["id1","id2"]}' # Folder ordering JSON
Expand Down
7 changes: 6 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
},
"bugs": "https://github.com/hackmdio/hackmd-cli/issues",
"dependencies": {
"@hackmd/api": "2.6.0",
"@hackmd/api": "2.8.0-beta.20261120140115.031d6dc",
"@inquirer/password": "^5.2.4",
"@oclif/core": "5.1.9",
"@oclif/plugin-autocomplete": "4.0.5",
Expand Down Expand Up @@ -57,6 +57,11 @@
"commands": "./lib/commands",
"bin": "hackmd-cli",
"topicSeparator": " ",
"topics": {
"api": {
"description": "Explore and call HackMD API operations"
}
},
"additionalHelpFlags": [
"-h"
],
Expand Down
11 changes: 6 additions & 5 deletions pnpm-lock.yaml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 2 additions & 0 deletions scripts/test-package.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -133,6 +133,8 @@ try {
error => error.code === 2 && /No access token configured/.test(error.stderr),
)
assert.match(await run(['help', 'notes', 'create']), /--readPermission/)
assert.match(await run(['api', 'operations']), /\bGetMe\b/)
assert.deepEqual(JSON.parse(await run(['api', 'call', 'GetMe'])), user)
for (const argv of [
['whoami'],
['teams'],
Expand Down
68 changes: 68 additions & 0 deletions src/api/operations.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
import type {OperationId} from '@hackmd/api/raw'

import {operationRegistry} from '@hackmd/api/raw'

export type Operation = {
call: unknown;
method: string;
parameters: ReadonlyArray<{in: string; name: string; required: boolean; type: string}>;
path: string;
requestBody?: {
binaryFields: ReadonlyArray<{name: string; required: boolean}>;
contentTypes: readonly string[];
required: boolean;
};
responses: Record<string, readonly string[]>;
}

export function getOperation(id: string): Operation {
if (!Object.hasOwn(operationRegistry, id)) {
throw new Error(`Unknown operation "${id}". Run "hackmd-cli api operations" to see available operations.`)
}

return operationRegistry[id as OperationId]
}

export function parsePairs(values: string[], separator: string, kind: string): Record<string, string> {
const result: Record<string, string> = Object.create(null)
for (const value of values) {
const index = value.indexOf(separator)
if (index <= 0) throw new Error(`Invalid --${kind} value "${value}"; expected key${separator}value`)
const key = value.slice(0, index).trim()
if (!key || Object.hasOwn(result, key)) throw new Error(`Duplicate or empty --${kind} key "${key}"`)
result[key] = value.slice(index + separator.length).trim()
}

return result
}

export function validateParameters(operation: Operation, location: 'path' | 'query', input: Record<string, string>): Record<string, boolean | number | string> {
const parameters = operation.parameters.filter(parameter => parameter.in === location)
const allowed = new Map(parameters.map(parameter => [parameter.name, parameter]))
for (const parameter of parameters) {
if (parameter.required && !Object.hasOwn(input, parameter.name)) {
throw new Error(`Missing required --${location} ${parameter.name}=...`)
}
}

const result: Record<string, boolean | number | string> = {}
for (const [key, value] of Object.entries(input)) {
const parameter = allowed.get(key)
if (!parameter) throw new Error(`Unknown --${location} parameter "${key}" for ${operation.method} ${operation.path}`)
if (parameter.type === 'number' || parameter.type === 'integer') {
const number = Number(value)
if (value === '' || !Number.isFinite(number) || (parameter.type === 'integer' && !Number.isInteger(number))) {
throw new Error(`--${location} ${key} must be a ${parameter.type}`)
}

result[key] = number
} else if (parameter.type === 'boolean') {
if (value !== 'true' && value !== 'false') throw new Error(`--${location} ${key} must be true or false`)
result[key] = value === 'true'
} else {
result[key] = value
}
}

return result
}
19 changes: 10 additions & 9 deletions src/command.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,17 +10,18 @@ export default abstract class HackMDCommand extends Command {
return super.catch(error)
}

async getAPIClient() {
let token = config.accessToken
if (!token) {
if (!process.stdin.isTTY) {
this.error('No access token configured. Set HMD_API_ACCESS_TOKEN or run hackmd-cli login in a terminal.')
}

const {default: password} = await import('@inquirer/password')
token = await password({mask: false, message: 'Enter your access token', toggleMask: false})
protected async getAccessToken() {
if (config.accessToken) return config.accessToken
if (!process.stdin.isTTY) {
this.error('No access token configured. Set HMD_API_ACCESS_TOKEN or run hackmd-cli login in a terminal.')
}

const {default: password} = await import('@inquirer/password')
return password({mask: false, message: 'Enter your access token', toggleMask: false})
}

async getAPIClient() {
const token = await this.getAccessToken()
const APIClient = new API(token, config.hackmdAPIEndpointURL)

try {
Expand Down
Loading
Loading