Skip to main content
Start the shell with opensre (needs a real terminal). Type a /command, or describe what you want in plain language.
When you type / and browse with the arrow keys, the hint line above the prompt shows the highlighted command’s description.
Confirmation prompts come from /auto (tool-approval autonomy) and from elevated slash commands. Default /auto is high (alpha: no tool prompts). /trust on skips approval prompts for the rest of the session. Outside a TTY, actions that would ask are blocked.

​
How the REPL works

TTY vs non-TTY: Interactive menus, confirmations, and onboarding wizards need a real terminal. Piping input or running in CI is non-interactive — prefer explicit CLI commands outside the REPL for automation. Unknown commands: Typos suggest the closest registered command (Did you mean /integrations?). Run /help for the authoritative list — it always matches your installed OpenSRE version. Keyboard shortcuts: When you first launch the shell with no scheduled loops, a picker offers three starter loops (CI/CD, task management, daily brief). Escape skips; the picker returns on the next launch until a loop exists. See Scheduled deliveries.

​
Quick reference

​
Help and exit

​
Session

​
Investigation

​
Integrations, models, and tools

​
Privacy and history

​
Tasks and background work

​
Watchdog

​
Agents and alerts

​
CLI parity

These commands delegate to the same Click CLI you would run outside the REPL.

​
System

​
Commands with interactive menus (TTY)

Bare invocation opens a picker or submenu:

​
Commands

​
Help

Help categories mirror the REPL grouping: Quick Access, Session, Integrations/Models/Tools, Investigation, Privacy, Tasks, Agents, Alerts, CLI parity, and System.Quick Access duplicates frequently used commands (/investigate, /integrations, /model, /health, /watch, /status, /help) for faster discovery in the picker.
Shortcut for /help. Same forms and picker behavior.

​
Session

Shows a snapshot of the current REPL session:
Typical fields:Use /status for session state. Use /health for integration connectivity.
Shows LLM usage tracked locally for the current REPL session. This is not cloud-provider billing and does not read your vendor invoice.
Example output (measured + estimated mix):
Measured vs estimated:When any estimate is included, the table title notes (includes estimates) and rows show measured vs estimated splits.What increments the counter: Normal LLM chat turns and planner calls. What does not: Non-LLM command handling such as history recall or prompt rendering.Token totals reset on /new or when session identity is rotated. They do not carry across /resume. See Session History.
Displays key/value infra metadata collected during investigations and chat — typically service, cluster, region, or similar fields extracted from alert text and investigation state.
Context is inherited across investigations in the same session (and restored by /resume). It is passed as overrides to subsequent /investigate runs so the pipeline does not re-ask for environment details you already established.
Set reasoning depth for OpenAI and Codex providers in this REPL session only.
Bare /effort prints the current level, the config default for your provider/model, and supported choices. /status includes the same field.Other providers (Anthropic, Ollama, etc.) ignore /effort; the shell prints a hint suggesting /model set openai or /model set codex. Set OPENSRE_REASONING_EFFORT in the environment for non-interactive defaults. See LLM providers.
Set how often the REPL asks before running agent tools. Shown on the status line as Auto (Med) · ….
/auto is not a shell-command allowlist: under alpha, shell strings still run when approved (or when High skips the prompt). Lower levels only promote the existing ask confirmation hook by tool_type.With /trust: /trust on skips approval prompts even when /auto would ask. Turn trust off to restore /auto prompts.Session preference only — not restored by /resume. Bare /auto prints the current level, the default, and each caption.
Trust mode skips execution confirmation prompts for elevated commands (/save, /watch, /cancel, /uninstall, integration remove, etc.).
In a TTY, bare /trust opens an interactive on/off menu. Trust mode is a session preference — it is not restored by /resume.
During watchdog demos or repeated /save exports, /trust on avoids confirmation fatigue. Turn it off before running destructive commands you might mistype.
Toggle TRACER_VERBOSE logging for the REPL process (deeper internal logs to stderr).
Clears the terminal and re-renders the OpenSRE banner. Does not reset session state, token usage, LLM conversation context, or accumulated infra context.
Summarizes older conversation context, keeps recent messages, and persists a compaction entry in the session file. Future /resume calls replay the summary before the kept messages.
If there are not enough messages to compact, the command reports nothing to compact. OpenSRE also compacts automatically before a shell turn when the replayed branch context exceeds the runtime threshold.
List up to 20 recent sessions stored on disk, newest first:
The current row updates duration live. Sessions with no name show (current) or ↩ <resumed-from> when applicable.
Restore LLM conversation context and accumulated infra context from a previous session.
Current session: If the ID prefix matches the session you are already in, /resume is a no-op — OpenSRE prints a hint to pick a previous session from /sessions.When you resume a different session, OpenSRE:
  1. Switches the active session file to the target session
  2. Restores cli_agent_messages so the assistant remembers prior turns
  3. Restores accumulated_context keys
  4. Reprints conversation history (user prompts, assistant replies, slash commands)
