obsinstall

         ▗▄▟██
       ▄█████▛ █▄
      ▐█████▛ ▟███
      ▐████▛ ▟████▌
     ▗ ▜███▎▐█████▌
    ▗█▙ ▜██▎▐██████
   ▗███▙ ▜█▙ ▜█████▙
  ▗█████▙ ▄▄▄▄▃▔▀███▙
  ▝██████ ██████▄ ▜█▘
   ▀████▛ ███████▙ ▘
     ▀█▛ ▟████████▌
        ▝▀▀▀▀████▀

  Obsidian plugin manager

CLI to install and manage Obsidian plugins — from the community registry, a GitHub URL, or a local directory. Zero dependencies.

---

Features

• Install by registry ID — obsinstall add obsidian-kanban — no need to find a GitHub URL
• Install from GitHub — full URL, owner/repo shorthand, or registry ID
• Install from local directory — auto-detects and runs the build if needed
• Update — one plugin or all at once with --all
• Enable / Disable — edits community-plugins.json directly
• Search — queries the official community registry with relevance ranking
• Inspect — info shows version, source, install date, and per-vault status
• List — ps gives a full overview of all vaults and plugins
• Multi-vault — interactive vault picker or --vault <name> flag
• Dry-run mode — preview changes without applying them (--dry-run)
• Robust error handling — timeouts, retries, clear error messages
• Zero dependencies — uses only Node.js built-ins and the native fetch API
• No color / pipe friendly — respects NO_COLOR env var and non-TTY environments

---

Requirements

• Node.js ≥ 18
• Obsidian opened at least once (to initialize vault structure)

---

Installation

npm install -g obsinstall

Or with other package managers:

pnpm add -g obsinstall
yarn global add obsinstall
bun add -g obsinstall

---

Quick Start

# Search the community registry
obsinstall search kanban

# Install a plugin by registry ID (easiest)
obsinstall add obsidian-kanban

# Install using GitHub shorthand
obsinstall add mgmeyers/obsidian-kanban

# Install from a GitHub URL
obsinstall add https://github.com/mgmeyers/obsidian-kanban

# Preview what would be installed (dry-run)
obsinstall add obsidian-kanban --dry-run

# List all installed plugins
obsinstall ps

# Update all plugins
obsinstall update --all

---

Commands

add — Install a plugin

obsinstall add <github-url|registry-id|local-path> [--vault <name>] [--dry-run]

Accepts multiple forms:

Form	Example
Registry ID	obsinstall add obsidian-kanban
GitHub shorthand	obsinstall add mgmeyers/obsidian-kanban
GitHub URL	obsinstall add https://github.com/mgmeyers/obsidian-kanban
Local path	obsinstall add ./my-plugin

• Registry ID — looked up in the official community registry. If multiple matches are found, an interactive picker is shown.
• GitHub shorthand — owner/repo format for quick access.
• GitHub URL — fetches the latest release assets (main.js, manifest.json, styles.css). Falls back to the default branch if no release exists.
• Local path — copies plugin files directly. If main.js is missing, attempts a build (npm run build / bun / pnpm / yarn, auto-detected from lockfile).

After installation, a .obsinstall.json metadata file is written alongside the plugin for future updates.

---

rm — Remove a plugin

obsinstall rm <plugin-id> [--vault <name>] [--dry-run]

Shows which vaults contain the plugin (with enabled/disabled status), then removes it from the selected vault(s).

---

update — Update installed plugins

obsinstall update <plugin-id> [--vault <name>] [--dry-run]
obsinstall update --all       [--vault <name>] [--dry-run]

Compares the installed version against the latest GitHub release using semantic versioning. Only plugins installed via obsinstall (with a .obsinstall.json metadata file) can be updated.

---

enable / disable — Toggle a plugin

obsinstall enable  <plugin-id> [--vault <name>] [--dry-run]
obsinstall disable <plugin-id> [--vault <name>] [--dry-run]

