Don’t call this function directly. Rather, call cli.opt, clip.flag, clip.arg, clip.arg_many, or clip.arg_many1.

Parse the next positional argument built using the clip/arg module and provide it to a Command function build using clip.command()

clip.command(fn(a) { a })
|> clip.arg(arg.new("foo"))
|> clip.run(["foo"])

// Ok("foo")

arg will not attempt to parse options starting with - unless the special -- value has been previously passed or the option is a negative integer or float.

Parse the next zero or more positional arguments built using the clip/arg module and provide them as a List to a Command function build using clip.command(). arg_many is greedy, parsing as many options as possible until parsing fails. If zero values are parsed successfuly, an empty List is provided.

clip.command(fn(a) { a })
|> clip.arg_many(arg.new("foo"))
|> clip.run(["foo", "bar", "baz"])

// Ok(["foo", "bar", "baz"])

arg_many will not attempt to parse options starting with - unless the special -- value has been previously passed or the option is a negative integer or float.

Parse the next one or more positional arguments built using the clip/arg module and provide them as a List to a Command function build using clip.command(). arg_many is greedy, parsing as many options as possible until parsing fails. Parsing fails if zero values are parsed successfully.

clip.command(fn(a) { a })
|> clip.arg_many1(arg.new("foo"))
|> clip.run(["foo", "bar", "baz"])

// Ok(["foo", "bar", "baz"])

arg_many1 will not attempt to parse options starting with - unless the special -- value has been previously passed or the option is a negative integer or float.

The command function is use to start building a parser. You provide a curried function and then provide arguments to be supplied to that function.

clip.command({
  use a <- clip.parameter
  use b <- clip.parameter

  #(a, b)
})
|> clip.opt(opt.new("first"))
|> clip.opt(opt.new("second"))
|> clip.run(["--first", "foo", "--second", "bar"])

// Ok(#("foo", "bar"))

Creates a Command that always produces Error(message) when run.

Parse a flag built using the clip/flag module and provide it to a Command function build using clip.command()

clip.command(fn(a) { a })
|> clip.flag(flag.new("foo"))
|> clip.run(["--foo"])

// Ok(True)

Add the help (-h, --help) flags to your program to display usage help to the user. See the clip/help module for producing simple and custom help text.

Parse an option built using the clip/opt module and provide it to a Command function build using clip.command()

clip.command(fn(a) { a })
|> clip.opt(opt.new("first"))
|> clip.run(["--first", "foo"])

// Ok("foo")

The parameter function provides an alternative syntax for building curried functions. The following two code blocks are equivalent:

fn(a) {
  fn(b) {
    thing(a, b)
  }
}

{
  use a <- clip.parameter
  use b <- clip.parameter

  thing(a, b)
}

You can use either style when calling clip.command.

The return function takes a value val and produces a Command that, when run, produces val. You should only call this function directly when your command doesn’t require any arguments. Otherwise, use clip.command.

clip.return(1) |> clip.run(["whatever"])

// Ok(1)

See the subcommand example for idiomatic usage of return.

Run a command. Running a Command(a) will return either Ok(a) or an Error(String). The Error value is intended to be printed to the user.

Build a command with subcommands. This is an advanced use case, see the examples directory for more help.

Build a command with subcommands and a default top-level command if no subcommand matches. This is an advanced use case, see the examples directory for more help.