CLI Guidelines

Guidelines for CLI tools shipping with WebHare

• New CLI tools should be written in TypeScript, existing ones should be ported
• Prefer a 'swiss army knife' for tools that handle a major subsystem, eg wh wrd, wh whfs...
• Public tools should live in mod::platform/cli-commands/, private tools in modules (eg mod::publisher/scripts/whcommands/dumpcsp.whscr = wh publisher:dumpcsp)
• Third party modules should store their CLI tools in mod::<module>/scripts/whcommands/ so they can integrate into wh help and command line completion

Options parser

Common flags:

  flags: {
    "j,json": { description: "Output in JSON format" }
    "v,verbose": { description: "Show verbose output" }
    "f,force": { description: "Force this action" },
  },

TypeScript

Skeleton:

// @webhare/cli: short tool description

import { run } from "@webhare/cli";

run({
  flags: {
    "v,verbose": "Show more info",
  },
  main: async ({ opts, args }) => {
    
  }
});

HareScript

<?wh
// syntax: [arguments] - remove this line if your tool doesn't expect arguments
// short: Does a CLI thing - remove if your tool shouldn't be document in 'wh help'

LOADLIB "wh::os.whlib";

LOADLIB "mod::system/lib/database.whlib";


MACRO SubCommand(STRING ARRAY params)
{
  RECORD subargs := ParseArguments(params,
      [ [ name := "switch", type := "switch"  ]
      , [ name := "param", type := "param", required := TRUE ]
      ]);

  IF(NOT RecordExists(subargs))
  {
    Print("Syntax: wh cli-tool subcommand [--virtual] <port number>\n");
    TerminateScriptWithError("");
  }

  GetPrimary()->BeginWork();

  //Database stuff

  GetPrimary()->CommitWork();
}

MACRO Main()
{
  RECORD ARRAY syntax := [ [ name := "command", type := "param", required := TRUE ]
                         , [ name := "params", type := "paramlist" ]
                         ];

  RECORD args := ParseArguments(GetConsoleArguments(), syntax);

  SWITCH(RecordExists(args) ? args.command : "help")
  {
    CASE "subcommand"
    {
      SubCommand(args.params);
    }
    DEFAULT
    {
      Print("Syntax: wh cli-tool <command>\n");
      Print("  subcommand [--switch] <param>: Execute the subcommand\n");
      TerminateScriptWithError("");
    }
  }
}

OpenPrimary();
Main();