Pickley

4.6.1 · active · verified Thu Apr 16

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.

Common errors

```
command not found: <cli-tool-installed-via-pickley>
```
cause The directory where pickley installs CLIs is not in your shell's PATH environment variable.

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`).
```
Installed <cli-tool> vX.Y.Z, but my script requires vA.B.C and is failing.
```
cause Pickley automatically upgrades installed CLIs to their latest non-prerelease version upon use or `pickley upgrade`, leading to unexpected version bumps.

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`.
```
pickley: command not found
```
cause Pickley itself is not installed or its installation directory is not in your PATH.

fix Install pickley using `pip install pickley` or one of the bootstrap methods, and ensure the installation target directory is in your PATH.

Warnings

gotcha 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.
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).
gotcha 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.
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.
gotcha 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.
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.

Install

pip install pickley Standard pip installation
uvx pickley bootstrap ~/.local/bin Bootstrap Pickley with uv (recommended for portability)
curl -fsSL https://raw.githubusercontent.com/codrsquad/pickley/main/src/pickley/bstrap.py | /usr/bin/python3 - One-liner to install Pickley (e.g., in ~/.local/bin)

Imports

pickley
```
import pickley
```
While pickley is primarily a CLI tool, it can be imported for programmatic access to its functionalities.

Quickstart

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.

import os

# Ensure ~/.local/bin is in PATH for pickley to be found
# This is a common setup for CLI tools
# For a true quickstart, users would typically install via the bash commands above
# and then use `pickley` directly in their shell.
# This Python quickstart demonstrates programmatic interaction if needed.

# Example of using pickley programmatically (less common for its primary use-case)
# For CLI, you'd run commands like 'pickley install tox'

# This is a placeholder as direct programmatic API isn't extensively documented
# on PyPI/GitHub for installing other CLIs. The core functionality is via shell.
# For the purpose of this registry, showing CLI usage is more accurate.
# We simulate the shell interaction for clarity.

# Assuming pickley is installed and in PATH
# The actual Python API would be more involved than a simple 'import pickley'
# and would likely involve calling internal functions or a main entry point.
# For a quickstart focusing on its primary use:

print("To install a CLI like 'tox':")
print("$" + " pickley install tox")
print("To run an installed CLI:")
print("$" + " tox --version")
print("To install a specific version:")
print("$" + " pickley install 'hatch<2'")

view raw JSON →