{"id":8415,"library":"pickley","title":"Pickley","description":"Pickley is a Python library and CLI tool designed to automate the installation and management of standalone Python command-line interfaces (CLIs). It functions similarly to pipx, but with the key difference that installed CLIs automatically self-upgrade upon use. Pickley is portable and aims for zero-configuration, installing CLIs within the same directory it resides, supporting any PyPI package with console_scripts entry points. The current version is 4.6.1, and it maintains a regular release cadence with frequent updates as seen in its GitHub release history.","status":"active","version":"4.6.1","language":"en","source_language":"en","source_url":"https://github.com/codrsquad/pickley","tags":["CLI management","package manager","python tools","automation","self-updating"],"install":[{"cmd":"pip install pickley","lang":"bash","label":"Standard pip installation"},{"cmd":"uvx pickley bootstrap ~/.local/bin","lang":"bash","label":"Bootstrap Pickley with uv (recommended for portability)"},{"cmd":"curl -fsSL https://raw.githubusercontent.com/codrsquad/pickley/main/src/pickley/bstrap.py | /usr/bin/python3 -","lang":"bash","label":"One-liner to install Pickley (e.g., in ~/.local/bin)"}],"dependencies":[],"imports":[{"note":"While pickley is primarily a CLI tool, it can be imported for programmatic access to its functionalities.","symbol":"pickley","correct":"import pickley"}],"quickstart":{"code":"import os\n\n# Ensure ~/.local/bin is in PATH for pickley to be found\n# This is a common setup for CLI tools\n# For a true quickstart, users would typically install via the bash commands above\n# and then use `pickley` directly in their shell.\n# This Python quickstart demonstrates programmatic interaction if needed.\n\n# Example of using pickley programmatically (less common for its primary use-case)\n# For CLI, you'd run commands like 'pickley install tox'\n\n# This is a placeholder as direct programmatic API isn't extensively documented\n# on PyPI/GitHub for installing other CLIs. The core functionality is via shell.\n# For the purpose of this registry, showing CLI usage is more accurate.\n# We simulate the shell interaction for clarity.\n\n# Assuming pickley is installed and in PATH\n# The actual Python API would be more involved than a simple 'import pickley'\n# and would likely involve calling internal functions or a main entry point.\n# For a quickstart focusing on its primary use:\n\nprint(\"To install a CLI like 'tox':\")\nprint(\"$\" + \" pickley install tox\")\nprint(\"To run an installed CLI:\")\nprint(\"$\" + \" tox --version\")\nprint(\"To install a specific version:\")\nprint(\"$\" + \" pickley install 'hatch<2'\")","lang":"python","description":"Pickley is primarily used as a command-line interface. After installation, you can use the `pickley` command to install and manage other Python CLIs. The example demonstrates how to install a tool like 'tox' and 'hatch' and then run it, reflecting its main utility. While it can be imported, its core functionality is exposed via the shell commands."},"warnings":[{"fix":"Ensure the directory where `pickley` is installed (e.g., `~/.local/bin`) is included in your system's PATH environment variable. For example: `export PATH=\"$HOME/.local/bin:$PATH\"` (add to your shell's rc file).","message":"Pickley is portable and installs CLIs in the same directory it resides. If `~/.local/bin` (or equivalent) is not in your system's PATH, CLIs installed by pickley may not be directly executable from any shell session.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For production environments or sensitive workflows, always pin the exact version or a strict version range when installing CLIs using `pickley install 'package==X.Y.Z'` or `pickley install 'package~=X.Y'`. Use `pickley list -v` to check installed versions and `pickley describe <package>` for spec details.","message":"Pickley's automatic self-upgrade feature for installed CLIs can sometimes lead to unexpected version changes if strict version pinning is not used. This might break scripts or workflows expecting a specific tool version.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If precise control over versions is required, explicitly use `pickley install 'package==X.Y.Z'` before `pickley run <package>`. Review your `pickley config` to understand default behaviors for auto-installation.","message":"When running a command via `pickley run <command>`, Pickley will auto-install the CLI if it's not present. This can lead to implicit installations, potentially using the latest version which might introduce incompatibilities.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Add the pickley installation directory (e.g., `~/.local/bin`) to your system's PATH. For example, `export PATH=\"$HOME/.local/bin:$PATH\"` and add this to your shell profile (e.g., `.bashrc`, `.zshrc`).","cause":"The directory where pickley installs CLIs is not in your shell's PATH environment variable.","error":"command not found: <cli-tool-installed-via-pickley>"},{"fix":"When installing, specify a precise version or range: `pickley install 'cli-tool==A.B.C'` or `pickley install 'cli-tool<=(A.B.C)'`. Regularly check installed versions with `pickley list`.","cause":"Pickley automatically upgrades installed CLIs to their latest non-prerelease version upon use or `pickley upgrade`, leading to unexpected version bumps.","error":"Installed <cli-tool> vX.Y.Z, but my script requires vA.B.C and is failing."},{"fix":"Install pickley using `pip install pickley` or one of the bootstrap methods, and ensure the installation target directory is in your PATH.","cause":"Pickley itself is not installed or its installation directory is not in your PATH.","error":"pickley: command not found"}]}