Code Pills

Code Pills is a curated collection of standalone scripts and reusable snippets. The repository is managed with codepills.py, a standard-library Python CLI for checking metadata, searching entries, copying snippets, importing scripts, and running standalone tools.

Layout

• codepills.py: repository helper CLI.
• python/, bash/, powershell/, javascript/: language-specific scripts.
• */snippets.*: normalized snippet notebooks for each language.

Quick Start

Run commands from the repository root.

git clone git@github.com:octanima-labs/codepills.git codepills
cd codepills
python codepills.py check
python codepills.py ensurepath
python codepills.py search
python codepills.py search --type snippet -t linux
python codepills.py search --type script -t python -D
python codepills.py get py0006
python codepills.py get -c python/pingwave
python codepills.py run python/pingwave --tests

Python Package API

The PyPI package installs only the Python modules as the codepills import package. It does not install the Bash, JavaScript, or PowerShell collections as Python modules, and the repository helper codepills.py remains separate from the package API.

pip install codepills

Use module-first imports:

from codepills.dirinit import create_structure, preview_structure
from codepills.snippets import safe_filename
from codepills.zipperzero import ZipperZero

The package root is intentionally minimal and does not re-export every utility. Documented public names are also declared in each module's __all__. Private helpers, parser builders, test helpers, and CLI internals are importable only as implementation details and are not stable package API.

Supported first-pass imports:

from codepills.dirinit import (
    StructureEntry,
    CreatedEntry,
    parse_structure_file,
    preview_structure,
    create_structure,
)
from codepills.bename import (
    RenamePlan,
    RenameResult,
    preview_renames,
    rename_paths,
    render_name,
)
from codepills.snippets import Cprint, cprint, safe_filename
from codepills.pingwave import (
    PingResult,
    build_ping_command,
    output_shows_all_packets_lost,
    ping_target,
    ping_targets,
    result_line,
    format_file_result,
    format_summary,
    write_output_file,
)
from codepills.massrun import (
    PLACEHOLDERS,
    RunResult,
    has_placeholder,
    substitute_placeholders,
    build_argv_command,
    resolve_cwd,
    find_targets,
    run_for_target,
    run_targets,
    run_matching,
)
from codepills.zipperzero import ZipperZero
from codepills.freezenv import (
    BASE_PACKAGES,
    OUTPUT_FILENAME,
    FreezenvError,
    discover_venv,
    find_site_packages,
    freeze_requirements,
    write_requirements,
    generate_requirements_from_venv,
)
from codepills.browpic import (
    DEFAULT_PORT,
    IMAGE_EXTS,
    MIME_TYPES,
    get_mime,
    create_server,
    serve,
)

To start a fresh Code Pills collection from this toolset:

python codepills.py ensurepath
codepills reset --force
git remote add origin <YOUR_REPO_URL>

CLI

After running python codepills.py ensurepath, examples can use codepills directly instead of python codepills.py in new shell sessions.

Ensure Path

Install the codepills command into the user PATH.

python codepills.py ensurepath

On POSIX systems this makes codepills.py executable, creates a ~/.local/bin/codepills symlink, and adds ~/.local/bin to a shell startup file when needed. On Windows it creates a codepills.cmd shim in %USERPROFILE%\.local\bin and adds that directory to the user PATH.

Reset

Reset the repository into a fresh Code Pills collection.

codepills reset
codepills reset --force

reset empties language folders, recreates empty snippet notebooks, removes the current .git directory, and runs git init. It keeps codepills.py, README.md, and the language folders. It does not configure a remote.

After reset, configure your own remote:

git remote add origin <YOUR_REPO_URL>

Without --force, reset asks for confirmation with a default No answer.

Check

Validate standalone script metadata and normalized snippets.

python codepills.py check

Search

Search scripts and snippets by metadata.

python codepills.py search [--type script|snippet] [-D] [-n NAME] [-d TEXT] [-t TAG] [-p PLATFORM]

