HackMD CLI

If you are upgrading from version 1.x, note the following changes:

1. CodiMD Users: hackmd-cli v2 no longer supports CodiMD. Use the dedicated codimd-cli instead.
2. HackMD/EE Users:
   • JSON Config: If you use ~/.hackmd/config.json, remove it and start fresh.
   • Environment Variables: HMD_CLI_SERVER_URL has been renamed to HMD_API_ENDPOINT_URL. You must also set HMD_API_ACCESS_TOKEN.

Install the HackMD Command Line Tool globally using npm:

$ npm install -g @hackmd/hackmd-cli

You must provide an access token to use the CLI. You can obtain one from hackmd.io via Settings -> API -> Create API token.

There are three ways to configure the token:

1. Interactive Login: Run the login command to save the token to ~/.hackmd/config.json.
2. Environment Variable: Set HMD_API_ACCESS_TOKEN in your shell.
3. Manual Config File: Edit ~/.hackmd/config.json directly.

# Option 1: Interactive
$ hackmd-cli login

# Option 2: Environment Variable
export HMD_API_ACCESS_TOKEN=MY_ACCESS_TOKEN

# Option 3: Manual JSON
# Edit ~/.hackmd/config.json
{
  "accessToken": "MY_ACCESS_TOKEN"
}

Install the HackMD CLI globally using npm. To use it, you must provide an API token (generated at hackmd.io/settings#api). You can configure it via an interactive login which saves credentials to ~/.hackmd/config.json, or by setting the HMD_API_ACCESS_TOKEN environment variable. If you are using a HackMD EE instance, you must also set the HMD_API_ENDPOINT_URL environment variable.

# Install
npm install -g @hackmd/hackmd-cli

# Configure via interactive login
hackmd-cli login

# OR via environment variables
export HMD_API_ACCESS_TOKEN=YOUR_TOKEN
export HMD_API_ENDPOINT_URL=https://your.hackmd-ee.endpoint

The hackmd-cli configuration is stored in a config.json file. By default, this file is located in the .hackmd directory within your user's home directory. You can override this location by setting the HMD_CLI_CONFIG_DIR environment variable.

Default path: ~/.hackmd/config.json (on Unix-like systems)

By default, the CLI uses https://api.hackmd.io/v1. If you are using a custom HackMD Enterprise Edition (EE) instance, you must specify the custom endpoint URL using an environment variable or the JSON configuration file.

# Using Environment Variable
export HMD_API_ENDPOINT_URL=https://my.hackmd-ee.api.endpoint

# Using JSON config (~/.hackmd/config.json)
{
  "hackmdAPIEndpointURL": "https://my.hackmd-ee.api.endpoint"
}

If you encounter issues, check the following common error scenarios:

The autocomplete command provides instructions for installing shell completion for the CLI. You can specify the shell type (e.g., bash, zsh, fish).

$ hackmd-cli autocomplete zsh

Use the export command to retrieve the content of a specific note using its ID.

$ hackmd-cli export --noteId=kNFWV5E-Qz-QP7u6XnNvyQ

All list commands support various flags to control the output format and data presentation:

Output Formats:

• --output=json: JSON output.
• --output=yaml: YAML output.
• --output=csv (or --csv): CSV output.

Display and Filtering:

• --no-header: Hide table headers.
• --no-truncate: Don't truncate long values.
• --columns=id,title: Show specific columns.
• -x, --extended: Show additional columns.
• --filter=name=foo: Filter by property.
• --sort=title: Sort by property (use -title for descending).

When creating or updating notes, you can specify access permissions using the following values:

Read/Write Permissions (--readPermission, --writePermission):

• owner
• signed_in
• guest

Comment Permissions (--commentPermission):

• disabled
• forbidden
• owners
• signed_in_users
• everyone