Edits community-plugins.json in the vault's .obsidian directory. Shows the current state per vault and displays the before → after transition.

Note: Reload Obsidian after toggling for the change to take effect.

---

info — Plugin details

obsinstall info <plugin-id>

Displays version, source (GitHub repo or local path), installation and update dates, and enabled/disabled status per vault.

---

search — Search the registry

obsinstall search <query>

Searches the official community plugin registry by plugin ID, name, author, and description. Results are ranked by relevance. Plugins already installed in any vault are marked [installed].

---

ps — List installed plugins

obsinstall ps [--vault <name>]

Shows all installed plugins across all discovered vaults, with their enabled/disabled status and source (GitHub or local).

---

Options

Flag	Shorthand	Description
--vault <name>	-V <name>	Target a specific vault by name or path substring
--dry-run	-n	Preview changes without applying them
--verbose		Show detailed output for debugging
--version	-v	Print version
--help	-h	Show help

The --vault flag works with all commands that operate on a vault. The name is matched case-insensitively against both the vault name and its path.

---

Configuration

Environment Variables

Variable	Description
GITHUB_TOKEN	GitHub API token (increases rate limits from 60 to 5000/hour)
OBSINSTALL_DRY_RUN	Set to 1 to enable dry-run mode globally
OBSINSTALL_VERBOSE	Set to 1 to enable verbose output
NO_COLOR	Set to 1 to disable colored output

GitHub Token

obsinstall uses the GitHub API to fetch releases and repository info. The unauthenticated rate limit is 60 requests/hour. To raise it to 5 000/hour, set a personal access token:

export GITHUB_TOKEN=ghp_your_token_here

A token with no special scopes (public repos only) is sufficient.

Add it to your shell profile (~/.bashrc, ~/.zshrc, etc.) to persist it.

---

Safety Features

Dry-Run Mode

Use --dry-run (or -n) to preview changes without modifying your vaults:

# See what would be installed
obsinstall add obsidian-kanban --dry-run

# Preview plugin updates
obsinstall update --all --dry-run

# See what would be removed
obsinstall rm obsidian-kanban --dry-run

Input Validation

• Plugin IDs are validated to prevent invalid characters
• Paths are checked for directory traversal attempts (../)
• GitHub URLs are parsed and validated

Atomic Operations

Plugin installations use atomic writes (temporary directory + rename) to prevent corruption if the process is interrupted.

Network Resilience

• Timeouts — All network requests have 30s timeout (60s for downloads)
• Retries — Automatic retry on transient failures (5xx errors)
• Rate limiting — Clear error messages when GitHub rate limits are hit

---

Platform Support

Platform	Vault discovery
Linux	$HOME, $XDG_DOCUMENTS_DIR, $XDG_DATA_HOME
macOS	$HOME/Documents, iCloud Obsidian directory
Windows	%USERPROFILE%, %APPDATA%

Vaults are discovered by searching for .obsidian directories up to 6 levels deep. Standard system directories (node_modules, .git, proc, etc.) are skipped.

---

How it works

1. Discovery — vaults are found by recursively scanning common OS paths for .obsidian directories.
2. Install — plugin files are placed in <vault>/.obsidian/plugins/<plugin-id>/. A .obsinstall.json metadata file records the source, version, and timestamp.
3. Update — metadata is read to find the GitHub source, the latest release is fetched, and files are replaced atomically.
4. Enable/Disable — <vault>/.obsidian/community-plugins.json (an array of enabled plugin IDs) is read and rewritten.

---

Troubleshooting

"GitHub API rate limit exceeded"

Set a GITHUB_TOKEN environment variable with a personal access token.

"No Obsidian vaults found"

Make sure Obsidian has been opened at least once to initialize your vault structure. The CLI searches standard locations for .obsidian directories.

"Request timed out"

Check your network connection. The CLI uses a 30-second timeout for API requests.

Enable verbose mode

For debugging, use --verbose or set OBSINSTALL_VERBOSE=1:

obsinstall add obsidian-kanban --verbose

---

License

MIT