Compaction entries are replayed as summary messages before the kept branch messages.Restored vs not restored:Warning: Resuming a different session replaces the current session’s LLM context if messages already exist.Session replay reads the current version-2 session tree format. Older session files are ignored by /sessions and /resume. See Session History.
Rotate to a new session file while keeping the current LLM conversation thread and accumulated context.
Use /new after a long /resume so /sessions stays tidy without losing your place in the conversation.
Set a finish line and keep working toward it across turns:
Bare /goal shows the current goal. /goal set starts work immediately. See Goals for the full workflow.

​
Investigation

Three ways to start RCA from the REPL: Investigations inherit accumulated context from earlier runs in the same session.
Template names win over same-named files in the working directory. Force file mode: /investigate ./generic
During a run:
  • Output streams to the terminal like chat
  • Ctrl+C cancels and marks the task cancelled
  • /tasks shows the investigation task id and status
  • On completion, last_state is updated for /last and /save
  • Infra fields from the result merge into accumulated context
Errors: Missing files, unreadable paths, and pipeline failures print actionable messages; failed runs do not update last_state.
Print starter alert JSON to stdout — copy, edit, save, then /investigate your-file.json.
Reprint the root cause and report sections from the most recent successful investigation in this session.
Sections rendered when present: Root Cause, Report (from problem_md or slack_message). If no investigation ran yet, prints a dim empty-state message.
Write the last investigation to disk. Requires confirmation unless trust mode is on.
Parent directories must exist or be creatable; write failures print the underlying error.

​
Integrations, models, and tools

Read-only pass/fail report for the local OpenSRE agent, LLM connectivity, and each configured integration.
Runs live verification against the integration store. Use before incidents to confirm Datadog/Grafana/K8s credentials still work. For integration-only checks without the full agent/LLM report, prefer /verify.
Shortcut for integration connectivity checks (same as opensre integrations verify / make verify-integrations).
Bare /integrations opens an interactive menu in a TTY with service pickers for show/remove.
MCP-capable integrations only (subset of the full integration catalog).
Show or change LLM provider and models. Updates project .env (default: repository root .env, override with OPENSRE_PROJECT_ENV_PATH), ~/.opensre/opensre.json, and resets in-process LLM caches.
Credential guard: Switching to a provider without prompt-safe auth status fails fast with setup instructions. Run /auth login <provider> or export the provider API key before switching. If status is stale, run /auth verify <provider>.Reasoning vs toolcall model: Reasoning model drives chat and planning; toolcall model drives investigation tool invocation when the provider exposes a separate slot (common on Anthropic/OpenAI).Interactive /model menu flow: pick provider → reasoning model (or default) → optional toolcall model (keep, match-reasoning, or explicit).See LLM providers.
List tools available to investigation and chat surfaces in this build (name, source, surfaces).
There is no global /list command — use domain-specific list commands (see Natural language actions).

​
Privacy and history

Command history (up-arrow recall) is separate from session history (/sessions). Full redaction patterns and env vars: Interactive Shell Privacy.
Bare /history opens an interactive menu in a TTY (presets: 100, 500, 1000, 5000 for retention).
Redaction applies to the history file, not necessarily to what is sent to the LLM. Treat shared machines accordingly — run /history clear after sensitive sessions.
Shows persistence on/off, redaction on/off, retention cap, history file path, built-in pattern count, and a short threat-model reminder (unencrypted local disk).

​
Tasks and background

Long-running work is tracked in a per-session task registry surfaced by /tasks. Human todos and reminders are tracked separately by /work.
Example:
Shows up to 50 recent tasks, newest first. Use the id column (short prefix) with /cancel or /unwatch.
Human todos, reminders, and follow-ups — separate from /tasks (runtime jobs). See Work Management.You can also ask naturally:
  • Matches task id by prefix (must be unique among active/recent tasks)
  • Only running tasks accept cancellation
  • Investigations: signals cancel; press Ctrl+C if streaming continues
  • Watchdogs: prefer /unwatch for watchdog-specific messaging
Prints guidance only — does not kill processes:
Session-local async investigation mode. Launch an RCA, keep using the shell, and get the finished report delivered to email, Telegram, Rocket.Chat, or Buzz.
Channels are off by default. They are cleared when the REPL process exits; /new keeps notify prefs but clears jobs and turns background mode off. email requires smtp; telegram requires telegram; rocketchat requires rocketchat; buzz requires buzz. Interactive shell only — there is no opensre background … CLI command. Full guide: Background investigations.

​
Watchdog

