Quickstart

Requirements

• Python 3.11+ (from pyproject.toml).
• A local folder where you want your garden files.

Install

python -m venv .venv
. .venv/bin/activate  # Windows PowerShell: .venv\Scripts\Activate.ps1
pip install -e ".[dev]"

If you install from source with the editable command above, the link-garden CLI entry point becomes available.

Create a garden directory

mkdir my-garden
cd my-garden
link-garden init .

This creates data/bookmarks/, data/index.json, and (if missing) a secure config.yaml.

Add your first bookmark

link-garden add --url "https://example.com" --title "Example" --tags "reference,docs"

New bookmarks use default_visibility from config.yaml (secure default: private).

List and search

link-garden list --limit 20
link-garden list --search "example"
link-garden list --tag docs
link-garden list --folder "bookmark_bar/Research"
link-garden list --visibility private

The list command reads from the index, supports filters, and prints tab-separated rows including visibility, tags, folder, and archived state.

Export and serve safely

link-garden export --format html --out ./exports --scope public
link-garden serve --repo-dir . --port 8000

By default, serving binds to 127.0.0.1 and uses public scope unless config/flags say otherwise.