postlocker

name: postlocker description: Manage saved content (links, places, contacts, notes) via the PostLocker CLI (postlocker). Use for saving content, searching (including semantic search), organizing into groups, managing tags, listing/filtering by content type, exporting/importing, and piping commands. Use when the user wants to research, organize places/contacts/links, group similar content, or have the agent organize their PostLocker saves.

What is PostLocker?

PostLocker is a content locker: you save URLs, text, places, contacts, or any content you want to keep. The service stores saves, enriches them with AI-generated metadata (summaries, content type), and lets you search semantically, tag, and group items. The PostLocker CLI (postlocker) is the main way to operate on your saves from the command line or from an agent.

Typical use cases:

• Research: Save articles, links, and notes; search later by meaning (semantic search).
• Organizing places: Save addresses, venue links, or “want to go” spots; group by city, trip, or category.
• Contacts and links: Save people’s profiles, contact pages, or important URLs; tag or group by project/context.
• Grouping similar content: Create groups (e.g. “Unity tutorials”, “Paris restaurants”), then add saves from search or list via piping.
• Agent-driven organization: List or search saves, then add them to groups, add/remove tags, export subsets, or re-analyze with AI.

Install the CLI

Before using this skill, install the PostLocker CLI so the postlocker command is available:

pip install postlocker[cli]

• Library only: pip install postlocker
• Verify: Run postlocker --help. If the command is not found, ensure the Python scripts directory (e.g. Scripts on Windows, bin on Unix) is on your PATH, or set POSTLOCKER_BIN to the full path of the postlocker executable.
• Auth: The CLI manages tokens for you. On first use it will prompt for email/password and store a token under ~/.postlocker/tokens.json (encrypted). Multiple hosts are supported.

Assumptions (after install)

• postlocker CLI is installed and on PATH (or POSTLOCKER_BIN points to it).
• Authentication is handled by the CLI (tokens under ~/.postlocker/).
• Default host is https://api.postlocker.app unless --host or POSTLOCKER_BASE_URL is set.

Safety / operating rules

• Prefer read-only operations first (list, search, groups list, groups get <id>, tags list).
• Before destructive ops (delete, clear, groups rm), confirm the target; use --raw or --pipe to inspect when possible.
• clear deletes ALL saves and groups in the account — use only when the user explicitly intends a full wipe.
• For automation and piping, use --raw (JSON) or --pipe (IDs only where supported).

Main use-case map (questions → commands)

| User / agent goal | Approach | Example command(s) | |-------------------|----------|--------------------| | “What have I saved about X?” | Semantic search (default). | postlocker search "X" or postlocker search "X" --raw | | “List my recent saves” | List with optional limit/since. | postlocker list --limit 20 or postlocker list --since 2025-02-01T00:00:00 | | “Only links” / “Only places” | Filter by content type. | postlocker list --content-type url, postlocker search "cafes" --content-type place | | “Put these in a group” | Use group ID with --add; feed IDs via pipe. | postlocker search "Unity" --pipe \| postlocker groups get "<GROUP_ID>" --add | | “Create a group for Paris trips” | Create group with a name, then add saves. | postlocker groups create "Paris trips" then postlocker groups list --raw to get the new group ID; then postlocker groups get "<ID>" <save_id1> <save_id2> --add | | “What’s in group X?” | Get group contents. | postlocker groups get "<GROUP_ID>" or --raw / --pipe | | “Remove this save from a group” | groups get with --delete. | postlocker groups get "<GROUP_ID>" "<SAVE_ID>" --delete | | “Tag all search results as project-X” | Pipe search IDs; for tags you need to call tags add per save (no bulk pipe). | postlocker search "API docs" --pipe → then for each ID: postlocker tags add <save_id> project-X (or use a small script). | | “Export my saves” | Export all or a subset. | postlocker export -o backup.json or postlocker search "important" --pipe \| postlocker export -o important.json | | “Re-analyze saves for better summaries” | AI analyse (single or piped). | postlocker list --limit 10 --pipe \| postlocker ai analyse | | “Save this link with a note and tags” | Save with options. | postlocker save "https://..." --note "Read later" -T reading -G "<group_id>" |

Use cases (primary)

1. Save content

• Command: postlocker save <content> [--note TEXT] [-T tag] [-G group_id] [--host URL]
• content is the main payload (URL, text, etc.). Optional: --note, -T (repeat for multiple tags), -G (repeat for multiple groups).
• Example: postlocker save "https://example.com/article" --note "Review for project" -T research -G "550e8400-e29b-41d4-a716-446655440000"

2. Search (semantic and keyword)

• Command: postlocker search <query> [--limit N] [--semantic/--no-semantic] [--distance FLOAT] [--group NAME] [-c CONTENT_TYPE] [--raw] [--summary] [--pipe] [--host]
• Default is semantic search. Use --raw for JSON, --pipe for IDs only (for piping to delete, export, groups get --add, ai analyse).
• Filter by group: --group "<group_name_or_id>"; by type: -c / --content-type.