Monitor a local process and send Telegram alarms when CPU, memory, or runtime thresholds breach. Configure Telegram credentials before use (via /onboard or env — see messaging docs).
On start:
When a threshold fires (Telegram configured):
Typical demo workflow:
  1. /trust on (optional — skips /watch confirmation)
  2. /watch <pid> --max-cpu 80 — use a real PID (e.g. the REPL’s Python process)
  3. /watches — confirm running status and threshold string
  4. /unwatch abc12 — request stop; /watches should show cancelled
Quoted values are supported: /watch 12345 --max-cpu "80".
Watchdog-only view with columns: id, pid, status, started, thresholds (from command summary), last sample (live CPU/RSS from progress line).
Cancels a watchdog task by task id. Using /cancel also works; /unwatch validates the task kind.
CLI-parity syntax (subprocess to opensre watchdog):
Prefer /watch inside the REPL — it registers tasks for /watches and /tasks automatically.

​
Agents and alerts

Fleet coordination is documented further on Agents. Register discovered agents with opensre fleet scan --register before /fleet trace targets them.
Kill confirmation: Without --force, prompts [y/N]. --force skips prompt (still elevated tier unless trust mode).
When the alert listener is active:If the listener is inactive, prints a warning. Incoming alerts also appear in /status as incoming alerts. Post alerts to your configured webhook/listener URL during setup; the REPL can start investigations from plain language.

​
Setup and ops (CLI parity)

These spawn opensre … subprocesses. Output is captured into the REPL buffer for non-interactive subcommands; wizards attach to the real TTY.
Log in to LLM providers, show local auth status, or clear stored credentials. Same as opensre auth. Interactive login prompts on the real TTY.
Shortcut for /auth login. Same provider flows as opensre auth login.
First-run setup: LLM keys, integrations, Telegram, alert listener. A blank LLM key defers provider setup instead of blocking the wizard. Requires exclusive stdin — the REPL tears down prompt_toolkit before the wizard runs.
Operate remote deployed OpenSRE agents (EC2, Nitro, hosted runtime). See Remote runtime investigation.
Copy sessions and memory to an object store you own (S3, GCS, Azure, Vercel Blob, or S3-compatible). Credentials and API keys stay local. See Sync to your own object store.
Read/write ~/.opensre/config.yml. Prefer env vars for secrets; use config for structured interactive-shell settings.
Scheduled investigation or report delivery. See Cron.
List recurring loops from the scheduler store, create manual prompt loops, run a loop once immediately, stop or restart a loop, delete a loop, and debug the next fire time. Onboarding creates draft examples such as a weekday morning report; active loops run through the cron scheduler when the gateway or opensre cron start is running.You can also ask naturally:
By default, new loops send to every configured default handle OpenSRE can reach: Telegram, Slack, and the local interactive-shell inbox.
Automated Sentry morning digest delivery (#10) and uptime watch notifications (#4032). Requires Sentry plus Telegram or Slack configured for the chosen provider. See Sentry.
Telegram bot pairing and sender allowlist — required for /watch alarms and some delivery features.
Tail Hermes logs and escalate classified incidents. See Hermes and Hermes runbook.
Related: Masking.
Synthetic tests can run for a long time; default timeout is generous — use /cancel to stop.
Checks PyPI and upgrades OpenSRE in-place (5-minute network timeout). Non-zero exit prints CLI error code.
Targeted smoke tests (Sentry, etc.) — subcommands match opensre debug --help.
Removes OpenSRE and local data. Destructive — confirmation required unless trust mode. Delegates to interactive CLI uninstall flow.

​
System

Environment diagnostic distinct from /health:
Checks Python version, venv, config paths, Docker availability, credential presence, and related local prerequisites. Each row: ok, warn, or error with detail text.Use /doctor before first install debugging; use /health before an incident to verify integrations.
Clean shutdown with a /resume hint. Prefer this over killing the terminal so session files flush cleanly./exit, /quit, double Ctrl+C, or Ctrl+D (empty prompt) all print something like:

​
Trust mode, /auto, and confirmations

Two controls decide whether the REPL prompts before an action: Non-TTY: actions that would ask fail closed (error message, no side effect).

​
Natural language actions

You do not need to memorize every slash command. Examples: List intents — there is no global /list: When the planner is uncertain, it asks for clarification or falls back to help — it does not silently run elevated commands. Compound requests (“health then integrations”) execute as an ordered sequence of slash actions.

​
Common workflows

​
First-time setup

If you skip onboarding’s LLM key, later turns that need a model point you at /auth login instead of a raw provider error. On first launch with no scheduled loops, the shell offers three starter loops — Escape skips. See Scheduled deliveries.

​
Incident triage (local)

Paste alert text or:

​
Pick up yesterday’s thread

Continue chatting, then optionally:

​
Switch model mid-session

​
Monitor a runaway process

​
Debug integration failures

​
Troubleshooting