Image Not Showing Possible Reasons
The image file may be corrupted
The server hosting the image is unavailable
The image path is incorrect
The image format is not supported
Learn More →

回到 HackMD 教學首頁

Image Not Showing Possible Reasons
The image file may be corrupted
The server hosting the image is unavailable
The image path is incorrect
The image format is not supported
Learn More →

給予建議或回報BUG

hackmd-cli - The HackMD Command Line Tool

If you work mostly from the command line, you can interact with HackMD via hackmd-cli. It's really handy to, for example, create a copy of local files on HackMD.

hackmd-cli - The HackMD Command Line Tool

Image Not Showing Possible Reasons

The image file may be corrupted
The server hosting the image is unavailable
The image path is incorrect
The image format is not supported

Learn More →

If you have experienced hackmd-cli versions older than v2 and/or would like to migrated from them, please refer to this document.

Usage

$ npm install -g @hackmd/hackmd-cli
$ hackmd-cli COMMAND
running command...
$ hackmd-cli (-v|--version|version)
@hackmd/hackmd-cli/2.0.2 darwin-arm64 node-v17.7.0
$ hackmd-cli --help [COMMAND]
USAGE
  $ hackmd-cli COMMAND
...

Configuration

Set access token

Access token should be set before using hackmd-cli. It can be created by landing hackmd.io -> Setting -> API -> Create API token. Copy the token and set it as config variable. For more details, please follow the tutorial: How to issue an API token.

Example:

Set the access token by login command. By doing so, the access token will be saved in ~/.hackmd/config.json.

$ hackmd-cli login
Enter your access token: My_ACCESS_TOKEN

Or you don't want to keep the credentials in one file, you can set it through environment variable:

export HMD_API_ACCESS_TOKEN=MY_ACCESS_TOKEN

Or you can write the configuration file manually. Edit ~/.hackmd/config.json with the following content:

{
  "accessToken": "MY_ACCESS_TOKEN"
}

Specify HackMD API endpoint manually (optional)

