Thanks for the very quick response.
It's not clear to me why you aren't able to checkout the cores under the hardware subfolder of ARDUINO_DIRECTORIES_USER. Would you mind helping me to understand better?
That, or a symlink farm for the various components is, indeed, my likely workaround, but it feels like a hack. Were this a one-shot "how do I build my sketch" question, I'd have done that without blinking.
The additional context is that we make make computer keyboards that run arduino-derived firmware. We have our own libraries and our own core, as well as extensive command-line tooling for folks who don't want to use the Arduino IDE. That predates arduino-cli and we're in the process of modernizing it, now that arduino-cli seems to have stabilized. I'm very excited about all the stuff we'll no longer need to do ourselves.
Some end-users do indeed just use the packaged versions of our core and libraries that we publish for installation using the boards manager. But many others prefer to run the current codebase directly from git, and I'm working on making that as straightforward and seamless as possible. With arduino-builder, we could at least construct things such that a checkout started at the directory that would be dropped into 'hardware/keyboardio' in a sketchbook. I was very much looking forward to being able to do something less hacky with arduino-cli.
Forcing a single directory structure feels like a strangely limiting design choice if it's intentional, and a step backward from arduino-builder in terms of flexibility.
I realize now that I'm actually going to end up with a similar issue around --libraries: I'd really like to be able to include individual libraries in the search path, without having to stick them one extra level deeper in the directory structure so that --libraries /path/to/my-library's-parent-directory/ doesn't attempt pick up ever sibling directory of my library's checkout as a possible library to include.
What I'm really looking for, if this is not indeed possible right now, is some read on whether it's a design decision or just something not-yet-implemented.