hackmd

Rust client library and CLI for HackMD.

Ports the official @hackmd/api SDK and @hackmd/hackmd-cli to Rust, plus an optional terminal UI behind the tui feature.

Install

cargo install hackmd

This installs the hackmd binary. The cli feature is on by default; library-only consumers should opt out (see below).

CLI

Authentication

Create a HackMD access token at https://hackmd.io/settings#api, then log in:

$ hackmd login
Enter your HackMD access token: ********
Login successfully

The token is written to ~/.hackmd/config.json. To log out:

$ hackmd logout
You've logged out successfully

Commands

hackmd login                                          # interactive token prompt + validate
hackmd logout                                         # clear the stored token
hackmd whoami                                         # show the authenticated user
hackmd history                                        # list browse history
hackmd export --note-id <id>                          # dump raw markdown to stdout
hackmd teams                                          # list teams

hackmd notes list                                     # list your notes
hackmd notes get --note-id <id>                       # fetch a single note
hackmd notes create [--title <t>] [--content <c>] \
                    [--read-permission <r>] \
                    [--write-permission <w>] \
                    [--comment-permission <c>] \
                    [-e | --editor]                   # create a note (stdin or $EDITOR also accepted)
hackmd notes update --note-id <id> --content <c>      # replace a note's content
hackmd notes delete --note-id <id>                    # delete a note

hackmd team-notes --team-path <p> list
hackmd team-notes --team-path <p> create  ...         # same flags as `notes create`
hackmd team-notes --team-path <p> update --note-id <id> --content <c>
hackmd team-notes --team-path <p> delete --note-id <id>

hackmd tui                                            # interactive TUI (requires --features tui at install)

Every list-style command accepts shared output flags:

flag	meaning
`--output {table\|json\|csv\|yaml}`	output format (default `table`)
`--columns id,title,...`	project a subset of columns
`--sort <column>`	sort rows by a column (string compare)
`--filter key=value`	keep rows where `row[key] == value`
`--no-header`	omit the header row
`--no-truncate`	don't shrink wide cells to fit the terminal

Permission values: owner, signed_in, guest. Comment permission values: disabled, forbidden, owners, signed_in_users, everyone.

Content precedence on `notes create` / `team-notes create`

--editor opens $EDITOR on a temp .md file and uses the saved contents.
If stdin is piped (cat note.md | hackmd notes create), the piped bytes are used.
Otherwise the --content flag value is used.
If none of those is set, the note is created with empty content (matches upstream).

Environment variables

variable	maps to	notes
`HMD_API_ACCESS_TOKEN`	the access token	takes precedence over the file config
`HMD_API_ENDPOINT_URL`	the API base URL	defaults to `https://api.hackmd.io/v1`
`HMD_CLI_CONFIG_DIR`	config directory	defaults to `~/.hackmd`

Each of these has a matching global CLI flag (--token, --endpoint, --config-dir) that takes priority over the env value when set.

Examples

# Show notes as JSON
hackmd notes list --output json

# Filter then sort
hackmd notes list --filter teamPath=demo --sort title

# Create a note from stdin
cat draft.md | hackmd notes create --title "Draft"

# Create a team note via $EDITOR
hackmd team-notes --team-path my-team create --editor --title "RFC"

TUI

Install with the tui feature, then run hackmd tui to browse and edit your notes interactively:

cargo install hackmd --features tui
hackmd tui

Two-pane layout: note list on the left, selected-note content on the right.

key	action
`j` / `↓`	move selection down
`k` / `↑`	move selection up
`Enter` / `o`	load the selected note into the right pane
`r`	refresh the note list
`e`	open the selected note in `$EDITOR` and save on exit
`q` / `Esc`	quit

The TUI currently covers user notes only — team notes and folders are still CLI-only for this release.

Library

[dependencies]
hackmd = { version = "0.0", default-features = false }

# async fn run() -> hackmd::Result<()> {
let client = hackmd::Client::new(std::env::var("HMD_API_ACCESS_TOKEN").unwrap())?;
let me = client.me().await?;
println!("hello {}", me.name);

let notes = client.notes().await?;
for n in &notes {
    println!("{}\t{}", n.id, n.title);
}
# Ok(()) }

The full SDK surface (user notes, team notes, folders + folder-order, ETag-aware GET, retries, rate-limit parsing) lives on Client. Requires a tokio runtime.

Features

feature	default	what it pulls in
`cli`	yes	CLI binary and its dependencies
`tui`	no	TUI subcommand (implies `cli`) — install with `cargo install hackmd --features tui`

The cli feature gates compilation of src/cli/ and the hackmd binary. The binary's required-features = ["cli"] means cargo build --no-default-features simply skips the binary build.

License

MIT

hackmd 0.0.2