Positionals

Bare (non---) arguments, consumed in order. Declared in the positionals array of operation.

positionalRequired — must be present

Fails if missing.

const name = positionalRequired({
  type: typeString("person"),
  description: "The name of the person to greet",
});
// Usage:
//   my-cli Alice   →  "Alice"
//   my-cli  →  Error: <person>: Is required, but was not provided

Parameter	Type	Description
type	Type<Value>	Decoder for the raw string token
description	string?	Help text
hint	string?	Short note in parentheses

positionalOptional — may be absent

Falls back to a default when absent.

const greeting = positionalOptional({
  type: typeString("greeting"),
  description: "Custom greeting",
  hint: "default to 'Hello'",
  default: () => "Hello",
});
// Usage:
//   my-cli          →  "Hello"
//.  my-cli Howdy    →  "Howdy"

Parameter	Type	Description
type	Type<Value>	Decoder for the raw string token
description	string?	Help text
hint	string?	Short note in parentheses
default	() => Value	Value when absent — throw to make it required

positionalVariadics — zero or more

Consumes all remaining tokens into an array.

const files = positionalVariadics({
  type: typePath(),
  description: "Files to process",
});
// Usage:
//   my-cli a.ts b.ts c.ts   →  ["a.ts", "b.ts", "c.ts"]
//   my-cli  →  []

End delimiter

Optionally stop collecting at a specific sentinel token:

const args = positionalVariadics({
  type: typeString("argument"),
  endDelimiter: "STOP",
  description: "Arguments (end with STOP)",
});
// Usage:
//   my-cli foo bar STOP   →  ["foo", "bar"]

Parameter	Type	Description
type	Type<Value>	Decoder applied to each token
description	string?	Help text
hint	string?	Short note in parentheses
endDelimiter	string?	Sentinel token that stops collection

Ordering rules

Consumed in declaration order — required first, variadics last.

operation(
  {
    options: {},
    positionals: [
      positionalRequired({ type: typeString("src") }),
      positionalRequired({ type: typeString("dst") }),
      positionalOptional({ type: typeString("tag"), default: () => "latest" }),
      positionalVariadics({ type: typeString("extra") }),
    ],
  },
  async function (_ctx, { positionals: [src, dst, tag, extras] }) {
    /* ... */
  },
);
// Usage:
//   my-cli in out  →  src="in", dst="out", tag="latest", extras=[]
//   my-cli in out v2 a b c  →  src="in", dst="out", tag="v2", extras=["a","b","c"]