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

# How to use opsh

> Learn how to use the Opsh interactive shell — type natural-language requests, review AI-generated commands, and control execution from a persistent prompt.

The Opsh REPL is an interactive prompt where you type natural-language requests and Opsh translates them into shell commands in real time. It runs as a persistent session, so your working directory, history, and session state are preserved between requests.

## Starting the REPL

Run `opsh` with no arguments to open the REPL:

```bash theme={null}
opsh
```

Opsh starts a shell session, loads your configuration and recent shell history, then drops you into the interactive prompt.

## The prompt

The prompt shows your current directory followed by `>`:

```text theme={null}
projects >
```

When you're in your home directory, it displays `~` instead of the full path:

```text theme={null}
~ >
```

## Typing a request

Type your request in plain English and press Enter. You don't need to remember any command syntax — just describe what you want to do:

```text theme={null}
~ > show me the 10 largest files in this directory
```

Opsh sends your request to your configured AI provider, which generates a shell command. Opsh then displays the command, a brief explanation of what it does, and its risk level before asking whether to run it.

## The confirmation prompt

After Opsh shows the generated plan, it waits for your response:

| Key          | Action                                     |
| ------------ | ------------------------------------------ |
| Enter or `y` | Run the command                            |
| `n`          | Cancel without running                     |
| `e`          | Edit the command before running            |
| `r`          | Regenerate with a different interpretation |

If you press `e`, Opsh shows an edit prompt where you can modify the command directly:

```text theme={null}
Edit command >
```

If you press `r`, Opsh asks the AI to produce a safer or simpler alternative.

## Example session

```text theme={null}
~ > show me the 10 largest files in this directory

  Command   du -ah . | sort -rh | head -10
  Explains  Lists files and directories by size, sorted largest first, showing the top 10.
  Risk      safe

[Enter/y] run  [n] cancel  [e] edit  [r] regenerate

projects > find all .log files older than 7 days

  Command   find . -name "*.log" -mtime +7
  Explains  Searches the current directory recursively for .log files not modified in the last 7 days.
  Risk      safe

[Enter/y] run  [n] cancel  [e] edit  [r] regenerate
```

## Keyboard shortcuts

* **Ctrl+C** — cancels the current input and returns to a fresh prompt. It does not exit Opsh.
* **Up arrow** — cycles through your shell history within the REPL session, the same as in a standard terminal.

## Exiting

Type `!exit` or press **Ctrl+D** to exit the REPL and return to your shell.

<Note>
  If you installed Opsh with shell integration, the REPL starts automatically whenever you open a new terminal window. You can disable this by running `!uninstall` to remove the shell integration, or by editing your shell startup file directly.
</Note>