> ## Documentation Index
> Fetch the complete documentation index at: https://opensre.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Headless CLI

> Run one OpenSRE agent turn non-interactively from a terminal, script, or CI job.

`opensre ask` is OpenSRE’s headless CLI command. It runs one agent turn, prints
the response, and exits instead of opening the interactive shell. Each run is
saved as a resumable session unless you pass `--ephemeral`.
It uses the LLM provider from `opensre onboard` and any tools configured with
`opensre integrations setup`.

```bash theme={null}
opensre ask "why did checkout latency increase today?"
```

## Follow-ups and required input

When the agent completes the request, a terminal run prints a session ID and a
command you can use for a later follow-up:

```text theme={null}
Session: 489e2ba8-3b7f-4fa2-bcdf-55a93177337c
Continue: opensre ask --resume 489e2ba8-3b7f-4fa2-bcdf-55a93177337c "<reply>"
```

Use the full ID or an unambiguous prefix:

```bash theme={null}
opensre ask --resume 489e2ba8 "now check the last deployment"
```

If the agent cannot continue without a decision, it exits with status
`needs_input` and prints numbered options. Resume the same session with the
option number, or a custom answer when the question allows one:

```bash theme={null}
opensre ask --resume 489e2ba8 "1"
```

For a batch of questions, pass a JSON object keyed by the displayed labels:

```bash theme={null}
opensre ask --resume 489e2ba8 '{"Repository":"1","Window":"2"}'
```

Use `--ephemeral` for scripts or one-off requests that should not write
resumable session history or print a session ID:

```bash theme={null}
opensre ask --ephemeral "summarize this public status page"
```

[Prompt and response logging](/docs/interactive-shell-privacy#prompt-and-response-logging)
has separate controls. Set `OPENSRE_PROMPT_LOG_DISABLED=1` to disable it,
including for ephemeral requests.

## Live activity

When both output streams are attached to a terminal, `ask` starts with a
`Thinking…` spinner with elapsed time. It switches to the active diagnostic
tool (or a neutral tool count for a batch) when tools are invoked. The final
answer remains on standard output without echoing raw tool transcripts. Piped
and `--json` runs do not emit progress, so their output remains
machine-readable.

Pass `-` as the prompt to read all of standard input:

```bash theme={null}
cat incident-notes.txt | opensre ask -
```

## File context

Attach an alert, log excerpt, deployment note, or other regular UTF-8 text file with
`-i` or `--context-file` while keeping the positional prompt as the instruction:

```bash theme={null}
opensre ask -i alert.json \
  "investigate this alert and explain the likely cause"
```

Repeat the option to correlate several files:

```bash theme={null}
opensre ask \
  -i alert.json \
  -i deployment.md \
  "correlate the alert with the recent deployment"
```

Attach up to 16 files. Files are treated as untrusted context, not operator
instructions. Each file may contain up to 64 KiB, with a combined limit of 128
KiB. Empty, binary, and non-UTF-8 files are rejected before the agent starts.
The combined limit also applies after JSON encoding, so content dominated by
control characters, quotes, or backslashes may reach it earlier.

When a resumed session is waiting for a numbered choice, submit that answer
without context files. Attach files in the following turn instead.

## Tool approvals

Read-only tools run automatically. Tools that mutate state, contact an external
service, explicitly require approval, or do not declare their side effects are
denied by default.

Authorize only the tools needed for this invocation by repeating
`--allowed-tool`:

```bash theme={null}
opensre ask "inspect the repository and run its focused tests" \
  --allowed-tool shell_run \
  --allowed-tool github_cli
```

An unknown tool name is rejected before the agent starts. The authorization is
not saved and applies only to that process. The root `--yes` (`-y`) option does
not authorize agent tools.

`--dangerously-bypass-approvals` authorizes every approval-gated tool for that
invocation. Use it only in a trusted environment where the prompt and connected
integrations are controlled:

```bash theme={null}
opensre ask "perform the requested maintenance" --dangerously-bypass-approvals
```

Do not combine the bypass flag with `--allowed-tool`. Neither option bypasses
the operating-system permissions or sandboxing that applies to OpenSRE.

## JSON output and exit codes

Put the global `--json` option before `ask` for machine-readable output:

```bash theme={null}
opensre --json ask "summarize current service health"
```

The command writes one JSON object with `status`, `response`, `session_id`,
`questions`, `denied_tools`, and `error`. Each question includes its title,
label, options, whether it accepts multiple selections, and whether a custom
answer is allowed. The `error` value is either `null` or an object with
`message` and `suggestion`.

For required input, read `session_id` and `questions` from that object, then
pass the answer to another JSON invocation of the same session:

```bash theme={null}
opensre --json ask "investigate the failing CI"
opensre --json ask --resume 489e2ba8-3b7f-4fa2-bcdf-55a93177337c "1"
```

The first result can be `needs_input` (exit code `4`) with a question like:

```json theme={null}
{"status":"needs_input","response":"Which repository?\n  1. Tracer-Cloud/opensre\n  2. Another repository","denied_tools":[],"session_id":"489e2ba8-3b7f-4fa2-bcdf-55a93177337c","questions":[{"label":"Repository","title":"Which repository?","options":["Tracer-Cloud/opensre","Another repository"],"multi_select":false,"allow_custom":true}],"error":null}
```

After the answer, a successful result has `status: "success"`, the same
`session_id`, and an empty `questions` array.

JSON mode emits no terminal-only continuation footer; use the returned ID.
`--json` is a global option, so it must appear before `ask` on both invocations.
Without `--json`, a required question also prints `Session: ID` on stderr when
output is redirected, so the choice can still be resumed.

| Exit code | Meaning                                                             |
| --------- | ------------------------------------------------------------------- |
| `0`       | The agent completed the request.                                    |
| `1`       | Setup or agent execution failed.                                    |
| `2`       | The command arguments were invalid.                                 |
| `3`       | A tool required approval and was denied.                            |
| `4`       | The agent needs structured user input; resume the returned session. |
| `130`     | The invocation was interrupted with `SIGINT`.                       |
| `143`     | The invocation was terminated with `SIGTERM`.                       |