@nwire/please

Operator CLI — dispatch any registered action or query (and operator-script commands) from the command line.

runPlease({ apps, commands, argv }) boots every registered app, looks up the named target in the supplied commands first (operator scripts take precedence) then in each app's action/query surface, seeds an envelope, dispatches, prints the result. Same handlers as HTTP/queue — operator parity guaranteed.

pnpm add @nwire/please

Quick example

#!/usr/bin/env node
import { runPlease, defineCommand } from "@nwire/please";
import { z } from "zod";
import { apps } from "../app/apps";

const backfillUsers = defineCommand("backfill-users", {
  describe: "Re-hydrate users from the external source",
  args: z.object({ since: z.string().optional() }),
  handler: async ({ args, ctx }) => {
    const repo = ctx.resolve<UserRepo>("UserRepo");
    return { updated: await repo.backfill(args) };
  },
});

const code = await runPlease({
  apps,
  commands: [backfillUsers],
  argv: process.argv.slice(2),
});
process.exit(code);

please backfill-users --since 2026-01-01    # operator script (takes precedence)
please submissions.flag-for-review --submissionId xyz --confidence 0.4
please lessons.start-attempt --lessonId hebrew-1 --studentId avi
please submissions.by-student --studentId avi --status under-review
please --help

Surface

| Export | Role | | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | runPlease({ apps, commands?, argv, … }) | Boot apps, dispatch one target, return exit code (0 / 1). | | defineCommand(name, meta) | Operator-script primitive. { describe?, args?, handler }. | | CommandDefinition / CommandContext / CommandHandler / CommandMeta / CommandArgsSchema | Types for command authors and consumers. |

Resolution order

runPlease resolves argv[0] in this order:

1. commands[] — operator scripts shadow domain names on purpose.
2. Any app's action surface.
3. Any app's query surface (projection-backed reads).

Args parsers are duck-typed — any object with .parse(input) → output works, so a z.object({...}) schema is the obvious choice.

defineCommand captures $source so Studio's Commands page can render IDE-link chips.

Related

• @nwire/forge — supplies the App / AppDefinition / HandlerContext types runPlease and defineCommand build on.
• @nwire/cli — nwire please <name> delegates to this package.
• @nwire/scan — emits .nwire/commands.json so Studio + AI surfaces see every operator script.

Status

v0.x — runPlease argv contract + defineCommand shape are locked. Scaffolders (make:module, make:action) land on top in a follow-up.