cli

Module cli is used to build command line apps written in the Risor. Common CLI features are supported, including commands, flags, arguments, usage, and automatic help generation.

Behind the scenes, this module uses the urfave/cli (opens in a new tab) library.

Getting Started

Create a file named myapp.risor with the following contents. Note that you must include the shebang line including -- at the top of the file to ensure that arguments and options are passed to the app, rather than being used as options by the Risor binary itself.

#!/usr/bin/env risor --
 
from cli import app, command as c
 
app({
    name: "myapp",
    description: "My app description",
    commands: [
        c({
            name: "hello",
            description: "Say hello",
            action: func(ctx) {
                print("Hello, world!")
            },
        }),
    ],
}).run()

Now make the file executable:

$ chmod +x ./myapp.risor

You can now run the app as follows:

$ ./myapp.risor hello
Hello, world!

Functions

app

app(options map) app

Returns a new app initialized with the given options. A simple app may consist of just a name, description, and action function. Call .run() on the app to run it.

app := cli.app({
    name: "myapp",
    description: "My app description",
    action: func(ctx) {
        print("Hello, world!")
    },
})
 
app.run()

The app function supports the following options:

• action func(ctx): The action to run when the app is run.
• commands []cli.command: A list of commands that the app supports.
• description string: A short description of the app.
• flags []cli.flag: A list of flags that the app supports.
• help_name string : Override for the name of the app in help output.
• name string: The name of the app.
• usage_text string: The usage text for the app.
• usage string: The usage string for the app.
• version string: The version of the app.

command

command(options map) command

Returns a new command initialized with the given options. Commands are provided to an app via the app's commands option.

command := cli.command({
    name: "add",
    description: "Add numbers provided as arguments",
    action: func(ctx) {
        sum := 0
        for _, arg := range ctx.args() {
            sum += int(arg)
        }
        print(sum)
    },
})

The command function supports the following options:

• action func(ctx): The function to call when the command is invoked.
• aliases []string: A list of aliases for the command.
• args_usage string: A short description of the arguments of this command.
• args bool: Whether this command supports arguments.
• category string: The category the command is part of.
• custom_help_template string: Text template for the command help topic.
• description string: A longer explanation of how the command works.
• flags []cli.flag: A list of flags that the command supports.
• help_name string: Full name of command for help, defaults to full command name, including parent commands.
• hidden bool: Hide this command from help or completion.
• hide_help_command bool: Whether to hide the command from the help command.
• hide_help bool Hide the built-in help command and help flag.
• name string: The name of the command.
• usage_text string: Custom text to show in USAGE section of help.
• usage string: A short description of the usage of this command.
• use_short_option_handling bool: Enables short-option handling so the user can combine several single-character bool flags into one.

flag

flag(options map) flag

Returns a flag that may be used with an app or command. Supported flag types include string, int, bool, float, string_slice, int_slice, and float_slice.

A default value for the flag may be provided using the value option. The flag type is inferred from the value option if a type is not specified.

cli.flag({
    name: "food",
    aliases: ["f"],
    usage: "The type of food to eat",
    env_vars: ["FOOD"], // read from this environment variable, if present
    value: "pizza",     // default value
    type: "string",     // flag type: string, int, bool, etc.
})

cli.flag({
    name: "count",
    aliases: ["c"],
    usage: "The number of items to process",
    value: 1,
})

cli.flag({
    name: "verbose",
    aliases: ["v"],
    usage: "Enable verbose output",
    value: false,
})

Types

app

An app represents the main entry point for a command-line program. It contains commands, is customized with flags, and is executed via app.run().

ctx

A ctx object is passed through to each handler action in a cli app. It is used to retrieve context-specific args and parsed command-line options.

Attributes on the ctx object include:

command

A command represents a sub-command of an app. It contains its own flags and has an associated action. Commands may have sub-commands.

flag

A flag is used to parse command-line flags in a cli app. Flags may be specified on a cli app directly, as well as on commands.