--- title: Commands --- # Commands ## Basic Usage ```ts const cli = Cli() .scriptName("foo-cli") .description("A simple CLI") .version("1.0.0") .command("foo", "A foo command") .on("foo", (ctx) => { console.log("It works!"); }) .parse(); ``` This creates a CLI application named `foo-cli` with a command called `foo`. When the user runs `foo-cli foo`, the CLI will output "It works!". ## Optional Description The description parameter is optional. You can omit it if you don't need to document the command: ```ts const cli = Cli() .scriptName("foo-cli") .description("A simple CLI") .version("1.0.0") .command("foo", { // No description, pass options directly flags: { output: { type: String, description: "Output file", }, }, }) .on("foo", (ctx) => { console.log("It works!"); }) .parse(); ``` Alternatively, you can use the traditional syntax with a description: ```ts const cli = Cli() .scriptName("foo-cli") .description("A simple CLI") .version("1.0.0") .command("foo", "A foo command", { flags: { output: { type: String, description: "Output file", }, }, }) .parse(); ``` ## Aliases ### Overview Command aliases allow users to invoke a command using an alternative name. This is useful for providing shorter or more intuitive command names. ### Single Alias You can define a single alias for a command using a string: ```ts const cli = Cli() .scriptName("foo-cli") .description("A simple CLI") .version("1.0.0") .command("foo", "A foo command", { alias: "f", }) .on("foo", (ctx) => { console.log("It works!"); }) .parse(); ``` Now both `foo-cli foo` and `foo-cli f` will output "It works!". ### Multiple Aliases You can define multiple aliases for a command using an array: ```ts const cli = Cli() .scriptName("foo-cli") .description("A simple CLI") .version("1.0.0") .command("foo", "A foo command", { alias: ["f", "bar", "baz"], }) .on("foo", (ctx) => { console.log("It works!"); }) .parse(); ``` Now `foo-cli foo`, `foo-cli f`, `foo-cli bar`, and `foo-cli baz` all work the same way. ### Practical Examples #### Example: Git-like Abbreviations ```ts const cli = Cli() .scriptName("git") .command("status", "Show working tree status", { alias: "st", }) .on("status", (ctx) => { console.log("On branch main..."); }) .command("commit", "Record changes to repository", { alias: ["ci", "com"], }) .on("commit", (ctx) => { console.log("Committing changes..."); }) .command("checkout", "Switch branches or restore files", { alias: "co", }) .on("checkout", (ctx) => { console.log("Checking out..."); }) .parse(); ``` Usage: ```sh $ git st $ git commit $ git ci $ git com $ git checkout $ git co ``` ## Subcommands You can define subcommands by using spaces in the command name: ```ts const cli = Cli() .scriptName("foo-cli") .description("A simple CLI") .version("1.0.0") .command("parent child", "A subcommand") .on("parent child", (ctx) => { console.log("Subcommand was called!"); }) .parse(); ``` ## Root Command You can define a root command (a command with no name) to handle cases when no subcommand is specified: ```ts const cli = Cli() .scriptName("foo-cli") .description("A simple CLI") .version("1.0.0") .command("", "Root command") .on("", (ctx) => { console.log("Root command was called!"); }) .parse(); ``` ## Parameters Please refer to the [Parameters Documentation](./parameters) for detailed information about parameter definition, constraints, and descriptions. ## Flags Please refer to the [Flags Documentation](./flags). ## Ignore Sometimes, you may want to ignore certain arguments or flags in the command line input. For example, this usage of `deno`: ```sh deno run --allow-read script.ts --flag ``` Where `--flag` is passed directly to the script, not to `deno`. You can achieve this usage by using the `ignore` property to specify which arguments or flags to ignore. ```ts import { PARAMETER } from "clerc"; let encounteredParameter = false; const cli = Cli() .scriptName("deno") .description("Deno CLI") .version("1.0.0") .command("run", "Run script", { flags: { allowRead: { type: Boolean, description: "Allow file system read", }, }, parameters: ["