search

hackmdio / hackmd-cli

The HackMD/CodiMD Command Line Tool
https://github.com/hackmdio/hackmd-cli
MIT License
113 stars 11 forks source link
cli codimd oclif typescript

readme

hackmd-cli - The HackMD Command Line Tool

oclif Version Downloads/week 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 (--version|-v)
@hackmd/hackmd-cli/2.3.2 darwin-arm64 node-v18.14.2
$ 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 autocomplete [SHELL]

display autocomplete installation instructions

USAGE
  $ hackmd-cli autocomplete [SHELL] [-r]

ARGUMENTS
  SHELL  shell type

FLAGS
  -r, --refresh-cache  Refresh cache (ignores displaying instructions)

DESCRIPTION
  display autocomplete installation instructions

EXAMPLES
  $ hackmd-cli autocomplete

  $ hackmd-cli autocomplete bash

  $ hackmd-cli autocomplete fish

  $ hackmd-cli autocomplete zsh

  $ hackmd-cli autocomplete --refresh-cache

See code: @hackmd/oclif-plugin-autocomplete

hackmd-cli export

Export note content

USAGE
  $ hackmd-cli export [-h] [--noteId <value>]

FLAGS
  -h, --help        Show CLI help.
  --noteId=<value>  HackMD note id

DESCRIPTION
  Export note content

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

See code: src/commands/export.ts

hackmd-cli help [COMMANDS]

Display help for hackmd-cli.

USAGE
  $ hackmd-cli help [COMMANDS] [-n]

ARGUMENTS
  COMMANDS  Command to show help for.

FLAGS
  -n, --nested-commands  Include all nested commands in the output.

DESCRIPTION
  Display help for hackmd-cli.

See code: @oclif/plugin-help

hackmd-cli history

List user browse history

USAGE
  $ hackmd-cli history [-h] [--columns <value> | -x] [--sort <value>] [--filter <value>] [--output
    csv|json|yaml |  | [--csv | --no-truncate]] [--no-header | ]

FLAGS
  -h, --help         Show CLI help.
  -x, --extended     show extra columns
  --columns=<value>  only show provided columns (comma-separated)
  --csv              output is csv format [alias: --output=csv]
  --filter=<value>   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=<option>  output in a more machine friendly format
                     <options: csv|json|yaml>
  --sort=<value>     property to sort by (prepend '-' for descending)

DESCRIPTION
  List user browse history

EXAMPLES
  $ 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 [-h]

FLAGS
  -h, --help  Show CLI help.

DESCRIPTION
  Login to HackMD server from CLI

EXAMPLES
  $ 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 [-h]

FLAGS
  -h, --help  Show CLI help.

DESCRIPTION
  Login to HackMD server from CLI

EXAMPLES
  $ hackmd-cli logout
  You've logged out successfully

See code: src/commands/logout.ts

hackmd-cli notes

HackMD notes commands

USAGE
  $ hackmd-cli notes [-h] [--noteId <value>] [--columns <value> | -x] [--sort <value>] [--filter <value>]
    [--output csv|json|yaml |  | [--csv | --no-truncate]] [--no-header | ]

FLAGS
  -h, --help         Show CLI help.
  -x, --extended     show extra columns
  --columns=<value>  only show provided columns (comma-separated)
  --csv              output is csv format [alias: --output=csv]
  --filter=<value>   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=<value>   HackMD note id
  --output=<option>  output in a more machine friendly format
                     <options: csv|json|yaml>
  --sort=<value>     property to sort by (prepend '-' for descending)

DESCRIPTION
  HackMD notes commands

EXAMPLES
  $ 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 [-h] [--title <value>] [--content <value>] [--readPermission <value>]
    [--writePermission <value>] [--commentPermission <value>] [-e] [--columns <value> | -x] [--sort <value>] [--filter
    <value>] [--output csv|json|yaml |  | [--csv | --no-truncate]] [--no-header | ]

FLAGS
  -e, --editor                 create note with $EDITOR
  -h, --help                   Show CLI help.
  -x, --extended               show extra columns
  --columns=<value>            only show provided columns (comma-separated)
  --commentPermission=<value>  set comment permission: disabled, forbidden, owners, signed_in_users, everyone
  --content=<value>            new note content
  --csv                        output is csv format [alias: --output=csv]
  --filter=<value>             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=<option>            output in a more machine friendly format
                               <options: csv|json|yaml>
  --readPermission=<value>     set note permission: owner, signed_in, guest
  --sort=<value>               property to sort by (prepend '-' for descending)
  --title=<value>              new note title
  --writePermission=<value>    set note permission: owner, signed_in, guest

DESCRIPTION
  Create a note

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

hackmd-cli notes delete

Delete a note

USAGE
  $ hackmd-cli notes delete [-h] [--noteId <value>]

