Hard to figure out how to call `quarto create project`

[jennybc]

What would you like to do?

Give feedback or suggest an improvement

Description

I had some trouble figuring out how to call quarto create project -- especially non-interactively or with --no-prompt. I give some details below these are the main points:

• Would be helpful to document an exact, working call to quarto create project that does not trigger additional user interaction. In particular, it seems like title is required, which I didn't expect based on what I see at https://quarto.org/docs/projects/quarto-projects.html#creating-projects.
• Should title default to name? Should (project) type default to "default"?
• Could quarto create project support the POSIX-y way of passing arguments by name, meaning --name=value? The existing usage and help already puts my mind in that mode. Then it feels like sensible defaults could take over in non-interactive settings and even interactively you could specify just the name, for example (quarto create project --name=whatever).

Here's what I currently see for how to use quarto create project:

~/rrr/usethis % quarto create project --help

Usage:   quarto create [type] [commands...]
Version: 1.5.47                            

Description:

  Create a Quarto project or extension

Options:

  -h, --help              - Show this help.                                    
  --open        [editor]  - Open new artifact in this editor (vscode,rstudio)  
  --no-open               - Do not open in an editor                           
  --no-prompt             - Do not prompt to confirm actions                   
  --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.

I'm not sure what the [commands...] bit should be. I figured it out by successively adding inputs and noticing what I was being prompted for.

~/tmp % quarto create blah
Unknown type blah - please select from the following:
? Create
❯ project
  extension
# (ok `type` should be `project`)

~/tmp % quarto create project blah  
? Type
❯ default
  website
  blog
  manuscript
  book
  confluence
# (a new type appears! morally `--project-type=default`)

~/tmp % quarto create project default blah
# (now I get a prompt to specify a project title)

Culminating in this successful call:

~/tmp % quarto create project default blah1 blah2
Creating project at /Users/jenny/tmp/blah1:
  - Created _quarto.yml
  - Created blah2.qmd

So I think it's:

quarto create project [project-type] [project-folder-name] [?project-title?]

[cscheid]

I agree that we need to improve the situation, possibly not only with documentation.

I don't know why we decided to keep the following option quiet, but we have quarto create --json. You give it a JSON object on stdin, and it writes back on stdout a JSON object describing what happened:

quarto-cli/src/command/create/cmd.ts

Lines 38 to 54 in 92cad44

	.option("--json", "Pass serialized creation options via stdin", {
	hidden: true,
	})
	.arguments("[type] [commands...]")
	.action(
	async (
	options: {
	prompt: boolean;
	json?: boolean;
	open?: string | boolean;
	},
	type?: string,
	...commands: string[]
	) => {
	if (options.json) {
	await createFromStdin();
	} else {

quarto-cli/src/command/create/cmd.ts

Lines 274 to 279 in 92cad44

	const createResult = await resolved.artifact.createArtifact(
	createDirective,
	true,
	);
	const resultJSON = JSON.stringify(createResult, undefined);
	Deno.stdout.writeSync(new TextEncoder().encode(resultJSON));