hackmd-cli - The HackMD Command Line Tool

• Usage
• Commands
• Configuration
• License

v2 notice

hackmd-cli v2 now only supports the official HackMD instance(hackmd.io) and HackMD EE instances after version 1.38.1. CodiMD is not supported anymore. If you want to use the CLI tools with CodiMD, please check out the v1.x README and follow the instruction there.

Migrating from v1.x

1. If you are using the CLI with CodiMD, please follow the v1.x README
2. If you are using the CLI with HackMD(hackmd.io) or HackMD EE(Enterprise Edition) instances:
   • You're using the JSON file-based config: Remove ~/.hackmd/config.json and start over again. You can start with configuration section.
   • You're using environment variable based config: HMD_CLI_SERVER_URL has been replaced with HMD_API_ENDPOINT_URL. And HMD_API_ENDPOINT_URL may vary depending on your instance. Please check contact your instance admin to get the correct HMD_API_ENDPOINT_URL. For generating access token, please check the configuration section. You'll need to set the HMD_API_ACCESS_TOKEN environment variable.

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.

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

Login to HackMD server from CLI

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

Login to HackMD server from CLI

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