FLAGS
  -h, --help        Show CLI help.
  --noteId=<value>  HackMD note id

DESCRIPTION
  Delete a note

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

hackmd-cli notes update

Update note content

USAGE
  $ hackmd-cli notes update [-h] [--noteId <value>] [--content <value>]

FLAGS
  -h, --help         Show CLI help.
  --content=<value>  new note content
  --noteId=<value>   HackMD note id

DESCRIPTION
  Update note content

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

hackmd-cli team-notes

HackMD team-notes commands

USAGE
  $ hackmd-cli team-notes [-h] [--teamPath <value>] [--columns <value> | -x] [--sort <value>] [--filter <value>]
    [--output csv|json|yaml |  | [--csv | --no-truncate]] [--no-header | ]

FLAGS
  -h, --help          Show CLI help.
  -x, --extended      show extra columns
  --columns=<value>   only show provided columns (comma-separated)
  --csv               output is csv format [alias: --output=csv]
  --filter=<value>    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=<option>   output in a more machine friendly format
                      <options: csv|json|yaml>
  --sort=<value>      property to sort by (prepend '-' for descending)
  --teamPath=<value>  HackMD team path

DESCRIPTION
  HackMD team-notes commands

EXAMPLES
  $ 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 [-h] [--teamPath <value>] [--title <value>] [--content <value>] [--readPermission
    <value>] [--writePermission <value>] [--commentPermission <value>] [-e] [--columns <value> | -x] [--sort <value>]
    [--filter <value>] [--output csv|json|yaml |  | [--csv | --no-truncate]] [--no-header | ]

FLAGS
  -e, --editor                 create note with $EDITOR
  -h, --help                   Show CLI help.
  -x, --extended               show extra columns
  --columns=<value>            only show provided columns (comma-separated)
  --commentPermission=<value>  set comment permission: disabled, forbidden, owners, signed_in_users, everyone
  --content=<value>            new note content
  --csv                        output is csv format [alias: --output=csv]
  --filter=<value>             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=<option>            output in a more machine friendly format
                               <options: csv|json|yaml>
  --readPermission=<value>     set note permission: owner, signed_in, guest
  --sort=<value>               property to sort by (prepend '-' for descending)
  --teamPath=<value>           HackMD team path
  --title=<value>              new note title
  --writePermission=<value>    set note permission: owner, signed_in, guest

DESCRIPTION
  Create a team note

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

hackmd-cli team-notes delete

Delete a team note

USAGE
  $ hackmd-cli team-notes delete [-h] [--teamPath <value>] [--noteId <value>]

FLAGS
  -h, --help          Show CLI help.
  --noteId=<value>    HackMD note id
  --teamPath=<value>  HackMD team path

DESCRIPTION
  Delete a team note

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

hackmd-cli team-notes update

Update team note content

USAGE
  $ hackmd-cli team-notes update [-h] [--teamPath <value>] [--noteId <value>] [--content <value>]

FLAGS
  -h, --help          Show CLI help.
  --content=<value>   new note content
  --noteId=<value>    HackMD note id
  --teamPath=<value>  HackMD team path

DESCRIPTION
  Update team note content

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

hackmd-cli teams

List teams

USAGE
  $ hackmd-cli teams [-h] [--columns <value> | -x] [--sort <value>] [--filter <value>] [--output
    csv|json|yaml |  | [--csv | --no-truncate]] [--no-header | ]

FLAGS
  -h, --help         Show CLI help.
  -x, --extended     show extra columns
  --columns=<value>  only show provided columns (comma-separated)
  --csv              output is csv format [alias: --output=csv]
  --filter=<value>   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=<option>  output in a more machine friendly format
                     <options: csv|json|yaml>
  --sort=<value>     property to sort by (prepend '-' for descending)

DESCRIPTION
  List teams

EXAMPLES
  $ 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 [--json] [--verbose]

FLAGS
  --verbose  Show additional information about the CLI.

GLOBAL FLAGS
  --json  Format output as json.

FLAG DESCRIPTIONS
  --verbose  Show additional information about the CLI.

    Additionally shows the architecture, node version, operating system, and versions of plugins that the CLI is using.

See code: @oclif/plugin-version

hackmd-cli whoami

Show current user information

USAGE
  $ hackmd-cli whoami [-h] [--columns <value> | -x] [--sort <value>] [--filter <value>] [--output
    csv|json|yaml |  | [--csv | --no-truncate]] [--no-header | ]

FLAGS
  -h, --help         Show CLI help.
  -x, --extended     show extra columns
  --columns=<value>  only show provided columns (comma-separated)
  --csv              output is csv format [alias: --output=csv]
  --filter=<value>   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=<option>  output in a more machine friendly format
                     <options: csv|json|yaml>
  --sort=<value>     property to sort by (prepend '-' for descending)

DESCRIPTION
  Show current user information

EXAMPLES
  $ 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