Skip to content

CLI Commands

Engin provides a set of CLI commands to aid with application development. To use these commands, you need to install Engin with the cli extra, which can safely be treated as a development only dependency.

uv add engin[cli]

Tip

It is recommended to configure a default instance in your pyproject.toml.

[tool.engin]
default-instance = "myapp.main:engin"

When configured, you can run any CLI command without the app argument:

# Uses the default instance from pyproject.toml
engin check

# Passing an explicit instance always overrides the default instance
engin check myapp.main:engin

Commands

  • engin check: checks for missing providers.
  • engin inspect: show metadata about providers.
  • engin graph: visualise your dependency graph.

engin check

Checks that all dependencies in your Engin instance are satisfied.

If there are any missing providers it will return with exit code 1.

Note, this command only validates there are providers for all dependencies required by invocations, any dependencies built dynamically at runtime via the Assembler will not be checked for as these cannot be statically analysed.

Usage

engin check [OPTIONS]

Options

  • --app: the path to your application in the format <module>:<attribute>, e.g. myapp.main:engin. Not required if you set a default-instance in your pyproject.toml.

Example

engin check myapp.main:engin

✅ All dependencies are satisfied!

❌ Missing providers found:
  • httpx.AsyncClient
  • DatabaseConfig

engin inspect

Shows detailed metadata for providers in your Engin instance. You can filter providers by type or module.

Usage

engin inspect [OPTIONS]

Options

  • --app: the path to your application in the format <module>:<attribute>, e.g. myapp.main:engin. Not required if you set a default-instance in your pyproject.toml.
  • --type: filter providers by return type name. Note that multiproviders take the form of type[].
  • --module: filter providers by the return type's module.
  • --verbose: enable verbose output.

Example

engin inspect myapp.main:engin --module httpx

Found 1 matching provider
┌─────────────────────────────────────────────────────────────────────────┐
│ name           │ Provide(factory=httpx_client, type=AsyncClient)  │
│ scope          │ N/A                                              │
│ func           │ httpx_client                                     │
│ block          │ N/A                                              │
│ source module  │ myapp.main                                       │
│ source package │ myapp                                            │
└─────────────────────────────────────────────────────────────────────────┘

engin graph

Creates a visual representation of your application's dependency graph.

This starts a local web server which displays an interactive graph of your dependencies.

Usage

engin graph [OPTIONS]

Options

  • --app: the path to your application in the format <module>:<attribute>, e.g. myapp.main:engin. Not required if you set a default-instance in your pyproject.toml.
  • --port or -p: the port for the local web server to serve the graph on.

Example

engin graph myapp.main:engin

engin-graph-output.png

Serving dependency graph on http://localhost:8123