Newton's Programmatic Measurements

    @hackmd/hackmd-cli
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.2 • Public • Published

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

    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

    Keywords

    Install

    npm i @hackmd/hackmd-cli

    DownloadsWeekly Downloads

    1

    Version

    2.0.2

    License

    MIT

    Unpacked Size

    75.1 kB

    Total Files

    44

    Last publish

    Collaborators

    • a60814billy
    • yukaii
    • jackycute