Built-in commands

Cliffy provides some predefined commands like help, completions and upgrade. These commands are optional and must be registered manually if you want to use them.

The HelpCommand prints the auto generated help. It is mostly the same as the --help option but it also accepts the name of a child command as optional argument to show the help of the given sub-command.

To make the help command globally available for all child commands you can use the .global() method on the help command.

import { Command } from "@cliffy/command";
import { HelpCommand } from "@cliffy/command/help";

await new Command()
  .version("0.1.0")
  .description("Sample description ...")
  .env(
    "EXAMPLE_ENVIRONMENT_VARIABLE=<value:boolean>",
    "Environment variable description ...",
  )
  .command("help", new HelpCommand().global())
  .parse();

denonodebun

$ deno run https://cliffy.io/examples/v1.3.0/command/help_option_and_command.ts help
$ deno run https://cliffy.io/examples/v1.3.0/command/help_option_and_command.ts help completions
$ deno run https://cliffy.io/examples/v1.3.0/command/help_option_and_command.ts completions help

$ node run examples/command/help_option_and_command.ts help
$ node run examples/command/help_option_and_command.ts help completions
$ node run examples/command/help_option_and_command.ts completions help

$ bun run examples/command/help_option_and_command.ts help
$ bun run examples/command/help_option_and_command.ts help completions
$ bun run examples/command/help_option_and_command.ts completions help

The CompletionsCommand includes sub commands for all supported shell environments. The sub commands generate the shell completions script and outputs it to stdout. The completions command must be registered manually.

import { Command } from "@cliffy/command";
import { CompletionsCommand } from "@cliffy/command/completions";

await new Command()
  .command("completions", new CompletionsCommand())
  .parse();

By calling <command> completions <shell>, the command will output the completions script for the specified shell to stdout.

Each shell command provides also a --name option which allows you to override the command name: <command> completions <shell> --name <my-command>

To add support for bash completions you can either register the CompletionsCommand or directly the BashCompletionsCommand.

To enable bash completions add the following line to your ~/.bashrc:

source <(COMMAND completions bash)

i

NOTE

Replace COMMAND with the name of your cli.

To add support for fish completions you can either register the CompletionsCommand or directly the FishCompletionsCommand.

To enable fish completions add the following line to your ~/.config/fish/config.fish:

source (COMMAND completions fish | psub)

i

NOTE

Replace COMMAND with the name of your cli.

To add support for zsh completions you can either register the CompletionsCommand or directly the ZshCompletionsCommand.

To enable zsh completions add the following line to your ~/.zshrc:

source <(COMMAND completions zsh)

or run following command to use zsh fpath completions:

COMMAND completions zsh > /path/to/zsh/site-functions/_COMMAND

i

NOTE

Replace COMMAND with the name of your cli.

The UpgradeCommand can be used to upgrade your cli to a given or latest version. If the UpgradeCommand is registered, a hint is shown in the help and the long version output if a new version is available.

COMMAND upgrade --version 1.0.2

import { Command } from "@cliffy/command";
import { UpgradeCommand } from "@cliffy/command/upgrade";
import { DenoLandProvider } from "@cliffy/upgrade/provider/deno-land";

new Command()
  .command(
    "upgrade",
    new UpgradeCommand({
      main: "cliffy.ts",
      args: ["--allow-net"],
      provider: new DenoLandProvider(),
    }),
  );

With the provider option you specify which registries are supported. This option is required.

The main option is the entry file of your cli, appended to the registry url. On Deno the cli is reinstalled under the name of your main command.

i

NOTE

️ The name cannot have spaces! If you use spaces, you (or your users!) will get an error when upgrading.

If your cli needs some permissions, you can specify the permissions with the args option which are passed to the runtime's install command. Use the runtime option to pass different args or a different main per runtime.

i

NOTE

• Deno installs with --name, --global and --force.
• Node and bun install with --global and --force.
• The install command is silenced (--quiet on Deno, --silent on node and bun) unless the upgrade is run with -v or --verbose.

The provider option is required and takes one provider or an array of them. Cliffy ships providers for jsr, npm, deno.land, nest.land, github, gitlab, and any url. Their options are documented in providers.

With multiple providers, users select one with the --registry option (hidden when only one is registered). Without it, the first registered provider is used. For a standalone executable, the first provider that supports binary upgrades is used instead.

COMMAND upgrade --registry github --version main

The package name defaults to the command name for the jsr, npm, deno.land and nest.land providers. Override it with the name option. The github and gitlab providers use the repository option instead, and the url provider builds the url itself.

The -l or --list-versions option lists the available versions. The current version is highlighted and prefixed with a *. The option is only registered if at least one of the providers can list versions.

$ COMMAND upgrade -l
* v0.2.2
  v0.2.1
  v0.2.0
  v0.1.0

What each registry lists (for example the github provider's tags and branches) is covered under listing versions.

For a cli distributed as a standalone executable, the GithubProvider, GitlabProvider and UrlProvider can replace the running binary in place instead of reinstalling from a registry. Configure the provider with the asset option, force the binary path with standalone: true when it can't be auto-detected, and let users pick an install path with the -o or --output flag (or an env var via the outputEnv option). The --output flag is only registered if at least one of the providers supports binary upgrades. See binary upgrade for the full configuration.

i

NOTE

The UpgradeCommand wraps the parser-agnostic @cliffy/upgrade package. To add an upgrade command to a cli built with @cliffy/flags or another parser, use that package directly.