3. List saves

• Command: postlocker list [--limit N] [--offset N] [--since ISO_DATETIME] [-c CONTENT_TYPE] [--raw] [--summary] [--pipe] [--host]
• --since: only saves/groups updated since that date (ISO, timezone-aware or UTC). Useful for sync or “what changed”.

4. Groups: list, create, get (view/add/remove), delete

• List groups: postlocker groups list [--raw] [--host]
• Search groups by name: postlocker groups search <query> [--limit N] [--offset N] [--host] [--raw]
• Create group: postlocker groups create <name> [--host] — requires a group name. The CLI does not print the new group ID; use groups list --raw to get IDs.
• Get group (view or modify):
  postlocker groups get <GROUP_ID> [SAVE_IDS...] [--add \| --delete] [--raw] [--pipe] [--limit N] [--offset N] [--summary] [--host]
  • View: postlocker groups get "<GROUP_ID>"
  • Add saves: postlocker groups get "<GROUP_ID>" id1 id2 --add or pipe: postlocker search "X" --pipe \| postlocker groups get "<GROUP_ID>" --add
  • Remove: postlocker groups get "<GROUP_ID>" id1 --delete
  • --add and --delete cannot be used together.
• Delete group: postlocker groups rm <GROUP_ID> [--host]

5. Tags

• List tags: postlocker tags list [--raw] [--host]
• Get saves by tag: postlocker tags get <tag> [--raw] [--host]
• Add tag: postlocker tags add <save_id> <tag> [--host]
• Remove tag: postlocker tags remove <save_id> <tag> [--host]

6. Export / import

• Export: postlocker export [-o FILE] [-f json|csv] [--pretty] [--limit N] [--offset N] [--host]
  With piped IDs: postlocker search "X" --pipe | postlocker export -o out.json
• Import: postlocker import <csv_file> [--delay SEC] [--limit N] [--offset N] [--pipe] [--host]
  Import then add to group: postlocker import data.csv --pipe | postlocker groups get "<GROUP_ID>" --add

7. AI

• Re-analyze one or more saves: postlocker ai analyse [--host] [--raw] [--summary] (reads save IDs from stdin when piping).
  Example: postlocker list --limit 5 --pipe | postlocker ai analyse
• Re-analyze all: postlocker ai all [--delay SEC] [--limit N] [--offset N] [--host] — options use -d for delay, -l for limit, -s for offset.

8. Single save: get, delete

• Get by ID: postlocker get <save_id> [--host] (output is JSON).
• Related saves: postlocker related <save_id> [--limit N] [--distance FLOAT] [--host] [--raw] — semantically related saves.
• Delete by ID: postlocker delete <save_id> [--host]. With pipe: postlocker search "obsolete" --pipe | postlocker delete

Notes on saves: postlocker notes get <save_id>, postlocker notes add <save_id> <note>, postlocker notes delete <save_id> <note_id> (see references/cli.md).

Command piping

Commands that support --pipe (output save IDs only):

• list
• search
• groups get (when listing group contents)
• import (after importing)

Commands that accept piped IDs:

• delete
• ai analyse
• export
• groups get --add

Examples:

• Delete all saves matching a search: postlocker search "Football" --pipe | postlocker delete
• Add search results to a group: postlocker search "Unity" --pipe | postlocker groups get "1218471-1248917-12410897f34" --add
• Export search results: postlocker search "important" --pipe | postlocker export -o important.json
• Re-analyze first 10 saves: postlocker list --limit 10 --pipe | postlocker ai analyse

On Windows PowerShell, use | (no backslash). One-line:
postlocker search "Unity" --pipe | postlocker groups get "1218471-1248917-12410897f34" --add

Organizing saves (agent workflow)

1. Discover: Use list or search (with --content-type if the user cares about links vs places vs generic). Use --raw to parse programmatically.
2. Group similar content: Create a group with groups create, then add saves via groups get <id> ... --add or by piping search/list output.
3. Tag for context: Use tags add for individual saves (no bulk pipe for tags; iterate over IDs if needed).
4. Export subsets: Use search or groups get with --pipe into export -o file.json for backup or analysis.
5. Clean up: Use search or list to identify candidates, then delete (with confirmation) or groups get ... --delete to remove from a group.

Quick checks

• Who am I: run a command that requires auth (e.g. postlocker list --limit 1) or use postlocker users me --raw if available.
• Tokens: postlocker tokens list, postlocker tokens clear

Common options (global)

• --host: PostLocker base URL (default https://api.postlocker.app).
• --raw: Output raw JSON.
• --summary: Show AI-generated summaries (list, search).
• --limit / --offset: Paging for list, search, export, etc.

Scripts

• postlocker_run.py — UTF-8 + POSTLOCKER_BIN shim:
  python scripts/postlocker_run.py -- list --limit 5 --raw
• postlocker_api.py — Helpers to run CLI and parse JSON (list, search, groups get, etc.) for scripted workflows.

References

• references/cli.md — Full CLI command and option reference.