# caique/prompt-for

> Every export of caique/prompt-for, with its signature and doc comment: promptFor, PromptRefusal, plus 5 types.

Source: https://caique.interlace.tools/docs/api/prompt-for

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

```ts
import { promptFor, PromptRefusal } from 'caique/prompt-for';
```

## Functions

### promptFor

Wrap a command so that its declared prompts are resolved before its handler runs (R1, R2, R6).

```ts
function promptFor<T extends PromptableCommand>(command: T & CarriesContext<T>, name?: string, spec?: PromptSpec, opts?: PromptForOptions): T;
```

| Parameter | Type |
| :-- | :-- |
| `command` | `T & CarriesContext<T>` |
| `name` (optional) | `string` |
| `spec` (optional) | `PromptSpec` |
| `opts` (optional) | `PromptForOptions` |

**Returns** `T`

## Classes

### PromptRefusal

A refusal a handler throws: burgee reads `code` by name, prints `message` and `fix` (P2, P3).

```ts
class PromptRefusal extends Error {
    readonly code: ResolveFailure['code'];
    readonly fix: string | undefined;
    /** The option or positional it stopped at, by its declared name. */
    readonly option: string;
    constructor(failure: ResolveFailure);
}
```

## Interfaces

### PromptableArgument

A positional as `promptFor` reads it. burgee's `ArgumentSpec` satisfies it.

```ts
interface PromptableArgument extends PromptableSpec {
    name: string;
}
```

### PromptableCommand

A command as `promptFor` reads it. burgee's `Command` satisfies it. `run` takes the host's own
context, whatever it is called; {@link promptFor} checks that it carries a {@link PromptContext}.

```ts
interface PromptableCommand {
    options?: Record<string, PromptableSpec>;
    arguments?: readonly PromptableArgument[];
    run?: (ctx: never) => unknown;
}
```

### PromptableSpec

An option as `promptFor` reads it. burgee's `OptionSpec` satisfies it; the rest of a host's spec is carried as it is.

```ts
interface PromptableSpec {
    required?: boolean;
    prompt?: PromptSpec;
    [field: string]: unknown;
}
```

### PromptContext

What `promptFor` reads of a host's run context. burgee's `RunContext` satisfies it.

```ts
interface PromptContext {
    options: Record<string, unknown>;
    /** The declared positionals by name. */
    args: Record<string, unknown>;
    /** The positionals as typed; an answered one is written in at its declared place. */
    positionals: string[];
    env: Record<string, string | undefined>;
    /** Whether a person may be asked: a terminal on stdin, no `CI`, no agent (N12) — the host's answer. */
    interactive: boolean;
    /** The run was asked for `--json`, which an `--mcp` tool call always is (R6): nobody is there to type. */
    json?: boolean;
    /** The host's exit path (E5): what closes the terminal if the run is ended mid-question. */
    onExit?: (handler: () => void, label?: string) => () => void;
}
```

### PromptForOptions

```ts
interface PromptForOptions {
    /** Where to ask; the process's stdin and stderr when omitted, opened only if a question is asked. */
    io?: Io;
}
```