{"id":15441963,"url":"https://github.com/sander76/clipstick","last_synced_at":"2025-12-28T08:08:58.721Z","repository":{"id":196657668,"uuid":"696857831","full_name":"sander76/clipstick","owner":"sander76","description":"create cli applications using pydantic models","archived":false,"fork":false,"pushed_at":"2024-06-25T11:05:16.000Z","size":3103,"stargazers_count":29,"open_issues_count":8,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-01T19:46:05.859Z","etag":null,"topics":["cli","click","commandline","pydantic","typer"],"latest_commit_sha":null,"homepage":"https://sander76.github.io/clipstick/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sander76.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-09-26T15:04:50.000Z","updated_at":"2024-12-30T22:28:35.000Z","dependencies_parsed_at":null,"dependency_job_id":"ff9972a5-bcfb-4a76-9ce0-8ff357c6ecd4","html_url":"https://github.com/sander76/clipstick","commit_stats":null,"previous_names":["sander76/beta","sander76/clipstick"],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sander76%2Fclipstick","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sander76%2Fclipstick/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sander76%2Fclipstick/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sander76%2Fclipstick/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sander76","download_url":"https://codeload.github.com/sander76/clipstick/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":236085430,"owners_count":19092545,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","click","commandline","pydantic","typer"],"created_at":"2024-10-01T19:24:43.378Z","updated_at":"2025-10-11T11:30:26.666Z","avatar_url":"https://github.com/sander76.png","language":"Python","funding_links":[],"categories":["Command-Line Interface"],"sub_categories":[],"readme":"![coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/sander76/a25f1e6bfcb3b085ffe05f520b56e43c/raw/covbadge.json)\n[![PyPI - Version](https://img.shields.io/pypi/v/clipstick.svg?logo=pypi\u0026label=PyPI\u0026logoColor=gold)](https://pypi.org/project/clipstick/)\n[![code style - black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![types - Mypy](https://img.shields.io/badge/types-Mypy-blue.svg)](https://github.com/ambv/black)\n\n\u003c!-- begin index --\u003e\n\nCreate your cli using Pydantic models.\n\nDefine a pydantic model as you would normally do, pass it to clipstick and you get a cli including subcommands, nice docstrings and validations based on typing and pydantic validators.\n\n## Installation\n\n`pip install clipstick`\n\n\n\n## Example\n\nCreate a pydantic model as you would normally do.\n\n```python\nfrom pydantic import BaseModel\n\nfrom clipstick import parse\n\n\nclass MyName(BaseModel):\n    \"\"\"What is my name.\n\n    In case you forgot I will repeat it x times.\n    \"\"\"\n\n    name: str\n    \"\"\"Your name.\"\"\"\n\n    age: int = 24\n    \"\"\"Your age\"\"\"\n\n    repeat_count: int = 10\n    \"\"\"How many times to repeat your name.\"\"\"\n\n    def main(self):\n        for _ in range(self.repeat_count):\n            print(f\"Hello: {self.name}, you are {self.age} years old\")\n\n\nif __name__ == \"__main__\":\n    model = parse(MyName)\n    model.main()\n\n```\n\nThat's it. The clipstick parser will convert this into a command line interface based on the properties assigned to the model, the provided typing and docstrings.\n\nSo `python examples/name.py -h` gives you nicely formatted (and colored) output:\n\n![help_output](https://raw.githubusercontent.com/sander76/clipstick/main/docs/_images/name-help.svg)\n\nAnd use your cli `python examples/name.py superman --repeat-count 4`:\n\n![usage output](https://raw.githubusercontent.com/sander76/clipstick/main/docs/_images/name-output.svg)\n\nThe provided annotations define the type to which your arguments need to be converted.\nIf you provide a value which cannot be converted you will be presented with a nice error:\n\n`python examples/name.py superman --age too-old`\n\n![wrong age](https://raw.githubusercontent.com/sander76/clipstick/main/docs/_images/name-wrong-age.svg)\n\n\u003e The inclusion of the `def main(self)` method is not a requirement. `clipstick` generates a pydantic model based on provided cli arguments and gives it back to you for your further usage. Using `def main()` is one of the options to further process it.\n\n## Why?\n\nThere are many other tools out there that do kind of the same, \nbut they all don't do quite exactly what I want.\n\nThe goal of clipstip is to use pydantic to model your cli by leveraging:\n\n- The automatic casting of input variables.\n- The powerful validation capabilities.\n- Docstrings as cli documentation.\n- No other mental model required than Typing and Pydantic.\n\nClipstick is inspired by [tyro](https://brentyi.github.io/tyro/), which is excellent and more versatile than this tool. But in my opionion its primary focus is not building a cli tool along the lines of Argparse or Click but more on composing complex objects from the command line. Making tyro behave like a \"traditional\" cli requires additional `Annotation` flags, which I don't want.\n\nSome other similar tools don't support pydantic v2, so I decided to create my own. Next to that I wanted to try and build my own parser instead of using `Argparse` because... why not.\n\n\u003c!-- end index --\u003e\n\nFor more information visit the [documentation](https://sander76.github.io/clipstick/index.html)\n\n## Development\n\nPull requests are very much appreciated!\nSome guidance:\n\n- Fork this repo and use this to create your branch based on the `dev` branch.\n- This project makes use of **Poetry**. `Poetry install` to install everything\n    need for development.\n- This project makes use of **Nox**. `nox -s test` and `nox -s quality` are your friends here.\n- Please update the `CHANGELOG.md` file with your changes under `## [Unreleased]` section.\n- When finished, point your pull-request towards the `dev` dev branch.\n\nThanks!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsander76%2Fclipstick","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsander76%2Fclipstick","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsander76%2Fclipstick/lists"}