xnpm ask

Natural language for intent.
Deterministic commands
for execution.

xnpm ask and xgit ask are not LLM features. Same input always produces the same command. Unknown input fails with suggestions, not guesses.

How ask works

Phrase catalogs, not
language models.

xnpm ask resolves intent phrases to real xnpm commands using a known, finite catalog. There is no model inference, no probability, and no guessing involved.

LLM shell May invent commands. Output varies per run.
xnpm ask Same phrase → same command. Deterministic. Always.
  • ✓
    Same input, same outputThe phrase catalog is static. Identical inputs always resolve to the same command.
  • ✓
    Unknown input fails safelyIf the phrase is not in the catalog, xnpm returns an error and suggests the closest known commands.
  • ✓
    Dangerous operations require approvalIrreversible commands (publish, push) show the plan and require explicit confirmation before running.
No hallucinated shell. No guessing. No magic.
known phrase
$ xnpm ask "publish all @x12i packages and push" → Resolved: xnpm --filter "@x12i/*" --build --test --publish --push --report Publish and push are irreversible. Continue? y/N > y
unknown phrase
$ xnpm ask "deploy to staging and pray" ✕ No safe match found. Did you mean: xnpm --publish xnpm --push xnpm --full-flow

Three guarantees

What ask always does.

Deterministic
Same phrase, same command

No variance between runs. No model drift. Scripting and automation can rely on ask output.

Safe failure
Unknown = error, not guess

If a phrase is not in the catalog, ask returns an error with the closest matching suggestions — never an invented command.

Transparent
Shows the plan before running

Irreversible operations always print the resolved command and ask for confirmation. No silent destructive actions.

Order modifiers & xgit

Phrases that compose.
Catalog order by CLI.

ask-cli 1.1.0 recognizes modifier phrases like in the right order without duplicating catalog entries. Order modifiers attach to publish/install intents and show in the resolved plan as Recognized: ….

dependency order
$ xnpm ask "publish everything in the right order" → Resolved: xnpm --build --test --publish --report Recognized: in dependency order
xgit — git catalog first
$ xgit ask "commit and push" → git phrases resolve first; xnpm/npm catalogs cross-solve monorepo steps $ xgit ask "publish all packages and push"

xnpm resolves xnpm → npm → git catalogs. xgit resolves git → xnpm → npm. Same engine, different default intent. Install both with npm install -g @x12i/npm — see Install → xgit.

Code-agent-safe ask — 2.30.0

Resolve intent without
risking a stuck shell.

For code agents, ask is a resolver first. Use --plan --json to get the matched command, argv, risks, explanation, and suggested execution command without running anything. In non-TTY mode xnpm will not wait for approval; if approval is needed, it exits with code 4 instead of blocking on stdin.

  • ✓
    --plan resolves without executingReturns the matched command, argv, and risk assessment — nothing runs.
  • ✓
    --json for machine-readable outputSame resolution, structured for a calling agent instead of a human reading a terminal.
  • ✓
    Never blocks on stdin in agent contexts--agent, XNPM_AGENT=1, CI=true, or non-TTY mode skip the interactive approval prompt entirely.
  • ✓
    Deterministic refusal, not a hangIf execution needs approval and approval was not provided, xnpm prints the plan and exits with code 4. TTY behavior for humans is unchanged.
agent plan, then execute
$ xnpm ask "release the stack" --plan --json → { command, argv, risks, explanation, suggestedYesCommand } $ XNPM_AGENT=1 xnpm ask "release the stack" ✕ exit 4 — approval required, plan printed $ xnpm ask "release the stack" --yes ✓ executes — approval given explicitly

ask-cli library

Build your own
deterministic ask command.

@x12i/ask-cli is the library behind xnpm ask. Any CLI can use it to add deterministic natural-language resolution without adding an LLM dependency.

@x12i/ask-cli
import { createAskCli } from '@x12i/ask-cli'; const askCli = createAskCli({ catalog }); const result = await askCli.resolve({ input, context, });
Install
npm install @x12i/ask-cliStandalone library, no LLM dependency