DocsThings to keep in mind

Things to Keep in Mind

When building a completion spec, your aim should be to represent a CLI tool in Fig's completion spec standard as best you can.

If a completion spec misrepresents a CLI, Fig won't just offer incorrect suggestions, but may even block the user from executing a command, or worse, cause the user to execute a command they didn't mean to! Fortunately, keeping the following in mind will help you avoid this:

Subcommands & Options

  1. Make sure the name prop exactly matches the token the user would type.
    1. Don't include = or the arg. i.e. use name: ["-m"] not name: ["-m=message"]
    2. Don't include a friendly message. i.e. use name: "commit" not name: "make a commit 😊"
  2. Subcommands can nest beneath other subcommands (e.g. aws s3 cp)
  3. Options cannot nest beneath options.


  1. If a subcommand or option takes an argument(s), you must signal this to our parser by at least including an empty Arg object (e.g. args: {}).
  2. If a subcommand or option does not take an argument, you should NOT include an Arg object
  3. If an argument is optional, it should use the isOptional: true prop
  4. If an argument is variadic (can repeat infinitely), it should use the isVariadic: true prop

What happens if you don't include an arg object?

Let's imagine you forgot to say that -m takes an argument in the completion spec for git commit -m <msg>.

  • If a user typed: git commit -m[space], Fig would suggest other options NOT enforce that a msg should be input
  • If a user typed: git commit -m "my message"[space], Fig would think there is an error and therefore hide, rather than suggesting other options.
    • Why would Fig hide? Because we didn't know -m took an argument, we assumed "my message" was a subcommand or an option nested beneath commit. Fig assumes the completion spec is correct. And because the completion spec doesn't specify an option or subcommand called "my message", we assume the user is wrong. And when we think the user is wrong, we hide!


You're now ready to build your own Completion Specs!