Skip to main content

Downloads PyPI PyPI versions Code style: black Tests

logo PICLE - Python Interactive Command Line Shells

PICLE helps you build interactive CLI shells from Pydantic v2 models. Think of it as: your model tree becomes the command tree.

Built on top of Python's standard library CMD module, prompt_toolkit for interactive input, and Pydantic models to construct shell environments.

What you get out of the box:

  • command discovery + inline help (? / ??)
  • tab completion (works well with nested commands)
  • editable, persistent command history
  • input validation via Pydantic
  • optional pipes (|) to post-process output

Docs: https://dmulyalin.github.io/picle/

Install

pip install picle

Optional extras (Rich output, tables, YAML config support):

pip install "picle[full]"

A tiny shell app

This creates a small interactive shell:

Root
  └─ show
     ├─ version
     └─ clock
import time
from typing import Any

from pydantic import BaseModel, Field
from picle import App


class Show(BaseModel):
    version: Any = Field(
        None,
        description="Show software version",
        json_schema_extra={"function": "show_version"},
    )
    clock: Any = Field(
        None,
        description="Show current clock",
        json_schema_extra={"function": "show_clock"},
    )

    @staticmethod
    def show_version():
        return "0.1.0"

    @staticmethod
    def show_clock():
        return time.ctime()


class Root(BaseModel):
    show: Show = Field(None, description="Show commands")

    class PicleConfig:
        prompt = "picle#"
        intro = "PICLE sample app"


if __name__ == "__main__":
    App(Root).start()

Try it:

picle#show version
0.1.0

picle#show clock
Fri May  2 22:44:01 2025

picle#?
... shows available commands

Comparison With Other Projects

PICLE is not trying to replace every CLI library. It’s mostly for the “network device / DB console / ops shell” style workflow: you stay in a shell, you explore commands, you get completion + help, and your input is validated.

Some nearby tools and where PICLE fits:

One-shot CLI command frameworks

Great when you want mytool subcommand --flags and exit.

  • argparse: batteries-included, stable, not interactive by default.
  • click / typer: excellent UX for subcommands/options, but still “run once and exit”.
  • python-fire: fast to expose a Python object as CLI, but it’s not focused on interactive shells, completion, or validation the way a model-driven shell is.

You can build REPL-like flows with these, but PICLE starts from the REPL/shell side.

Interactive shell / REPL frameworks

  • Python’s built-in cmd: the base that PICLE builds on.
  • cmd2: adds a lot of features on top of cmd (nice project). PICLE’s angle is different: it uses Pydantic models as the command tree, so completion/help/validation all come from the schema.
  • python-nubia (archived): similar “interactive shell” spirit, but the project is not maintained and doesn’t integrate with Pydantic.

TUI / input toolkits

  • prompt-toolkit: PICLE uses it for portable line editing, history, and terminal input. PICLE adds the model-driven command tree, parsing, help, completion rules, validation, and dispatch.
  • textual: awesome for full-screen TUIs (apps, dashboards). Different goal than a command shell.

Output formatting helpers

PICLE can use these (optionally) but doesn’t depend on them:

  • rich: pretty output rendering
  • tabulate: text tables
  • PyYAML: YAML config support (used by ConfigModel)

Metadata

Release files for picle 0.13.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for picle 0.13.2
File Size Uploaded Provenance Actions
picle-0.13.2.tar.gz 35.3 kB Without provenance Details for picle-0.13.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for picle 0.13.2
File Interpreter ABI Platform Actions
picle-0.13.2-py3-none-any.whl Python 3 none any Details for picle-0.13.2-py3-none-any.whl

Total release size: 72.4 kB

Release files / picle-0.13.2.tar.gz

Download URL picle-0.13.2.tar.gz
Size 35.3 kB
Tags Source
SHA-256 checksum
How to use checksums
df609393822d91b43ead9a69b4419d9c7d34b00a8d23d0eda5968bfbfe4b1ccc
BLAKE2b-256 checksum
How to use checksums
c3074457919a6ae8b785f50ec3cd01931b8ae0f80768dd8d1854a302f6dad959
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.2.1 CPython/3.11.9 Windows/10

Release files / picle-0.13.2-py3-none-any.whl

Download URL picle-0.13.2-py3-none-any.whl
Size 37.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
476c155165a6a7507e07e97b2d803551ecbb379258e3bb782d1522f69b3c3fb3
BLAKE2b-256 checksum
How to use checksums
ae780ec79294c461ca6b36e362ddb15f71b480330f1802d584079cf0bf182c5f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.2.1 CPython/3.11.9 Windows/10

Security for picle 0.13.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.13.2 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page