{"id":10052,"library":"polylith-cli","title":"Polylith CLI","description":"The `polylith-cli` is a command-line interface tool that provides essential tooling support for developing Python applications using the Polylith Architecture. It helps manage workspaces, create bases and components, and analyze dependencies within a monorepo structure. As of version 1.45.0, it is actively developed with regular updates and new features.","status":"active","version":"1.45.0","language":"en","source_language":"en","source_url":"https://github.com/davidvujic/python-polylith","tags":["cli","monorepo","architecture","tooling","project-management"],"install":[{"cmd":"pip install polylith-cli","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for core CLI functionality, especially on older Python versions (e.g., Python 3.8). Was a previously missing dependency now bundled.","package":"typing-extensions","optional":false}],"imports":[],"quickstart":{"code":"# Create a new Polylith workspace\npoly create workspace my_polylith_project\n\n# Navigate into the workspace\ncd my_polylith_project\n\n# Create a new component\npoly create component my_component\n\n# Get information about the workspace\npoly info","lang":"bash","description":"Start by creating a new Polylith workspace, then generate components and use `poly info` to inspect the structure."},"warnings":[{"fix":"Interact with `polylith-cli` via your terminal using the `poly` command, e.g., `poly info` or `poly check`.","message":"Polylith CLI is primarily a command-line tool. It is not designed for direct Python import into user applications. Its functionality is accessed via the `poly` executable.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure brick names are unique before attempting to create them. Use `poly info` to see existing bricks.","message":"The `poly create component` and `poly create base` commands now validate brick names and will exit with a failure code if a brick with the same name already exists in the workspace.","severity":"breaking","affected_versions":">=1.41.0 (stable-98) onwards"},{"fix":"Update `polylith-cli` to version 1.42.0 or higher to ensure accurate dependency checking.","message":"`poly check` and `poly libs` might have previously incorrectly reported missing imports/dependencies for third-party libraries sharing similar top-level namespaces with Polylith bricks. This was fixed in `stable-99`.","severity":"gotcha","affected_versions":"<1.42.0 (before stable-99)"},{"fix":"Ensure `polylith-cli` is updated to version 1.37.0 or higher. If issues persist, manually install `typing-extensions` via `pip install typing-extensions`.","message":"Python 3.8 users encountered `ModuleNotFoundError: No module named 'typing_extensions'` due to a missing dependency. This was patched in `stable-94`.","severity":"gotcha","affected_versions":"<1.37.0 (before stable-94) when using Python 3.8"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Choose a unique name for your new component/base, or delete the existing one if no longer needed. Check existing bricks with `poly info`.","cause":"Attempting to create a component or base with a name that is already in use within the workspace.","error":"Error: A brick named 'my_component' already exists. Aborting."},{"fix":"Update `polylith-cli` to the latest version (`pip install --upgrade polylith-cli`). If the problem persists, manually install `typing-extensions`: `pip install typing-extensions`.","cause":"Missing `typing_extensions` dependency, particularly on Python 3.8, due to `typer` updates.","error":"ModuleNotFoundError: No module named 'typing_extensions'"},{"fix":"Use the `poly` command in your terminal instead of attempting to import it in Python code. For example, run `poly info` from your command line.","cause":"Trying to import the `polylith_cli` package in Python code. This package is designed to provide the `poly` command-line entry point, not for direct programmatic import by end-users.","error":"ModuleNotFoundError: No module named 'polylith_cli'"},{"fix":"Upgrade `polylith-cli` to version 1.42.0 or higher (`stable-99` or newer). If the issue persists with the latest version, verify `my_third_party_lib` is correctly listed in your project's `pyproject.toml` or `requirements.txt`.","cause":"Older versions of `poly check` could incorrectly report missing dependencies when a third-party library's name was similar to a Polylith top-level namespace.","error":"poly check failed. Missing dependency 'my_third_party_lib' in project 'my_project' (found import in 'my_component')"}]}