Root

Carapace uses Cobra to define (sub)commands and flags:

var rootCmd = &cobra.Command{
	Use:   "freckles",
	Short: "A simple dotfile manager.",
	Run:   func(cmd *cobra.Command, args []string) {},
	CompletionOptions: cobra.CompletionOptions{
		DisableDefaultCmd: true,
	},
}

Cobra has its own completion logic and adds a completion subcommand by default. This can be prevented with CompletionOptions.

Historically, Cobra had no dynamic completion, and development in this regard was quite stale. Without the burden of backward compatibility and the massive amount of dependents, Carapace could develop much more quickly and push the boundary of what's possible.

Here's the cornerstone that ultimately became Carapace.

Gen

Gen adds a hidden _carapace subcommand which handles script generation, completions, and macros.

	carapace.Gen(rootCmd)

Calling Gen with the root command is enough to add completion for commands and flags. But be aware that in Carapace argument completion is explicit. So an undefined completion does not cause an implicit file completion fallback.

Script

Completion scripts are generated with freckles _carapace [shell]. Most of these can be directly sourced.

Carapace has a basic shell detection mechanism, so in most cases [shell] is optional.

Export

Shell scripts in Carapace are just thin layers to integrate with the corresponding shell.

Aside from shell-specific output:

freckles _carapace [shell] freckles [ARGS]...

Export provides a more generic json representation of completions:

freckles _carapace export freckles [ARGS]...

Carapace (binary) essentially acts as a central registry for all of your completions.

With #1336 packages will be able to register completions system-wide using Specs:

# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
name: freckles
parsing: disabled
completion:
  positionalany: ["$carapace.bridge.Carapace([freckles])"]

This has several benefits:

• it avoids the startup delay issue
• it provides a central registration point for all shells
• it enables embedding with bridge.ActionCarapaceBin
• it uses the newest version of Carapace for shell integration

Macro

Actions with the signature of MacroI, MacroN, or MacroV can be exposed as a custom macro for others to consume.

	spec.AddMacro("freckles", spec.MacroN(action.ActionFreckles))
	spec.Register(rootCmd)

Macros provide a way to loosely share Actions between applications.

More on this at Init#Clone and Edit#Action.