Basalt Cortex CLI

Sync your markdown vault with Basalt Cortex — a cloud-native knowledge workspace.

Install

npm install -g basalt-cortex

Usage

Login

basalt-cortex login

Generate an API token at basaltcortex.com/settings and paste it when prompted.

Push (local to cloud)

basalt-cortex push ~/Documents/vault

Uploads all .md files to Basalt Cortex. Folder structure is preserved. Frontmatter metadata (tags, type, summary) is synced.

Pull (cloud to local)

basalt-cortex pull ~/Documents/vault

Downloads all notes as .md files with frontmatter. Creates matching folder structure.

Sync (bidirectional)

basalt-cortex sync ~/Documents/vault

Watches the folder for changes and pushes them to Basalt Cortex. Polls for remote changes every 30 seconds and pulls them locally. Press Ctrl+C to stop.

Status

basalt-cortex status

Shows connection info, last sync time, and tracked files.

How It Works

• Local files map to notes via external_id (derived from file path)
• Frontmatter is preserved bidirectionally (tags, note_type, summary)
• Changes are detected by content hash — unchanged files are skipped
• Sync state is stored in ~/.basalt-cortex/sync-state.json
• Conflicts: last-write-wins (by timestamp)

Obsidian Compatibility

Point the CLI at your Obsidian vault folder. Frontmatter, folder structure, and wikilinks are preserved. Edit in Obsidian locally, see changes in Basalt Cortex within seconds.

License

Proprietary. Copyright (c) 2026 Jezweb Pty Ltd.