lestash

Core CLI and plugin system for Le Stash - a personal knowledge base that aggregates content from multiple sources into a unified, searchable database.

Note: For project overview, features, and quick start guide, see the GitHub repository.

Installation

uv add lestash

Or install the full workspace from the repository root:

uv sync --all-packages

CLI Commands

Items

# List all items (with date/time and resolved author names)
lestash items list

# Filter by source
lestash items list --source linkedin

# Search items
lestash items search "query"

# Show item details (includes reaction/comment target URLs)
lestash items show <id>

# Export items to JSON
lestash items export --output backup.json

# Create a Micro.blog draft from an item
lestash items draft <id> --output ~/blog/content/drafts/

Profiles

Map person URNs (e.g., LinkedIn) to human-readable names and profile URLs:

# Add a profile mapping
lestash profiles add "urn:li:person:abc123" --name "John Doe" --url "https://linkedin.com/in/johndoe"

# List all profiles
lestash profiles list

# Show a specific profile
lestash profiles show "urn:li:person:abc123"

# Remove a profile
lestash profiles remove "urn:li:person:abc123"

When profiles are configured, items list and items search display names instead of URNs, and items show includes the profile URL.

Sources

# List configured sources
lestash sources list

# Sync all sources
lestash sources sync

# View sync history
lestash sources history

Configuration

# Show current config
lestash config show

# Initialize config file
lestash config init

# Set a config value
lestash config set logging.level DEBUG

Plugin Architecture

Le Stash uses entry points for plugin discovery. Plugins implement the SourcePlugin base class:

from lestash.plugins.base import SourcePlugin
from lestash.models.item import ItemCreate

class MySource(SourcePlugin):
    name = "my-source"
    description = "My custom data source"

    def get_commands(self) -> typer.Typer:
        """Return Typer app with source-specific commands."""
        app = typer.Typer()
        # Add commands...
        return app

    def sync(self, config: dict) -> Iterator[ItemCreate]:
        """Fetch items from the source."""
        yield ItemCreate(
            source_type="my-source",
            source_id="unique-id",
            content="Item content",
        )

[project.entry-points."lestash.sources"]
my-source = "my_package:MySource"

Data Model

Item

The core unit of content:

Field	Type	Description
`id`	int	Auto-generated primary key
`source_type`	str	Plugin identifier (e.g., "arxiv", "linkedin")
`source_id`	str	Unique ID within the source
`url`	str	Optional URL to original content
`title`	str	Optional title
`content`	str	Main text content
`author`	str	Optional author
`created_at`	datetime	When the content was created
`is_own_content`	bool	Whether user authored this
`metadata`	dict	Source-specific data (JSON)
`parent_id`	int	Optional FK to parent item (for grouping children)

Database

SQLite database with:

items - Main content table with unique constraint on (source_type, source_id) and optional parent_id for hierarchical grouping
items_fts - Full-text search virtual table (FTS5)
vec_items - Vector embeddings for semantic search (sqlite-vec)
item_history - Audit trail of content changes
person_profiles - URN to name/URL mapping for display
post_cache - Cached metadata for posts referenced by reactions/comments
tags / item_tags - Tagging system
collections / collection_items - Cross-source item grouping
sources - Plugin configuration storage
sync_log - Sync operation history

Configuration

Default location: ~/.config/lestash/config.toml

[general]
database_path = "~/.config/lestash/lestash.db"

[logging]
level = "INFO"
file_path = "~/.config/lestash/logs/lestash.log"

License

MIT

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

lestash-1.64.4.tar.gz (86.3 kB view details)

Uploaded Aug 15, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

lestash-1.64.4-py3-none-any.whl (83.4 kB view details)

Uploaded Aug 15, 2026 Python 3

File details

Details for the file lestash-1.64.4.tar.gz.

File metadata

Download URL: lestash-1.64.4.tar.gz
Upload date: Aug 15, 2026
Size: 86.3 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for lestash-1.64.4.tar.gz
Algorithm	Hash digest
SHA256	`98102dc4391c0e719a1e88a2e358e9e97417c3b04b5fd95db2bc894f552644ef`
MD5	`13916e29e05edf13e7282c371f0da42e`
BLAKE2b-256	`ed4575b5c5c1827ccb006cbbb499bf8c2802724b62554df4716a8c9084e25195`

See more details on using hashes here.

Provenance

The following attestation bundles were made for lestash-1.64.4.tar.gz:

Publisher: release.yml on thompsonson/lestash

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: lestash-1.64.4.tar.gz
- Subject digest: 98102dc4391c0e719a1e88a2e358e9e97417c3b04b5fd95db2bc894f552644ef
- Sigstore transparency entry: 2473561301
- Sigstore integration time: Aug 15, 2026
Source repository:
- Permalink: thompsonson/lestash@64288e063c356c82781db6eafcbb68e1552cb6ec
- Branch / Tag: refs/heads/main
- Owner: https://github.com/thompsonson
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@64288e063c356c82781db6eafcbb68e1552cb6ec
- Trigger Event: push