Unintuitive behaviour of the cue command for package instances

[anibali]

Consider the following file structure:

$ tree
.
├── bar
│   └── baz.cue
├── cue.mod
└── foo.cue

2 directories, 2 files
$ cat bar/baz.cue 
package mypackage

baz: "hello"
$ cat foo.cue 
package mypackage

foo: 42

My aim is to achieve the "package instancing" behaviour described in https://cuelang.org/docs/concepts/packages/#instances. That is, I want to find a way of invoking cue eval such that the result combines the files like so:

foo: 42
baz: "hello"

Finding the correct invocation of cue to achieve this was unexpectedly difficult.

The first thing that I tried was:

$ cue eval bar/baz.cue 
baz: "hello"

Hmm, I guess that doesn't work for some reason. This is very counterintuitive to me. Why aren't the rules explained in the documentation being applied?

OK, what if I change into the directory and run from there?

$ cd bar
$ cue eval baz.cue 
baz: "hello"

Nope, still no dice. What if I don't specify the file name?

$ cue eval
foo: 42
baz: "hello"

Yay, got it! But I don't actually want to have to change directory, so let's back up to the parent directory and try again:

$ cd ..
$ cue eval bar
cannot find package "bar"
$ cue eval bar/
cannot find package "bar"
$ cue eval -p mypackage bar
cannot find package "bar"

Nope, nope, and nope. Finally I found the winning command:

$ cue eval ./bar
foo: 42
baz: "hello"

So it looks like cue sometimes interprets the positional arguments as files/directories, and sometimes does not (I'm still not sure what it's trying to do when "cannot find package" errors are produced). Usually this kind of issue can be resolved by reading the built-in help of the command. In this case, running cue eval --help only documents the flags, not the positional arguments.

Getting the right command was pure trial and error. I tried searching Google, reading documentation, and searching through the issues. I was very close to giving up. Obviously I got there in the end, but I thought that I'd open this issue to highlight what my experience as a new user was like and potentially emphasise an area for improvement. It might also help other users searching through the issues in the future.

P.S. Cue looks really cool and there is obviously some awesome work going on here, good job to all involved! Just giving my two cents...

[mvdan]

The bottom of cue help points to cue inputs, which does explain this in detail. Is there anything you would change there to make this more intuitive to new users?

[anibali]

cue inputs is definitely useful now that I know about it, thanks. However, as a long-time Linux user I still don't think that the path from cue eval to running what looks like a separate subcommand (but is actually a help page) is one that I would anticipate. If it were me I'd change two things:

1. Include a more in-depth example in https://cuelang.org/docs/concepts/packages/#instances with an example file directory structure, files, command, and output. Also mention here how "package instancing" works (or doesn't work) when specifying individual .cue files as inputs.
2. Update the individual subcommand help pages (like cue eval --help) so that usage shows cue eval [flags] inputs... (instead of cue eval [flags]) and include a reference to cue inputs.