Anwesh
837a66f1f1
* feat(agent): enforce host hooks during gather - compose multiple tool hook sets without losing lifecycle callbacks - forward per-turn approval hooks into evidence gathering - cover hook composition and gather propagation * feat(cli): add ask approval policy - gate mutating, external, approval-required, and unclassified tools - support exact per-invocation allowlists and broad bypass - track denied tools safely across concurrent calls * feat(cli): add one-shot ask command * feat(agent): classify action tool side effects * docs(cli): document ask approvals * style(cli): format ask package * fix(cli): respect ask surface boundaries - import harness components through public API modules\n- keep one-shot ask out of recursive REPL command parity\n- disable slash actions without importing shell adapters * fix(cli): keep ask sink surface-owned - preserve the exact public harness runtime API\n- provide a minimal CLI-owned output sink for one-shot turns * fix(cli): handle signals while reading ask stdin - install ask signal handling before prompt resolution\n- return stable JSON cancellation and signal exit codes\n- cover prompt-resolution interrupts and handler restoration * test(cli): pin ask invocation boundaries - verify root --yes never bypasses tool approvals\n- verify exact case-sensitive allowlist matching\n- verify sessions close after turn failures and JSON stays on stdout * docs(cli): present ask as headless CLI - rename the guide and navigation entry to Headless CLI - describe opensre ask as a one-shot non-interactive command * docs(readme): add headless CLI quick start - show the one-shot ask command in the run-mode overview - link to the Headless CLI guide for automation and approval details
73 lines
2.3 KiB
Plaintext
73 lines
2.3 KiB
Plaintext
---
|
||
title: "Headless CLI"
|
||
slug: "headless-cli"
|
||
description: "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
|
||
opensre ask "why did checkout latency increase today?"
|
||
```
|
||
|
||
Pass `-` as the prompt to read all of standard input:
|
||
|
||
```bash
|
||
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
|
||
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
|
||
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
|
||
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`. |
|