postlocker 1.0.0

Python SDK and CLI for PostLocker API - Save, search, organize content into groups, manage tags and user accounts.

PostLocker CLI

PostLocker CLI is a command-line interface tool designed to help you manage your saved content efficiently. With PostLocker, you can save, delete, search, and organize your content into groups, manage tags, and handle user accounts.

Table of Contents

• PostLocker CLI
  • Table of Contents
  • Installation
    • From Source
    • From PyPI
  • Usage
  • Commands
    • Common options
    • Tokens
    • Content Management
    • Groups
    • Users
    • Tags
    • AI Features
    • Command Piping
  • Admin Privileges

Installation

From Source

1. Clone the repository:

   git clone https://github.com/yourusername/postlocker-cli.git
   cd postlocker-cli
   

2. Install the dependencies:

   pip install -r requirements.txt
   

3. Install the package (add [cli] for the CLI):

   pip install .[cli]
   

From PyPI

• Library only: pip install postlocker
• Library + CLI: pip install postlocker[cli]

Usage

Once installed, you can use the postlocker command to interact with the CLI. Use postlocker --help to see the available commands and options.

Commands

Common options

--host : Pick the base PostLocker host (defaults to production https://api.postlocker.app)

--raw : Print the results as raw JSON from the API

--summary : Show AI-generated summaries for content (available in list and search commands)

--limit: Limit the amount of results listed, list the first X items. (use with --offset to create paging)

--offset: start the listing after skipping the first X items (use with --limit to create paging)

Tokens

The CLI tool will manage your tokens for you, if there are no tokens, all commands will securely ask you for your username and password before executing and store a token for you while it's still valid. You can cache multipe tokens for different hosts.

Tokens are safely encrypted and saved hidden in your home folder ~/.postlocker/tokens.json

• tokens clear: Clear all cached tokens.
• tokens list: List all cached tokens.

Content Management

• save: Save content to PostLocker.
  • Options: --title, --description, --tags, --host
• delete: Delete content from PostLocker by ID.
  • Options: --host
• list: List all saved content.
  • Options: --host, --raw, --summary, --pipe, --limit, --offset, --since, --content-type
  • Note: The --since option takes an ISO formatted datetime (timezone aware or UTC asumed if naive) and outputs all the saves and groups that have been updated since that date and all deleted objects (saves and groups). If it's combined with --pipe or --raw it will only output the updated saves.
  • The --content-type option filters saves by their content type
• get: Get content by ID.
  • Options: --host
• search: Search saved content.
  • Options: --limit, --semantic, --distance, --host, --raw, --summary, --pipe, --content-type
  • The --content-type option filters search results by their content type
• export: Export saved content to JSON or CSV format.
  • Options: --output, --format, --host, --pretty, --limit, --offset
• import: Import content from a CSV file.
  • Options: --host, --delay, --limit, --offset, --pipe
• clear: Delete ALL saves and groups from your account (WARNING: DESTRUCTIVE ACTION).
  • Options: --host

Groups

• groups list: List all content groups.
  • Options: --host, --raw
• groups get ID [SAVE_IDS]: Get content from a specific group or modify group contents.
  • Options:
    • --add, -a: Add the specified save IDs to this group
    • --delete, -d: Remove the specified save IDs from this group
    • --host, -h: PostLocker host URL
    • --raw: Display full JSON data
    • --pipe: Output only save IDs for piping
    • --limit, -l: Limit the number of saves to display
    • --offset, -s: Number of saves to skip
    • --summary: Show AI summary for each save
  • Note: --add and --delete cannot be used together
  • Examples:
    • View group contents: postlocker groups get "550e8400-e29b-41d4-a716-446655440000"
    • Add saves to group: postlocker groups get "550e8400-e29b-41d4-a716-446655444020" "123" "456" --add
    • Remove from group: postlocker groups get "8a7b3c4d-5e6f-7g8h-9i0j-123456789abc" "123" --delete
    • Pipe search results to group: postlocker search "topic" --pipe | postlocker groups get "9b8a7c6d-5e4f-3g2h-1i0j-abcdef123456" --add
• groups create: Create a new group.
  • Options: --host
• groups rm: Delete a group.
  • Options: --host

Users

• users me: Get current user information.
  • Options: --host, --raw
• users list: List all users (admin only).
  • Options:
    • --host: PostLocker host URL
    • --raw: Display full JSON data
    • --limit, -l: Limit the number of users to display
    • --offset, -o: Number of users to skip
    • --include-length: Include the number of saves for each user in the output
• users create: Create a new user or batch create users from piped input.
  • Options:
    • --host: PostLocker host URL
    • --pipe: Read email addresses from standard input
    • --yes, -y: Automatically generate passwords without prompting
    • --delay: Delay in seconds between creating users in batch (default: 0.5)
  • Examples:
    • Create single user (will prompt for password): ```bash postlocker users create ```
    • Create multiple users from a file with auto-generated passwords: ```bash cat accounts.txt | postlocker users create --pipe -y ```
    • Create users with custom delay between creations: ```bash cat accounts.txt | postlocker users create --pipe -y --delay 1.0 ```
  • Note: When not using --yes, passwords are securely prompted and require confirmation (leave empty to auto generate). With --yes, passwords are automatically generated and displayed.
• users set-admin: Set user as admin.
  • Options: --host
• users set-active: Set user as active.
  • Options: --host
• users reset-password: Reset user password.
  • Options: --host
  • Note: Passwords are securely prompted and require confirmation.

Tags

• tags list: List all tags.
  • Options: --host, --raw
• tags get: Get saves by tag.
  • Options: --host, --raw
• tags add: Add a tag to a save.
  • Options: --host
• tags remove: Remove a tag from a save.
  • Options: --host

AI Features

• ai analyse: Re-analyze a specific save or piped saves to update AI metadata.
  • Options: --host, --raw, --summary
• ai all: Re-analyze all saves to update AI metadata.
  • Options: --delay, --limit, --offset, --host

Command Piping

PostLocker CLI supports piping between commands, allowing you to chain operations together. Commands that list or search content can pipe their results to commands that operate on individual saves.

Examples:

• Delete all posts related to "Football":

  postlocker search "Football" --pipe | postlocker delete
  

• Analyze the first 10 saves:

  postlocker list --limit 10 --pipe | postlocker ai analyse
  

• Add all Unity-related posts to a group (by id):

  postlocker search "Unity" --pipe | postlocker groups get -a "1218471-1248917-12410897f34"
  

• Export specific search results:

  postlocker search "important" --pipe | postlocker export -o important.json
  

• Import saves and add them to the "Newly imported" group (by id):

  postlocker import data.csv --pipe | postlocker groups get "1209145-158-13258-91851f" -a
  

Commands that support --pipe output:

• list: List all saves
• search: Search for saves
• groups get: List saves in a group
• import: After importing saves

Commands that accept piped input:

• delete: Delete saves
• ai analyse: Analyze saves
• export: Export specific saves
• groups get --add: Add saves to a group

Admin Privileges

Certain commands require admin privileges, such as managing users (users list, users set-admin, users set-active, users reset-password). Ensure you have the necessary permissions to execute these commands.

For more detailed information on each command, use the --help option with the command, e.g., postlocker groups get --help.