Is there a recommended way to run Mill from a subdirectory in a monorepo?

[atty303]

When running Mill from a subdirectory of build.mill, I would like task names to be resolved relative to the current working directory.

For example, suppose the monorepo has the following structure:

build.mill
apps/package.mill
apps/foo/package.mill
apps/foo/server/package.mill
apps/foo/client/package.mill
apps/bar/package.mill

I would like to be able to run commands as follows:

$ cd apps/foo
$ mill server.run
# Resolves to apps.foo.server.run

$ cd apps/foo/client
$ mill run
# Resolves to apps.foo.client.run

My understanding is that, with the current behavior, I need to run the fully qualified task from the repository root:

$ mill apps.foo.server.run

I could implement this with a wrapper script, but I would like to know whether Mill provides a standard or recommended way to achieve this.

[yudin-s]

I do not think Mill currently has a built-in “resolve targets relative to the shell cwd” mode.

Mill can discover/evaluate a build made from build.mill plus nested package.mill files, but target selectors are still names in the build graph, not filesystem-relative names. In the layout you showed, server.run is a different selector from apps.foo.server.run; changing into apps/foo does not make apps.foo an implicit prefix.

So the two practical options are:

1. Keep using fully qualified targets:

mill apps.foo.server.run
mill apps.foo.client.run

2. Add a thin repo-local wrapper that computes the path from the build root to $PWD, converts / to ., and prefixes that to the target. For example, from apps/foo/client, the wrapper would map:

mill run

to:

mill apps.foo.client.run

I would keep that wrapper explicit, e.g. ./mill-here run or a shell function, rather than replacing mill globally. It avoids surprising cases like commands that are intentionally root-scoped (resolve, show, cross-module tasks, wildcards, etc.).

Another low-tech option is to add local alias tasks in the nearest package.mill, such as a short def run = server.run, but those aliases still become normal Mill targets under their full module path; they do not make command-line resolution cwd-relative.

If cwd-relative target resolution is important for monorepos, this sounds like a feature request for an explicit flag/config rather than something Mill already standardizes.

If this clarifies the current behavior, please mark it as the answer so other monorepo users can find it.

[atty303]

Thanks for the explanation. That clarifies the current behavior.

Target selectors are still names in the build graph, not filesystem-relative names.

I think this limitation only really applies when the build graph is defined purely through object nesting in build.mill. If a project uses package.mill, the filesystem already provides enough information to derive the corresponding build graph name. In that case, I think resolving the module path from the filesystem is feasible. I agree that making this the default behavior would be difficult for builds that rely only on object nesting, since there is no canonical mapping from the filesystem to the build graph.

The biggest pain point for me with Mill in a monorepo is the developer workflow. In a monorepo, I typically cd into the subproject I'm working on. However, to run a Mill task, I have to go back to the repository root.

I also use mise extensively, and my project-specific mise configuration is activated by changing into the subproject directory. That makes staying in the subproject the natural workflow.

Whether or not relative target resolution should be supported, I wonder if Mill could at least search parent directories for build.mill, similar to how many other developer tools discover their project root. That alone would make the workflow much smoother in monorepos.

I already have a wrapper script that provides the workflow I want, so this isn't blocking me.

I mainly wanted to report it because I think improving this area could make the monorepo experience with Mill significantly better.