{"id":13486559,"url":"https://github.com/nat-n/poethepoet","last_synced_at":"2026-02-08T22:04:22.214Z","repository":{"id":38017535,"uuid":"267704930","full_name":"nat-n/poethepoet","owner":"nat-n","description":"A task runner that works well with poetry or uv.","archived":false,"fork":false,"pushed_at":"2025-11-24T19:47:36.000Z","size":8458,"stargazers_count":1919,"open_issues_count":22,"forks_count":71,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-12-21T20:49:06.993Z","etag":null,"topics":["developer-tools","development-workflow","poetry","poetry-plugin","python","task-runner","uv"],"latest_commit_sha":null,"homepage":"https://poethepoet.natn.io/","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/nat-n.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.rst","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["nat-n"],"custom":"https://www.buymeacoffee.com/natn"}},"created_at":"2020-05-28T21:56:22.000Z","updated_at":"2025-12-21T19:32:51.000Z","dependencies_parsed_at":"2023-09-28T00:00:48.977Z","dependency_job_id":"96be0eef-b611-4ab3-a0e4-2f15235d7446","html_url":"https://github.com/nat-n/poethepoet","commit_stats":{"total_commits":274,"total_committers":38,"mean_commits":"7.2105263157894735","dds":"0.25912408759124084","last_synced_commit":"a4702d86d485afa8055ffe610a425541313d5dfb"},"previous_names":[],"tags_count":74,"template":false,"template_full_name":null,"purl":"pkg:github/nat-n/poethepoet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nat-n%2Fpoethepoet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nat-n%2Fpoethepoet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nat-n%2Fpoethepoet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nat-n%2Fpoethepoet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nat-n","download_url":"https://codeload.github.com/nat-n/poethepoet/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nat-n%2Fpoethepoet/sbom","scorecard":{"id":675003,"data":{"date":"2025-08-11","repo":{"name":"github.com/nat-n/poethepoet","commit":"9c582c8d25b72b90c509e844930061681825045c"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":4.6,"checks":[{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Code-Review","score":1,"reason":"Found 3/30 approved changesets -- score normalized to 1","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Maintained","score":10,"reason":"15 commit(s) and 11 issue activity found in the last 90 days -- score normalized to 10","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: jobLevel 'contents' permission set to 'write': .github/workflows/ci.yml:140","Warn: no topLevel permission defined: .github/workflows/ci.yml:1","Warn: no topLevel permission defined: .github/workflows/publish-docs.yml:1"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Binary-Artifacts","score":7,"reason":"binaries present in source code","details":["Warn: binary detected: tests/fixtures/packages/cowpy-1.1.5-py3-none-any.whl:1","Warn: binary detected: tests/fixtures/packages/poetry-1.8.2-py3-none-any.whl:1","Warn: binary detected: tests/fixtures/packages/poetry-2.0.0-py3-none-any.whl:1"],"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:79: update your workflow using https://app.stepsecurity.io/secureworkflow/nat-n/poethepoet/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:84: update your workflow using https://app.stepsecurity.io/secureworkflow/nat-n/poethepoet/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:93: update your workflow using https://app.stepsecurity.io/secureworkflow/nat-n/poethepoet/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:110: update your workflow using https://app.stepsecurity.io/secureworkflow/nat-n/poethepoet/ci.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:116: update your workflow using https://app.stepsecurity.io/secureworkflow/nat-n/poethepoet/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:145: update your workflow using https://app.stepsecurity.io/secureworkflow/nat-n/poethepoet/ci.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:150: update your workflow using https://app.stepsecurity.io/secureworkflow/nat-n/poethepoet/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:21: update your workflow using https://app.stepsecurity.io/secureworkflow/nat-n/poethepoet/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:26: update your workflow using https://app.stepsecurity.io/secureworkflow/nat-n/poethepoet/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:55: update your workflow using https://app.stepsecurity.io/secureworkflow/nat-n/poethepoet/ci.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:58: update your workflow using https://app.stepsecurity.io/secureworkflow/nat-n/poethepoet/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:63: update your workflow using https://app.stepsecurity.io/secureworkflow/nat-n/poethepoet/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/publish-docs.yml:15: update your workflow using https://app.stepsecurity.io/secureworkflow/nat-n/poethepoet/publish-docs.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/publish-docs.yml:20: update your workflow using https://app.stepsecurity.io/secureworkflow/nat-n/poethepoet/publish-docs.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/publish-docs.yml:32: update your workflow using https://app.stepsecurity.io/secureworkflow/nat-n/poethepoet/publish-docs.yml/main?enable=pin","Info:   0 out of  11 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   4 third-party GitHubAction dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Signed-Releases","score":8,"reason":"5 out of the last 5 releases have a total of 5 signed artifacts.","details":["Info: signed release artifact: poethepoet-0.37.0-py3-none-any.whl.sigstore.json: https://github.com/nat-n/poethepoet/releases/tag/v0.37.0","Info: signed release artifact: poethepoet-0.36.0-py3-none-any.whl.sigstore.json: https://github.com/nat-n/poethepoet/releases/tag/v0.36.0","Info: signed release artifact: poethepoet-0.35.1-py3-none-any.whl.sigstore.json: https://github.com/nat-n/poethepoet/releases/tag/v0.35.1","Info: signed release artifact: poethepoet-0.35.0-py3-none-any.whl.sigstore.json: https://github.com/nat-n/poethepoet/releases/tag/v0.35.0","Info: signed release artifact: poethepoet-0.34.0-py3-none-any.whl.sigstore.json: https://github.com/nat-n/poethepoet/releases/tag/v0.34.0","Warn: release artifact v0.37.0 does not have provenance: https://api.github.com/repos/nat-n/poethepoet/releases/239105822","Warn: release artifact v0.36.0 does not have provenance: https://api.github.com/repos/nat-n/poethepoet/releases/228623307","Warn: release artifact v0.35.1 does not have provenance: https://api.github.com/repos/nat-n/poethepoet/releases/228611995","Warn: release artifact v0.35.0 does not have provenance: https://api.github.com/repos/nat-n/poethepoet/releases/216583917","Warn: release artifact v0.34.0 does not have provenance: https://api.github.com/repos/nat-n/poethepoet/releases/213683611"],"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Packaging","score":10,"reason":"packaging workflow detected","details":["Info: Project packages its releases by way of GitHub Actions.: .github/workflows/ci.yml:98"],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 18 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":3,"reason":"7 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: PYSEC-2024-48 / GHSA-fj7x-q9j7-g6q6","Warn: Project is vulnerable to: GHSA-79v4-65xg-pq4g","Warn: Project is vulnerable to: GHSA-cpwx-vrp4-4pq7","Warn: Project is vulnerable to: GHSA-9hjg-9r4m-mvj7","Warn: Project is vulnerable to: GHSA-7cx3-6m66-7c5m","Warn: Project is vulnerable to: GHSA-48p4-8xcf-vxj5","Warn: Project is vulnerable to: GHSA-pq67-6m6q-mj2v"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-21T21:11:33.333Z","repository_id":38017535,"created_at":"2025-08-21T21:11:33.333Z","updated_at":"2025-08-21T21:11:33.333Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28012085,"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","status":"online","status_checked_at":"2025-12-24T02:00:07.193Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["developer-tools","development-workflow","poetry","poetry-plugin","python","task-runner","uv"],"created_at":"2024-07-31T18:00:48.316Z","updated_at":"2026-02-08T22:04:22.205Z","avatar_url":"https://github.com/nat-n.png","language":"Python","funding_links":["https://github.com/sponsors/nat-n","https://www.buymeacoffee.com/natn"],"categories":["Python","Software Engineering","python","Other Tools"],"sub_categories":["Curated Python packages"],"readme":"# Poe the Poet\n\n\u003cimg alt=\"Poe the Poet\" src=\"https://raw.githubusercontent.com/nat-n/poethepoet/main/docs/_static/poe_logo_x2000.png\" height=\"200\" width=\"200\" align=\"left\"/\u003e\n\n[![Python versions](https://img.shields.io/badge/python-3.10%20%E2%80%93%203.13-blue)](https://pypi.org/project/poethepoet/)\n[![PyPI version](https://img.shields.io/pypi/v/poethepoet.svg)](https://pypi.org/project/poethepoet/)\n[![Download stats](https://img.shields.io/pypi/dm/poethepoet.svg)](https://pypistats.org/packages/poethepoet)\n[![License](https://img.shields.io/pypi/l/ansicolortags.svg)](https://github.com/nat-n/poethepoet/blob/doc/init-sphinx/LICENSE)\n\n**A batteries included task runner that works well with [poetry](https://python-poetry.org/) or [uv](https://docs.astral.sh/uv/).**\n\n**[📖 Read the documentation 📖](https://poethepoet.natn.io/)**\n\n\u003cbr clear=\"both\"/\u003e\n\n## Features\n\n- ✅ Straight forward [declaration of project tasks in your pyproject.toml](https://poethepoet.natn.io/tasks/index.html) (or [poe_tasks.toml](https://poethepoet.natn.io/guides/without_poetry.html#usage-without-pyproject-toml))\n\n- ✅ Tasks are run in poetry or uv's virtualenv ([or another env](https://poethepoet.natn.io/index.html#usage-without-poetry) you specify)\n\n- ✅ [Shell completion of task names and arguments](https://poethepoet.natn.io/installation.html#shell-completion)\n\n- ✅ The poe CLI can be used standalone, or as a [plugin for poetry](https://poethepoet.natn.io/poetry_plugin.html)\n\n- ✅ Tasks can be [commands](https://poethepoet.natn.io/tasks/task_types/cmd.html), [shell scripts](https://poethepoet.natn.io/tasks/task_types/shell.html), [python expressions](https://poethepoet.natn.io/tasks/task_types/expr.html), or references to [python functions](https://poethepoet.natn.io/tasks/task_types/script.html)\n\n- ✅ Concise commands with extra arguments passed to the task `poe [options] task [task_args]`\n\n- ✅ Easily [declare named CLI arguments](https://poethepoet.natn.io/guides/args_guide.html) for your tasks\n\n- ✅ Tasks can specify and [reference environment variables](https://poethepoet.natn.io/tasks/task_types/cmd.html#ref-env-vars), even without a shell\n\n- ✅ Tasks are [self documenting](https://poethepoet.natn.io/guides/help_guide.html), with optional help messages (just run `poe` with no arguments)\n\n- ✅ Tasks can be composed to run in [sequence](https://poethepoet.natn.io/guides/composition_guide.html#composing-tasks-into-sequences), in [parallel](https://poethepoet.natn.io/guides/composition_guide.html#composing-tasks-to-run-in-parallel), or as a [DAG](https://poethepoet.natn.io/guides/composition_guide.html#composing-tasks-into-graphs).\n\n- ✅ Works with [`.env` files](https://poethepoet.natn.io/tasks/options.html#loading-environment-variables-from-an-env-file)\n\n- ✅ Can be [used as a library](https://poethepoet.natn.io/guides/library_guide.html) to embed in other tools\n\n- ✅ Tasks can be [defined in python packages](https://poethepoet.natn.io/guides/packaged_tasks.html) for ease of reuse across projects\n\n- ✅ Also works fine as a [general purpose task runner](https://poethepoet.natn.io/guides/without_poetry.html)\n\n\n## Quick start\n\n1. Install the Poe the Poet globally via [pipx](https://pypa.github.io/pipx/) or [another method](https://poethepoet.natn.io/installation.html).\n\n  ```sh\n  pipx install poethepoet\n  ```\n\n  Or add it as a poetry project plugin:\n\n  ```toml\n  [tool.poetry.requires-plugins]\n  poethepoet = \"\u003e=0.39\"\n  ```\n\n2. Define some tasks in your **pyproject.toml**\n\n  ```toml\n  [tool.poe.tasks]\n  test         = \"pytest --cov=my_app\"                         # a simple command task\n  serve.script = \"my_app.service:run(debug=True)\"              # python script based task\n  tunnel.shell = \"ssh -N -L 0.0.0.0:8080:$PROD:8080 $PROD \u0026\"   # (posix) shell based task\n\n  # A more complete example with documentation and named arguments\n  [tool.poe.tasks.count-incomplete]\n  help = \"Count incomplete tasks in DynamoDB\"\n  cmd  = \"\"\"\n  aws dynamodb scan --table-name tasks\n                    --select \"COUNT\"\n                    --filter-expression \"status \u003e= :status\"\n                    --expression-attribute-values '{\":status\":{\"S\":\"incomplete\"}}'\n                    --no-cli-pager\n  \"\"\"\n  args = [\n    # Allow $AWS_REGION to be overridden with a CLI option when calling the task\n    {name = \"AWS_REGION\", options = [\"--region\", \"-r\"], default = \"${AWS_REGION}\"}\n  ]\n  ```\n\n3. Run your tasks via the CLI\n\n  ```sh\n  $ poe test -v tests/unit # extra CLI arguments are appended to the underlying command\n  Poe =\u003e pytest --cov=my_app\n  ...\n  ```\n\nIf you're using poetry or uv, then poe will automatically use CLI tools and libraries from your project's virtualenv without you having to run `poetry run` / `uv run`\n\nPoe can also be [used as a general purpose task runner](https://poethepoet.natn.io/guides/without_poetry.html).\n\n## Contributing\n\nThere's plenty to do, come say hi in the [discussions](https://github.com/nat-n/poethepoet/discussions) or [open an issue](https://github.com/nat-n/poethepoet/issues)! 👋\n\nAlso check out the [CONTRIBUTING guide](https://github.com/nat-n/poethepoet/blob/main/.github/CONTRIBUTING.rst) 🤓\n\n\n## License\n\n[MIT](https://github.com/nat-n/poethepoet/blob/main/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnat-n%2Fpoethepoet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnat-n%2Fpoethepoet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnat-n%2Fpoethepoet/lists"}