> ## 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, one-shot CLI command. It runs one agent
turn, prints the response, and exits instead of opening the interactive shell.
It uses the provider, integrations, and tools configured by `opensre onboard`.

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

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

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

For a structured alert investigation, use `opensre investigate` 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`, `denied_tools`,
and `error`. The `error` value is either `null` or an object with `message` and
`suggestion`.

| 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.      |
| `130`     | The invocation was interrupted with `SIGINT`. |
| `143`     | The invocation was terminated with `SIGTERM`. |