# Non-Interactive Mode

> Source: https://parallelworks.com/docs/ai/code/non-interactive

# Non-Interactive Mode

With the `-p` (`--prompt`) flag, `pw code` runs a single prompt to completion and exits (these docs also call this a one-shot run): no full-screen interface, no follow-up questions. This is the mode to use in scripts, CI jobs, and anywhere you want the agent's answer as program output.

```bash
pw code -p "find all TODO comments" owner:provider-name/model-name
```

A model is required in one-shot mode. Pass it as the positional argument or with `-m`. Organization provider models also require [`--allocation`](/docs/ai/code/models#allocations) (there is no picker to fall back to). List available model IDs with `pw ai models ls`.

Press <kbd>Ctrl</kbd>+<kbd>C</kbd> to cancel a run in flight.

## What Goes to stdout vs. stderr

In the default text output, the streams are separated so the result stays clean:

- **stdout** carries only the model's answer, streamed as it is generated.
- **stderr** carries everything else: tool activity as it happens (a `● ToolName(...)` line per call with a condensed result line beneath it), the final usage summary, and the session/resume hint.

That means command substitution and pipes capture just the answer:

```bash
RESULT=$(pw code -p "summarize the changes in HEAD in one sentence" owner:provider-name/model-name)
echo "$RESULT"
```

Add `2>/dev/null` to silence the progress output entirely, or `2>progress.log` to keep it. Progress lines are colorized only when stderr is a terminal, so redirected logs never contain escape codes.

## JSON Output

Pass `-o json` to get a single structured result object on stdout instead of streamed text (no progress is printed for the answer itself in this mode):

```bash
pw code -p "list the Go files in this repo" -o json owner:provider-name/model-name
```

```json
{
  "message": "The repository contains ...",
  "model": "owner:provider-name/model-name",
  "session_id": "20260719-153045-a1b2c3d4",
  "iterations": 4,
  "usage": {
    "input_tokens": 18000,
    "output_tokens": 1200,
    "total_tokens": 19200
  },
  "estimated_cost": "$0.0480"
}
```

| Field | Description |
| --- | --- |
| `message` | The model's final answer. |
| `model` | The model ID the run used. |
| `session_id` | The local session ID, usable with `pw code -r`. |
| `iterations` | How many model requests the agent loop made to finish the prompt. |
| `usage.input_tokens` | Total input (prompt) tokens across the run. |
| `usage.output_tokens` | Total output (completion) tokens across the run. |
| `usage.total_tokens` | Input plus output tokens. |
| `estimated_cost` | Estimated cost as a dollar string, e.g. `"$0.0480"`, based on platform-configured model rates. |

Extract fields with `jq`:

```bash
pw code -p "how many source files are in src/?" -o json owner:provider-name/model-name \
  | jq -r '.message, .estimated_cost'
```

## Permissions in One-Shot Runs

One-shot runs use the same [permission modes](/docs/ai/code/permissions) as interactive sessions, but there is no one to answer a prompt: any action that would normally ask for approval is **denied automatically** (it fails closed). The agent sees the denial and continues, working around the restriction or reporting it in its answer.

The same applies to workspace configuration: a one-shot run never prompts to approve a workspace's settings, MCP servers, commands, or agent definitions, so unapproved files are ignored with a notice on stderr. Launch `pw code` interactively once to approve them. See [Workspace Trust](/docs/ai/code/settings#workspace-trust).

For scripting, that means:

- `--permission-mode read-only` is the safe choice for analysis and question-answering runs.
- The default `accept-edits` mode auto-approves file edits inside the workspace, but shell commands that would normally prompt are denied unless pre-approved.
- `--allowedTools` pre-approves specific tools or commands, e.g. `--allowedTools 'Bash(git status:*)',ReadFile`.
- `--permission-mode bypass-permissions` runs every tool without prompting.

:::warning bypass-permissions runs everything
`bypass-permissions` gives the agent unrestricted tool access, including arbitrary shell commands. Use it only in environments where that is acceptable, such as a disposable CI container.
:::

## Subagents in One-Shot Runs

The agent may delegate parts of the prompt to [subagents](/docs/ai/code/subagents). In non-interactive mode, subagents always run **inline**: requests to run a task in the background are forced to block until the task finishes, so no work is lost when the process exits.

- Progress on stderr is coarse: one `● Task(...)`-style start line naming the subagent and its task, and one condensed result line when it completes. The subagent's individual tool calls are not streamed.
- Permission-gated commands a subagent runs fail closed, just like the main agent's.
- The JSON output contains only aggregate usage: subagent tokens and cost roll up into the run's `usage` and `estimated_cost` totals, and there is no per-subagent breakdown field.

## Resuming a One-Shot Session

Every one-shot run is saved as a local session. In text mode, stderr ends with the session ID and a ready-to-run resume command:

```text
Session: 20260719-153045-a1b2c3d4
Resume:  pw code -r 20260719-153045-a1b2c3d4 -m owner:provider-name/model-name
```

Run that command to reopen the conversation interactively, with the one-shot exchange as history. The reverse also works: combine `-r` with `-p` to continue a saved session with another non-interactive prompt, or use `-r latest` for the most recent session. See [Sessions & Resume](/docs/ai/code/sessions).

## Related Documentation

- [pw code Overview](/docs/ai/code): Feature overview and quick start
- [Permissions](/docs/ai/code/permissions): Permission modes and allow rules
- [Models & Allocations](/docs/ai/code/models): Model IDs and the `--allocation` flag
- [Sessions & Resume](/docs/ai/code/sessions): Resuming one-shot sessions
- [Subagents](/docs/ai/code/subagents): How delegated tasks behave
- [Usage & Costs](/docs/ai/code/usage-and-costs): What the usage and cost figures mean
- [pw code command reference](/docs/cli/pw/code): Full CLI reference