Just some stream of consciousness and

[analog wigeon]

FWIW i'm aware that the top level CLI is currently undergoing a refactor so perhaps this gets solved via that refactor

[unkempt meteor]

@analog wigeon you're right. We did something similar for arguments in an earlier part: https://docs.dagger.io/zenith/quickstart/292472/arguments#list-available-arguments

So it makes sense to do the same for chaining.

We do have a chapter dedicated to understanding chaining: https://docs.dagger.io/zenith/quickstart/853930/directories#understand-function-chaining

Maybe it's important enough that it deserves its own section in the quickstart? And then we'd add your suggestion in there?

WDYT?

cc @deep mason

[analog wigeon]

Yes, this chapter is good to introduce the concept, I think the piece that was missing in my brain was actually attaching it to an example in an obvious way. Maybe better example with full typing will be helpful. I think in general sticking to the golden path of "this is how you are supposed to interact with any new module when learning about and using it "will help train people in the right habits about the CLI ergonomics. In other words, the DevEx around "discovering" how to use new modules via CLI commands should be baked into the getting started guide

This example invites a second question though... When do I use dagger functions -m mymodule and when do I use dagger call -m mymodule --help? It seems like they both do similar things but the call command gives more information currently.

Lastly, is the return type information surfaced in the CLI? That to me is the final piece around grokking the "chaining" of modules quickly. I think for me what would have helped my gears immediately click is if i saw the example and it showed me that

dagger call -m github.com/shykes/daggerverse/wolfi base

returns some typed thing that then returns a typed "configuration" (the Config type) which the container takes as input. Had I seen the types attached alongside the chained calls somehow it feels like it would have been "whoa ok, so base returns Config, container takes Config as input, now I see I can chain them together easily".

[unkempt meteor]

Yes there is overlap between functions and call --help. Documenting this in the quickstart will force us to choose one or the other as primary.

@analog wigeon initially functions showed return type information, but it dumped all types & functions for the module, so you had to search through it to find where to start. The current functions is much more narrow , basically a more focused/scriptable version of call --help

[analog wigeon]

got it, yeah, i haven't seen the worst output of my suggestion yet, so maybe that was just way too ugly to be usable 😄

[unkempt meteor]

Would you find it surprising if call --help added type information?

I think functions is a bandaid that should be replaced by a full blown dagger doc in the style of go doc. Won't ship right away though, need a polished multi-language experience.

[analog wigeon]

I don't see other CLI's doing it (rendering the return type), but usually I've dealt a lot with dynamic languages where the type might straight up be not known in the first place... which is not a limitation that exists here as far as I can tell? I do see other CLI's specifying argument type though e.g. click etc

[unkempt meteor]

we could also add a doc function to every type, which returns the type's API doc as a string

[analog wigeon]

I guess in general I love the idea of just being handed a module, let's say solomonscoolmod (or the hello one you made) and being able to very quickly discover everything I can do with it, and maybe dagger doc is the way to do that

[unkempt meteor]

yes we agree, very important and we haven't nailed it yet

it's still way easier to write a module from scratch than reuse one you don't know