Gap between errors and documentation in embedding extensions?

Discussed in https://github.com/quarto-dev/quarto-cli/discussions/10603

^{Originally posted by andrewpbray August 25, 2024}

Description

I added an extension within an extension (just kinda to see what would happen) and I got this error:

ERROR: Failed to resolve referenced filter countdown.lua - path does not exist.
If you are attempting to use another extension within this extension, please install the extension using the 'quarto install --embedded' command.

To learn more, I tried the help:

(base) MacBookPro:stat20slides andrewbray$ quarto install --help 
Usage:   quarto install [target...]
Version: 1.6.6                     

Description:

  Installs a global dependency (TinyTex or Chromium).

Options:

  -h, --help               - Show this help.                              
  --no-prompt              - Do not prompt to confirm actions             
  --update-path            - Update system path when a tool is installed  
  --log          <file>    - Path to log file                             
  --log-level    <level>   - Log level (info, warning, error, critical)   
  --log-format   <format>  - Log format (plain, json-stream)              
  --quiet                  - Suppress console output.                     
  --profile                - Active project profile(s)                    

Commands:

  help  [command]  - Show this help or the help of a sub-command.

Examples:

  Install TinyTeX:        quarto install tinytex 
  Install Chromium:       quarto install chromium
  Choose tool to install: quarto install

And when I went to run the recommended command at the root of the project I got:

(base) MacBookPro:stat20slides andrewbray$ quarto install --embedded
ERROR: Unknown option "--embedded". Did you mean option "--embed"?

So then:

(base) MacBookPro:stat20slides andrewbray$ quarto install --embed
ERROR: Missing value for option "--embed".

I'm not sure if this has already beed logged, but if not I figured I'd get it on the to-do list.

(quarto add <org/repo> --embed <extension> still works 👌 )

Start by comparing the CLI help for quarto install with the error recommending quarto install --embedded, then check the related quarto add <org/repo> --embed behavior. Reproduce the commands shown in the issue and align the help, error message, and accepted command so the documented recommendation works.