VERSE
078e5e817c
- macOS, Linux badge and AI suggestions showcase in README - Update user guide and docs for development
164 lines
5.6 KiB
Markdown
164 lines
5.6 KiB
Markdown
# User guide
|
|
|
|
Iris is a fast terminal autocomplete assistant written in Go. It wraps around your shell (Zsh, Bash, or Fish) to give you real-time command suggestions, a floating dropdown menu, and smart history search right where you type.
|
|
|
|
## Table of contents
|
|
|
|
- [Getting started](#getting-started)
|
|
- [Shortcuts](#shortcuts)
|
|
- [Configuration guide](#configuration-guide)
|
|
- [Reporting bugs](#reporting-bugs)
|
|
- [Developer documentation](dev/README.md)
|
|
|
|
## Getting started
|
|
|
|
### Dependencies
|
|
|
|
- OS: Linux or macOS
|
|
- Terminal emulator with ANSI color support
|
|
- Go 1.24 or newer (if building from source)
|
|
|
|
### Installation
|
|
|
|
#### Method 1: Install script (recommended)
|
|
|
|
```bash
|
|
curl -sSL https://raw.githubusercontent.com/versenilvis/iris/main/scripts/install.sh | sh
|
|
```
|
|
|
|
#### Method 2: Go install
|
|
|
|
```bash
|
|
go install github.com/versenilvis/iris@latest
|
|
```
|
|
|
|
#### Method 3: Build from source
|
|
|
|
```bash
|
|
git clone https://github.com/versenilvis/iris.git
|
|
cd iris
|
|
just reload
|
|
```
|
|
|
|
### Shell setup
|
|
|
|
Add an alias to your shell configuration file to launch Iris easily:
|
|
|
|
**Zsh (`~/.zshrc`):**
|
|
```zsh
|
|
if command -v iris >/dev/null 2>&1; then
|
|
alias i="iris"
|
|
fi
|
|
```
|
|
|
|
**Bash (`~/.bashrc`):**
|
|
```bash
|
|
if command -v iris >/dev/null 2>&1; then
|
|
alias i="iris"
|
|
fi
|
|
```
|
|
|
|
**Fish (`~/.config/fish/config.fish`):**
|
|
```fish
|
|
if command -v iris >/dev/null 2>&1
|
|
alias i="iris"
|
|
end
|
|
```
|
|
|
|
## Shortcuts
|
|
|
|
| Shortcut | Action | Description |
|
|
| :--------------------------------- | :---------------------- | :------------------------------------------------------------------------ |
|
|
| <kbd>Shift</kbd> + <kbd>Tab</kbd> | Toggle menu | Show or hide the suggestion menu. |
|
|
| <kbd>Esc</kbd> | Hide menu | Temporarily hide the menu until the next key press. |
|
|
| <kbd>Tab</kbd> | Accept suggestion | Insert the currently selected suggestion into the prompt. |
|
|
| <kbd>Enter</kbd> | Execute command | Close the menu and send the current command to the shell. |
|
|
| <kbd>↑</kbd> | Navigate up / history | Move the selection up, or open command history when the prompt is empty. |
|
|
| <kbd>↓</kbd> | Navigate down / history | Move the selection down, or open command history when the prompt is empty.|
|
|
| <kbd>→</kbd> | Accept ghost text | Accept the faded ghost text suggestion when the menu is open. |
|
|
| <kbd>←</kbd> / <kbd>→</kbd> | Move cursor | Move the cursor inside the input buffer. Disabled when the prompt is empty|
|
|
| <kbd>Ctrl</kbd> + <kbd>R</kbd> | Switch mode | Toggle between `spec` and `history` mode. |
|
|
| <kbd>Ctrl</kbd> + <kbd>A</kbd> | Beginning of line | Move the cursor to the start of the command line. |
|
|
| <kbd>Ctrl</kbd> + <kbd>E</kbd> | End of line | Move the cursor to the end of the command line. |
|
|
| <kbd>Ctrl</kbd> + <kbd>L</kbd> | Clear screen | Clear the terminal while preserving the input buffer and redrawing the menu. |
|
|
| <kbd>Ctrl</kbd> + <kbd>U</kbd> | Clear command | Remove the entire current command and close the menu. |
|
|
| <kbd>Ctrl</kbd> + <kbd>C</kbd> | Cancel command | Send `SIGINT`, clear the input buffer, and close the menu. |
|
|
| <kbd>Ctrl</kbd> + <kbd>W</kbd> | Delete word | Delete the word immediately before the cursor. |
|
|
|
|
> [!NOTE]
|
|
> With <kbd>Ctrl</kbd> + <kbd>A</kbd>, <kbd>Ctrl</kbd> + <kbd>E</kbd>, <kbd>Ctrl</kbd> + <kbd>W</kbd>, <kbd>Ctrl</kbd> + <kbd>U</kbd>, <kbd>Ctrl</kbd> + <kbd>L</kbd>, and <kbd>Ctrl</kbd> + <kbd>C</kbd>: they belong to your shell by default. IRIS handles them directly in raw mode so your cursor and menu stay in sync
|
|
|
|
## Configuration guide
|
|
|
|
Iris uses a clean TOML configuration file located at `~/.config/iris/config.toml`.
|
|
|
|
### Creating & viewing config
|
|
|
|
```bash
|
|
iris config init
|
|
iris config show
|
|
```
|
|
|
|
### Sample `config.toml`
|
|
|
|
```toml
|
|
[core]
|
|
version = 1
|
|
shell = "" # "zsh", "bash", "fish", or empty for auto-detection
|
|
mode = "last" # "last", "spec", or "history"
|
|
debug = false
|
|
|
|
[ui]
|
|
style = "modern" # "modern" or "classic"
|
|
ghost-text = true
|
|
max-suggestions = 100
|
|
max-height = 15
|
|
nerd-fonts = true
|
|
|
|
[git]
|
|
filter-active-branch = true
|
|
deduplicate-branches = true
|
|
|
|
[updater]
|
|
check-on-startup = true
|
|
channel = "stable" # "stable" or "nightly"
|
|
check-interval = "24h"
|
|
|
|
[ai]
|
|
enabled = false
|
|
provider = "groq" # "groq" or "ollama"
|
|
debounce_ms = 400
|
|
|
|
[ai.providers.groq]
|
|
endpoint = "https://api.groq.com/openai/v1/chat/completions"
|
|
api_key_env = "GROQ_API_KEY" # or set api_key directly
|
|
model = "llama-3.3-70b-versatile"
|
|
timeout_ms = 3000
|
|
|
|
[ai.providers.ollama]
|
|
endpoint = "http://localhost:11434/v1/chat/completions"
|
|
model = "qwen2.5-coder"
|
|
timeout_ms = 5000
|
|
```
|
|
|
|
> [!NOTE]
|
|
> Using `api_key_env` is recommended over hardcoding `api_key` in plain text to keep credentials out of configuration files.
|
|
|
|
## Reporting bugs
|
|
> [!NOTE]
|
|
> When submitting a bug report, please include:
|
|
> - A detailed description of the bug and steps to reproduce it
|
|
> - Relevant log files captured while running in debug mode
|
|
|
|
Run IRIS with debug mode:
|
|
```bash
|
|
iris -d
|
|
```
|
|
or `config.toml`:
|
|
```toml
|
|
debug=true
|
|
```
|
|
|
|
> [!IMPORTANT]
|
|
> **Since IRIS logs everything you type, you should only enable debug mode when you need to report bugs**
|