hackmd-cli - The HackMD Command Line Tool

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

If you are using the CLI with CodiMD, please follow the v1.x README
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.1.0 darwin-arm64 node-v17.9.1
$ 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`

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
  -e, --editor                           create note with $EDITOR
  -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

Name		Name	Last commit message	Last commit date
Latest commit History 120 Commits
.github/workflows		.github/workflows
bin		bin
src		src
test		test
.editorconfig		.editorconfig
.env.example		.env.example
.gitignore		.gitignore
.nvmrc		.nvmrc
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tslint.json		tslint.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

hackmd-cli - The HackMD Command Line Tool

v2 notice

Migrating from v1.x

Usage

Configuration

Set access token

Example:

Specify HackMD API endpoint manually (optional)

Example:

Configuration Reference

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`

License

About

Uh oh!

Releases 12

Packages

Uh oh!

Contributors 6

Uh oh!

Languages

License

hackmdio/hackmd-cli

Folders and files

Latest commit

History

Repository files navigation

hackmd-cli - The HackMD Command Line Tool

v2 notice

Migrating from v1.x

Usage

Configuration

Set access token

Example:

Specify HackMD API endpoint manually (optional)

Example:

Configuration Reference

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

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 12

Packages 0

Uh oh!

Contributors 6

Uh oh!

Languages

`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`

Packages