• -n, --name: case-insensitive substring match on name/title.
• -d, --description: case-insensitive substring match on description.
• -t, --tag: exact case-insensitive tag match. Can be repeated.
• -p, --platform: exact case-insensitive platform match. Can be repeated.
• --type: restrict results to script or snippet. Can be repeated.
• -D, --details: include description and tags columns.

Multiple filters use AND logic.

Get

Retrieve one or more snippets or standalone scripts.

python codepills.py get py0001
python codepills.py get python/pingwave
python codepills.py get javascript/xda
python codepills.py get py0001 python/pingwave
python codepills.py get -c py0001 javascript/xda

Snippet references use stable IDs such as py0001, sh0001, ps0001, and js0001. Script references use <language>/<name> with an optional extension, such as python/pingwave, python/pingwave.py, javascript/xda, or javascript/xda.js. Bare filenames such as xda.js are not script references.

For snippets, get prints only the snippet content; the ID/header metadata is omitted. For scripts, get prints the absolute path to the resolved script file. When multiple entries are selected, they are separated by two blank lines.

Use -c or --copy to copy retrieved content to the clipboard. Snippets copy the snippet content, while scripts copy the full script file content rather than the displayed path.

Clipboard support uses platform commands when available:

• Linux: wl-copy, xclip, or xsel
• macOS: pbcopy
• Windows: clip or PowerShell Set-Clipboard

If clipboard copy fails, the retrieved display output is still printed.

Run

Run a standalone script and pass through all remaining arguments.

python codepills.py run python/pingwave --tests
python codepills.py run python/zipperzero --self-test
python codepills.py run powershell/barabara -h

The script reference is <language>/<name> with an optional extension. Examples:

• python/pingwave or python/pingwave.py
• bash/swap_file or bash/swap_file.sh
• powershell/barabara or powershell/barabara.ps1
• javascript/xda or javascript/xda.js

run executes standalone scripts only. Snippets are not runnable through this command, and browser JavaScript snippets/scripts are blocked from CLI execution.

Import

Import an existing script into the repository and add metadata when needed.

python codepills.py import /path/to/tool.py
python codepills.py import /path/to/tool.py --name better-name

The destination directory is chosen from the file extension:

• .py -> python/
• .sh -> bash/
• .ps1 -> powershell/
• .js -> javascript/

--name is a filename stem only; the original extension is preserved. Existing destination files are not overwritten.

The generated repo metadata is inferred from git remote origin. If origin is not configured, import fails with a clear error.

Standalone Script Metadata

Every standalone script must start with a parseable CODEPILLS-META header. If a shebang is present, it must remain the first line and the metadata follows it.

Required fields:

• schema: codepills.tool/v1
• name
• version using X.Y.Z
• author
• description
• repo, pointing to the script's public source URL
• license
• usage
• tags
• requires
• platforms

Run python codepills.py check after editing scripts. check requires repo to be present, but it does not require the URL to match the current local origin; imported scripts may preserve their original upstream URLs.

Snippet Format

Snippets live in language-specific snippets.* files. Each snippet has a stable ID, metadata header, and content body.

# ### ID: py0001 ###
# Title: Input multiline values
# Description: Read standard input until an empty line and return all entered lines.
# Tags:
# - input
# - stdin
# Platforms:
# - Linux
# - macOS
# - Windows

def input_multiline():
    ...

ID prefixes are language-specific:

• Python: py0001
• Bash: sh0001
• PowerShell: ps0001
• JavaScript: js0001

IDs are stable once assigned. When adding a snippet, use the lowest available number for that language.

Maintenance

Before committing changes, run:

python codepills.py check

Useful focused checks:

python python/freezenv.py --tests
python python/zipperzero.py --self-test
python python/pingwave.py --tests
bash -n bash/swap_file.sh

Do not execute bash/swap_file.sh as a smoke test unless you intentionally want to modify system swap configuration.