Confusing CLI

[allefeld]

Description

Whenever I post something on this repository, I feel I'm being unfair because in general Quarto is brilliant, and the effort you put into it shows. With this disclaimer:

I find the Quarto CLI confusing.

• install installs a global dependency (aka tool), but uninstall does not uninstall a global dependency. Instead it removes an extension, though an extension is not installed but added; however there's also remove. → Okay, this is legacy.

• create can be used to create an extension (which can later be added to a project) but also to initialize a project (two very different things), but a project can also be initialized from a template with use template, but there's also use binder which is not used to initialize a project but to add to it. → Maybe have init [<type>|<template>] and reserve create for extensions? use would be open for future generalization to add other things, like utility scripts.

• Project types are extensions, but create extension does not support creating one. → create extension project?

• list and update can be used for tools and extensions (two very different things). → Maybe have a command tool with subcommands tool install, tool update and tool list?

• preview does the same as render, it just previews additionally. (If this point feels especially picky: When I started using Quarto I was massively confused by this.) → Maybe turn previewing into an option of render?

• Some embedded programs are directly exposed via their own command (pandoc, typst), but other embedded programs (Deno, Lua) can only be used through run, but run can also be used for external software (R, Python). → Maybe expose all embedded software in the same way, e.g. run [<embedded program>|<script>]? (I'm not sure why a command is needed to run external software.)

I realize that it is necessary to keep commands working for backwards compatibility. But maybe the already started effort to make things more logical (remove an extension instead of uninstall) could be continued, and legacy commands could be omitted from --help but shown separately with --help-legacy.

Somewhat related: The interactive specification of options is very nice, but I'd appreciate it if everything is also accessible through CLI syntax, and where that syntax already exists, if it were explained by <command> --help.

[cscheid]

Thanks for the kind words. The rest of your post deserves a longer answer which I'm not right now prepared to give, but:

(I'm not sure why a command is needed to run external software.)

Sometimes it's useful/necessary for extensions and user filters to have access to those external software at precisely the right version, and these can live in different places depending on how Quarto is packaged. quarto pandoc and quarto typst is an easy way to make that work.

I hear you about those inconsistencies. With that said, we value backwards compatibility more than we value consistency. You can mitigate consistency problems with documentation, but you can't break backwards compatibility without making your users do extra work. We try very hard to avoid that.

One of the things we want to do in 2025 is to overhaul Quarto's internals to communicate warnings + deprecations. When that's in place, we can start making plans for --- slowly! --- introducing changes that make users change the way they work.

[allefeld]

Thanks!

Just to clarify,

I'm not sure why a command is needed to run external software.

did not to refer to Pandoc and Typst; there the use is completely clear to me. They are packaged with Quarto to ensure the specific version, and making them available makes perfect sense. Same for Deno and Lua.

My comment referred to external software like R and Python, which are independently installed. Therefore scripts in these languages can easily be run without Quarto's run command.

[cscheid]

Therefore scripts in these languages can easily be run without Quarto's run command.

I'm sorry, but you're incorrect, especially if you emphasize "easily". One of the harder parts (ie, one of the most common sources of trouble) in running these commands is ensuring that you have the same environment that you'd get from an r of python code cell. quarto run tries to ensure that this is the case. See, eg, https://github.com/quarto-dev/quarto-cli/blob/main/src/core/run/r.ts#L26

[allefeld]

I don't think I really understand, including based on the code you linked to, but no problem, I take your word for it.

[mcanouil]

These commands allow you to run them in the context of Quarto meaning you get all the environment variables set by Quarto for instance.

[allefeld]

Thanks, now I get it!