Single positional (required) arg with Typescript support: I failed at building this

I just spent a little too much time trying to write an example program which accepts one positional (required) argument url of type string.

At the same time I wanted for Typescript to know that the corresponding property url is defined and of type string.

I could not really get this working to my satisfaction and came across some road blocks.

I am new to yargs and also still rather new to Typescript so maybe I failed in an embarrassing way. But I think this feedback is still rather useful, because I really went through docs and examples.

Here is what I tried:

  const opts = yargs
    .command("* <url>", "default command", yargs => {
      yargs.positional("url", {
        describe: "base URL",
        type: "string",
      });
    })
    .help().argv;

To get there I had to figure out that

• you can define positional arguments only in the context of a command and that there is the magical default command * (this may be fine but was surprising complexity).
• you have to add a magical string of shape <param> to the first argument of .command() to make the positional argument be actually "required" (this is surprising, coming from world where a positional arg is implicitly required).
• there may be more ways to mark a positional argument as "required" but a corresponding option is currently not documented within opts).

Now, with above's code I get proper help text and error message when the argument is omitted. That's cool.

In the subsequent code, though, opts.url is of type unknown and https://github.com/yargs/yargs/blob/master/docs/typescript.md didn't really help me fix that.

I found https://github.com/yargs/yargs/issues/1393 and https://github.com/DefinitelyTyped/DefinitelyTyped/issues/37797 though and they seem to be quite related.

For now I am using argparse:

  const parser = new argparse.ArgumentParser();
  parser.addArgument("url", {
    help: "base URL"
  });

which requires quite a bit less mental overhead.

Any help appreciated.

For yargs, I think we should definitely add a documentation example that shows how to get going with this use case: single positional (required) arg with proper Typescript support.

Start with docs/typescript.md and the positional API section in docs/api.md, then compare them with the issue's single-argument example. Document a complete example for one required url positional argument with TypeScript-aware output, including the relevant command syntax and typing approach. Done means a newcomer can follow the example and obtain a typed url value.