hackmd-cli operates on the official HackMD API endpoint (https://api.hackmd.io/v1) by default. If you want to use hackmd-cli with a custom HackMD EE instance, you will need to configure the API endpoint by either environment variable or JSON configuration manually.

Example:

Set environment variable in your shell profile:

export HMD_API_ENDPOINT_URL=https://my.hackmd-ee.api.endpoint

Or in JSON file (~/.hackmd/config.json):

{
  "hackmdAPIEndpointURL": "https://my.hackmd-ee.api.endpoint"
}

Configuration Reference

All available configurations are listed in the table below.

Config key	Environment Variable	Data Type	Example Value	Description
`hackmdAPIEndpointURL`	`HMD_API_ENDPOINT_URL`	`string`	`https://api.hackmd.io/v1`	HackMD EE API endpoint URL
`accessToken`	`HMD_API_ACCESS_TOKEN`	`string`	`UFHR12H7FSEF3ADFY3N9YNRN2E49VGR212NBF`	Token to access HackMD APIs

Commands

hackmd-cli export
hackmd-cli help [COMMAND]
hackmd-cli history
hackmd-cli login
hackmd-cli logout
hackmd-cli notes
hackmd-cli notes:create
hackmd-cli notes:delete
hackmd-cli notes:update
hackmd-cli team-notes
hackmd-cli team-notes:create
hackmd-cli team-notes:delete
hackmd-cli team-notes:update
hackmd-cli teams
hackmd-cli version
hackmd-cli whoami

`hackmd-cli export`

Export note content

USAGE
  $ hackmd-cli export

OPTIONS
  -h, --help       Show CLI help.
  --noteId=noteId  HackMD note id

EXAMPLE
  $ hackmd-cli export --noteId=kNFWV5E-Qz-QP7u6XnNvyQ
  # A note to be exported

See code: src/commands/export.ts

`hackmd-cli help [COMMAND]`

display help for hackmd-cli

USAGE
  $ hackmd-cli help [COMMAND]

ARGUMENTS
  COMMAND  command to show help for

OPTIONS
  --all  see all commands in CLI

See code: @oclif/plugin-help

`hackmd-cli history`

List user browse history

USAGE
  $ hackmd-cli history

OPTIONS
  -h, --help              Show CLI help.
  -x, --extended          show extra columns
  --columns=columns       only show provided columns (comma-separated)
  --csv                   output is csv format [alias: --output=csv]
  --filter=filter         filter property by partial string matching, ex: name=foo
  --no-header             hide table header from output
  --no-truncate           do not truncate output to fit screen
  --output=csv|json|yaml  output in a more machine friendly format
  --sort=sort             property to sort by (prepend '-' for descending)

EXAMPLE
  $ hackmd-cli history
  ID                     Title                            User Path               Team Path
  ────────────────────── ──────────────────────────────── ────────────────────── ────────
  raUuSTetT5uQbqQfLnz9lA CLI test note                    gvfz2UB5THiKABQJQnLs6Q null
  BnC6gN0_TfStV2KKmPPXeg Welcome to your team's workspace null                   CLI-test

See code: src/commands/history.ts

`hackmd-cli login`

USAGE
  $ hackmd-cli login

OPTIONS
  -h, --help  Show CLI help.

EXAMPLE
  $ hackmd-cli login

  Enter your access token: MY_ACCESS_TOKEN

  Login successfully

See code: src/commands/login.ts

`hackmd-cli logout`

USAGE
  $ hackmd-cli logout

OPTIONS
  -h, --help  Show CLI help.

EXAMPLE
  $ hackmd-cli logout

  You've logged out successfully

See code: src/commands/logout.ts

`hackmd-cli notes`

HackMD notes commands

USAGE
  $ hackmd-cli notes

OPTIONS
  -h, --help              Show CLI help.
  -x, --extended          show extra columns
  --columns=columns       only show provided columns (comma-separated)
  --csv                   output is csv format [alias: --output=csv]
  --filter=filter         filter property by partial string matching, ex: name=foo
  --no-header             hide table header from output
  --no-truncate           do not truncate output to fit screen
  --noteId=noteId         HackMD note id
  --output=csv|json|yaml  output in a more machine friendly format
  --sort=sort             property to sort by (prepend '-' for descending)

EXAMPLE
  $ hackmd-cli notes
  ID                     Title                            User Path               Team Path
  ────────────────────── ──────────────────────────────── ────────────────────── ────────
  raUuSTetT5uQbqQfLnz9lA CLI test note                    gvfz2UB5THiKABQJQnLs6Q null

See code: src/commands/notes/index.ts

`hackmd-cli notes:create`

Create a note

USAGE
  $ hackmd-cli notes:create

OPTIONS
  -h, --help                             Show CLI help.
  -x, --extended                         show extra columns
  --columns=columns                      only show provided columns (comma-separated)
  --commentPermission=commentPermission  set comment permission: disabled, forbidden, owners, signed_in_users, everyone
  --content=content                      new note content
  --csv                                  output is csv format [alias: --output=csv]
  --filter=filter                        filter property by partial string matching, ex: name=foo
  --no-header                            hide table header from output
  --no-truncate                          do not truncate output to fit screen
  --output=csv|json|yaml                 output in a more machine friendly format
  --readPermission=readPermission        set note permission: owner, signed_in, guest
  --sort=sort                            property to sort by (prepend '-' for descending)
  --title=title                          new note title
  --writePermission=writePermission      set note permission: owner, signed_in, guest

EXAMPLES
  notes create --content='# A new note' --readPermission=owner --writePermission=owner --commentPermission=disabled
  ID                     Title                            User Path               Team Path
  ────────────────────── ──────────────────────────────── ──────────────────────  ────────
  raUuSTetT5uQbqQfLnz9lA A new note                       gvfz2UB5THiKABQJQnLs6Q  null
  Or you can pipe content via Unix pipeline:
  cat README.md | hackmd-cli notes create

See code: src/commands/notes/create.ts

`hackmd-cli notes:delete`

Delete a note

USAGE
  $ hackmd-cli notes:delete

OPTIONS
  -h, --help       Show CLI help.
  --noteId=noteId  HackMD note id

EXAMPLE
  $ hackmd-cli notes delete --noteId=WNkLM6gkS0Cg2cQ8rv7bYA

See code: src/commands/notes/delete.ts

`hackmd-cli notes:update`

Update note content

USAGE
  $ hackmd-cli notes:update

OPTIONS
  -h, --help         Show CLI help.
  --content=content  new note content
  --noteId=noteId    HackMD note id

EXAMPLE
  $ hackmd-cli notes update --noteId=WNkLM6gkS0Cg2cQ8rv7bYA --content='# A new title'

See code: src/commands/notes/update.ts

`hackmd-cli team-notes`

HackMD team-notes commands

USAGE
  $ hackmd-cli team-notes

OPTIONS
  -h, --help              Show CLI help.
  -x, --extended          show extra columns
  --columns=columns       only show provided columns (comma-separated)
  --csv                   output is csv format [alias: --output=csv]
  --filter=filter         filter property by partial string matching, ex: name=foo
  --no-header             hide table header from output
  --no-truncate           do not truncate output to fit screen
  --output=csv|json|yaml  output in a more machine friendly format
  --sort=sort             property to sort by (prepend '-' for descending)
  --teamPath=teamPath     HackMD team path

EXAMPLE
  $ hackmd-cli team-notes --teamPath=CLI-test
  ID                     Title                            User path Team path
  ────────────────────── ──────────────────────────────── ──────── ────────
  WNkLM6gkS0Cg2cQ8rv7bYA a team note                      null     CLI-test
  BnC6gN0_TfStV2KKmPPXeg Welcome to your team's workspace null     CLI-test

See code: src/commands/team-notes/index.ts

`hackmd-cli team-notes:create`

Create a team note

USAGE
  $ hackmd-cli team-notes:create

OPTIONS
  -h, --help                             Show CLI help.
  -x, --extended                         show extra columns
  --columns=columns                      only show provided columns (comma-separated)
  --commentPermission=commentPermission  set comment permission: disabled, forbidden, owners, signed_in_users, everyone
  --content=content                      new note content
  --csv                                  output is csv format [alias: --output=csv]
  --filter=filter                        filter property by partial string matching, ex: name=foo
  --no-header                            hide table header from output
  --no-truncate                          do not truncate output to fit screen
  --output=csv|json|yaml                 output in a more machine friendly format
  --readPermission=readPermission        set note permission: owner, signed_in, guest
  --sort=sort                            property to sort by (prepend '-' for descending)
  --teamPath=teamPath                    HackMD team path
  --title=title                          new note title
  --writePermission=writePermission      set note permission: owner, signed_in, guest

EXAMPLES
  team-notes:create --teamPath=CLI-test --content='# A new note' --readPermission=owner --writePermission=owner 
  --commentPermission=disabled
  ID                     Title                            User Path              Team Path
  ────────────────────── ──────────────────────────────── ────────────────────── ────────
  raUuSTetT5uQbqQfLnz9lA A new note                       gvfz2UB5THiKABQJQnLs6Q null     
  Or you can pipe content via Unix pipeline:
  cat README.md | hackmd-cli notes create --teamPath=CLI-test

See code: src/commands/team-notes/create.ts

`hackmd-cli team-notes:delete`

Delete a team note

USAGE
  $ hackmd-cli team-notes:delete

OPTIONS
  -h, --help           Show CLI help.
  --noteId=noteId      HackMD note id
  --teamPath=teamPath  HackMD team path

EXAMPLE
  $ hackmd-cli team-notes delete --teamPath=CLI-test --noteId=WNkLM6gkS0Cg2cQ8rv7bYA

See code: src/commands/team-notes/delete.ts

`hackmd-cli team-notes:update`

Update team note content

USAGE
  $ hackmd-cli team-notes:update

OPTIONS
  -h, --help           Show CLI help.
  --content=content    new note content
  --noteId=noteId      HackMD note id
  --teamPath=teamPath  HackMD team path

EXAMPLE
  $ hackmd-cli team-notes update --teamPath=CLI-test --noteId=WNkLM6gkS0Cg2cQ8rv7bYA --content='# A new title'

See code: src/commands/team-notes/update.ts

`hackmd-cli teams`

List teams

USAGE
  $ hackmd-cli teams

OPTIONS
  -h, --help              Show CLI help.
  -x, --extended          show extra columns
  --columns=columns       only show provided columns (comma-separated)
  --csv                   output is csv format [alias: --output=csv]
  --filter=filter         filter property by partial string matching, ex: name=foo
  --no-header             hide table header from output
  --no-truncate           do not truncate output to fit screen
  --output=csv|json|yaml  output in a more machine friendly format
  --sort=sort             property to sort by (prepend '-' for descending)

EXAMPLE
  $ hackmd-cli teams
  ID                                   Name          Path     Owner ID
  ──────────────────────────────────── ───────────── ──────── ────────────────────────────────────
  f76308a6-d77a-41f6-86d0-8ada426a6fb4 CLI test team CLI-test 82f7f3d9-4079-4c78-8a00-14094272ece9

See code: src/commands/teams.ts

`hackmd-cli version`

USAGE
  $ hackmd-cli version

See code: @oclif/plugin-version

`hackmd-cli whoami`

Show current user information

USAGE
  $ hackmd-cli whoami

OPTIONS
  -h, --help              Show CLI help.
  -x, --extended          show extra columns
  --columns=columns       only show provided columns (comma-separated)
  --csv                   output is csv format [alias: --output=csv]
  --filter=filter         filter property by partial string matching, ex: name=foo
  --no-header             hide table header from output
  --no-truncate           do not truncate output to fit screen
  --output=csv|json|yaml  output in a more machine friendly format
  --sort=sort             property to sort by (prepend '-' for descending)

EXAMPLE
  $ hackmd-cli whoami
  ID                                   Name           Email User path
  ──────────────────────────────────── ────────────── ───── ──────────────────────
  82f7f3d9-4079-4c78-8a00-14094272ece9 Ming-Hsiu Tsai null  gvfz2UB5THiKABQJQnLs6Q

See code: src/commands/whoami.ts

License

MIT