██╗   ██╗ ██████╗ ██╗ ██████╗███████╗
 ██║   ██║██╔═══██╗██║██╔════╝██╔════╝
 ██║   ██║██║   ██║██║██║     █████╗
 ╚██╗ ██╔╝██║   ██║██║██║     ██╔══╝
  ╚████╔╝ ╚██████╔╝██║╚██████╗███████╗
   ╚═══╝   ╚═════╝ ╚═╝ ╚═════╝╚══════╝
 ███╗   ██╗ ██████╗ ████████╗███████╗███████╗
 ████╗  ██║██╔═══██╗╚══██╔══╝██╔════╝██╔════╝
 ██╔██╗ ██║██║   ██║   ██║   █████╗  ███████╗
 ██║╚██╗██║██║   ██║   ██║   ██╔══╝  ╚════██║
 ██║ ╚████║╚██████╔╝   ██║   ███████╗███████║
 ╚═╝  ╚═══╝ ╚═════╝    ╚═╝   ╚══════╝╚══════╝

voicenotes-cli

A command-line tool that syncs voice notes from the Voicenotes API to local markdown files. Ported from the voicenotes-sync Obsidian plugin, replacing Obsidian-specific APIs with Node.js equivalents.

Installation

npm install -g voicenotes-cli

Or run directly with npx:

npx voicenotes-cli

Requires Node.js 18 or later.

Authentication

Get your API token from your Voicenotes account settings, then:

voicenotes auth <your-token>

The token is stored globally at ~/.config/voicenotes/auth.json. You can validate a stored token with:

voicenotes auth --validate

Usage

Initialize a sync directory

voicenotes init

Creates a .voicenotes/ directory with config.json and state.json. By default, markdown files are written to a voicenotes/ subdirectory.

Sync voice notes

voicenotes sync

Fetches recordings from the API and writes each one as a markdown file with YAML frontmatter containing the recording_id, duration, created_at, updated_at, and tags.

Subsequent syncs are incremental — only recordings updated since the last sync are fetched. To force a full re-sync:

voicenotes sync --full

Preview what would be synced without making any changes:

voicenotes sync --dry-run

Delete recordings from the server after syncing:

voicenotes sync --delete-remote

View or change config

voicenotes config                        # list all settings
voicenotes config syncDirectory           # get a single value
voicenotes config downloadAudio true      # set a value

Delete a remote recording

voicenotes delete <recording_id>

Targeting a different directory

All commands accept -d / --directory to operate on a different sync directory:

voicenotes init -d ~/notes
voicenotes sync -d ~/notes

Configuration

Settings are stored in .voicenotes/config.json within the sync directory. Key options:

| Setting | Default | Description | |---|---|---| | syncDirectory | voicenotes | Subdirectory where markdown files are written | | downloadAudio | false | Download MP3 audio files into an audio/ subfolder | | dateFormat | YYYY-MM-DD | Moment.js format for dates in note content | | filenameDateFormat | YYYY-MM-DD | Moment.js format for dates in filenames | | filenameTemplate | {{date}} {{title}} | Template for generated filenames | | todoTag | "" | Tag appended to todo items (e.g. todo) | | excludeTags | [] | Tags to filter out during sync | | tagFilterMode | exclude | exclude or include — how excludeTags is applied | | deleteSynced | false | Delete recordings from server after syncing | | reallyDeleteSynced | false | Second confirmation required for remote deletion |

Templates

Templates are stored as editable files in .voicenotes/:

• frontmatter.template — YAML frontmatter for each note
• note.template — markdown body for each note

Manage them with the template command:

voicenotes template                      # list templates and their paths
voicenotes template note                 # print the current note template
voicenotes template note --path          # print the file path (handy for $EDITOR)
voicenotes template frontmatter --reset  # restore the default

Or just edit the files directly. They use Jinja2-style syntax. Available variables:

recording_id, title, date, duration, created_at, updated_at, transcript, summary, tidy, points, todo, tweet, blog, email, custom, tags, related_notes, subnotes, attachments, parent_note, embedded_audio_link, audio_filename

File structure

After syncing, your directory will look like:

.voicenotes/
  config.json              # settings
  state.json               # sync cursor (last_synced_at, deleted IDs)
  frontmatter.template     # YAML frontmatter template
  note.template            # markdown body template
voicenotes/
  2025-01-15 My first note.md
  2025-01-16 Another thought.md
  audio/               # if downloadAudio is enabled
    abc123.mp3
  attachments/          # if notes have image attachments
    image.png

Building

npm run build
npm link

Compiles TypeScript to dist/ and links the voicenotes command globally.