Parameters

Parameters are the values a route reads from the command line. There are three kinds:

• option() reads a named value, such as --limit 30.
• toggle() reads an on or off switch, such as --draft.
• argument() reads a positional value, such as the bombshell-dev/router in gh repo clone bombshell-dev/router.

Each parameter belongs to the route that declares it, and its value appears in that route’s model.

Add an option

option(name("body")) reads --body <value> or --body=<value>. The flag is the kebab-case form of the name, so option(name("bodyFile")) reads --body-file. When the flag is absent, the value is undefined.

Validate with a schema

Without a schema, a parameter’s type is unknown. Add schema() with any Standard Schema library to give it a type, a default, or a requirement:

import process from "node:process";
import { command, name, option, parse, schema } from "@bomb.sh/router";
import * as z from "zod";

const app = command(
  name("create"),
  option(name("body")),
  option(name("base"), schema(z.string().default("main"))),
  option(name("title"), schema(z.string())),
);

const result = parse(app, { argv: process.argv.slice(2) });

if (result.ok && result.method === "execute") {
  result.model.body; // unknown
  result.model.base; // string
  result.model.title; // string
}

A schema that rejects undefined makes the parameter required. Here --title is required, so create alone fails with unprocessable-content:

title: Invalid input: expected string, received undefined

Invalid values fail the same way, and they never reach your application.

Know how values are decoded

Command-line text is decoded before the schema sees it. The router tries a number first, then the original text, and the schema picks the first candidate it accepts. Without a schema, the first candidate wins:

Input	No schema	schema(z.string())
--milestone 2024	2024	"2024"
--milestone 007	7	"007"
--milestone 1e3	1000	"1e3"
--milestone v2	"v2"	"v2"

To keep text that looks like a number, such as a milestone or a version, use a string schema.

Add a toggle

toggle(name("draft")) reads a switch. It is true with --draft, false with --no-draft, and false when absent. Its type is always boolean, so it needs no schema. --draft=false is not accepted.

Read positional arguments

argument(name("repository")) reads one positional value. A second positional value, such as the docs in clone bombshell-dev/router docs, fails with unexpected: `docs` . As with options, add a schema to make the argument required or typed:

import { argument, command, name, schema } from "@bomb.sh/router";
import * as z from "zod";

const clone = command(
  name("clone"),
  argument(name("repository"), schema(z.string())),
);

Accept repeated values

multiple() turns a parameter into a list. An option collects every occurrence, so --label bug --label docs reads ["bug", "docs"]. An argument collects every positional value, so gist create a.ts b.ts reads ["a.ts", "b.ts"]. With multiple(), the schema validates the whole list:

import {
  argument,
  command,
  multiple,
  name,
  option,
  schema,
} from "@bomb.sh/router";
import * as z from "zod";

const prCreate = command(
  name("create"),
  option(
    name("label"),
    multiple(),
    schema(z.array(z.string()).default([])),
  ),
);

const gistCreate = command(
  name("create"),
  argument(
    name("files"),
    multiple(),
    schema(z.array(z.string())),
  ),
);

Both values are typed string[]. Without --label, the default gives an empty list.

Rename a flag

cli() replaces the flags an option reads. After cli(["--repo", "-R"]), an option named repository reads --repo and -R, and --repository is no longer accepted:

import { cli, command, name, option, schema } from "@bomb.sh/router";
import * as z from "zod";

const app = command(
  name("list"),
  option(name("repository"), cli(["--repo", "-R"]), schema(z.string())),
  option(name("web"), cli(["--web", "-w"], { switch: true })),
);

For most on or off flags, use toggle() instead. It reads --web and --no-web, defaults to false, and is always a boolean.

{ switch: true } makes an option take no value. --web or -w reads true, the value is undefined when absent, and its type is unknown unless you add a schema. Use it only when you need something a toggle cannot do, such as a short flag like -w.

Read a different environment variable

When you pass the environment to parse(), each parameter also reads a variable named after its route and its name. The repo option of the /pr/list route reads PR_LIST_REPO. env() replaces that name:

import process from "node:process";
import {
  command,
  env,
  name,
  option,
  parse,
  route,
  schema,
} from "@bomb.sh/router";
import * as z from "zod";

const app = command(
  name("gh"),
  route(
    name("pr"),
    command(
      name("list"),
      option(
        name("repo"),
        env("GH_REPO"),
        schema(z.string().optional()),
      ),
    ),
  ),
);

const result = parse(app, {
  argv: process.argv.slice(2),
  envs: [{ name: "process", value: process.env }],
});

With env("GH_REPO"), GH_REPO=bombshell-dev/router gh pr list sets the repository, and PR_LIST_REPO is ignored.