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.1

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.1
File Size Uploaded Provenance Actions
picle-0.13.1.tar.gz 34.7 kB Without provenance Details for picle-0.13.1.tar.gz

Built distribution (wheel)

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

Total release size: 71.2 kB

Release files / picle-0.13.1.tar.gz

Download URL picle-0.13.1.tar.gz
Size 34.7 kB
Tags Source
SHA-256 checksum
How to use checksums
f7d13d05b9fe074db0bc91fd3c1be5ed6c9b198d3d16575619e76726bf9f31b4
BLAKE2b-256 checksum
How to use checksums
3bdd05530baf09f5638e1a00205b5459390b1cdbe8816821c112e13d0ed51bf4
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.1-py3-none-any.whl

Download URL picle-0.13.1-py3-none-any.whl
Size 36.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
080b8d846633a34a3df598240bf856af6f7212aa911da32e73712e2ca13b0bf6
BLAKE2b-256 checksum
How to use checksums
84e8720f426b816f313d6449aa72fec5dcfe758d728869857bc430598ebddf1f
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.1

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.1 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