diff --git a/README.md b/README.md index 9e8444f..b5cc7bb 100644 --- a/README.md +++ b/README.md @@ -12,10 +12,10 @@ [![Status](https://img.shields.io/badge/status-beta-yellow?style=for-the-badge&logo=github&logoColor=white)]() [![License: 0BSD](https://img.shields.io/badge/License-0BSD-blue?style=for-the-badge&logo=github&logoColor=white)](./LICENSE) - [![Documentation](https://img.shields.io/badge/docs-available-brightgreen?style=for-the-badge&logo=github&logoColor=white)](./docs/README.md) + [![Documentation](https://img.shields.io/badge/docs-available-brightgreen?style=for-the-badge&logo=github&logoColor=white)](#install) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen?style=for-the-badge&logo=github&logoColor=white)](./CONTRIBUTING.md) - Comparison · Installation · Docs · Shortcuts · Configuration · Reporting bugs + Comparison · Install · Shortcuts · Configuration · Reporting bugs
@@ -43,7 +43,7 @@ Run iris wherever you already work; your local machine, a remote server, or anyw IRIS has AI suggestions like your code editor (API key/Local)
-## Why Iris instead of Fig +## Why IRIS instead of Fig > [!IMPORTANT] > **[Fig](https://app.fig.io/) was officially sunset in September 2024 and migrated to Amazon Q Developer (which requires cloud authentication and proprietary bloat)** @@ -51,7 +51,7 @@ Run iris wherever you already work; your local machine, a remote server, or anyw ### How it compares -| Feature | Iris | Fig | +| Feature | IRIS | Fig | | :-------------------------- | :------------------- | :--------------- | | **Platforms** | Linux, macOS | macOS only | | **Engine** | Native Go (TTY) | Electron | @@ -60,13 +60,13 @@ Run iris wherever you already work; your local machine, a remote server, or anyw | **Remote SSH** | TTY-native, portable | macOS GUI-bound | | **Tmux** | ✓ | Limited | | **Linux virtual terminals** | ✓ | - | -| **Memory** | < 15 MB | Electron runtime | +| **Memory** | Lightweight | Electron runtime | ## Why not shell autocomplete plugins? Shell plugins are great, but they also come with trade-offs. And also, not everyone use Zsh or Fish especially on SSH. -| Feature | Iris | Shell plugins | +| Feature | IRIS | Shell plugins | | :-------------------------- | :---------------------- | :--------------------------- | | **Installation** | Single binary | Plugin manager required | | **Shell support** | Most shells supported | Usually shell-specific | @@ -75,15 +75,157 @@ Shell plugins are great, but they also come with trade-offs. And also, not every | **Tmux** | ✓ | Depends on the shell | | **Linux virtual terminals** | ✓ | Depends on the shell | -## Installation +## Install + +#### Dependencies + +- OS: Linux or macOS +- Terminal emulator with ANSI color support +- Go 1.24 or newer (if building from source) + + +#### 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/cmd/iris@latest +``` + +#### Method 3: Build from source (for developers) + +```bash +git clone https://github.com/versenilvis/iris.git +cd iris +just reload +``` + > [!WARNING] > Currently, Windows is not supported +## Uninstall + +To completely uninstall IRIS, remove all configurations, and clean up your shell integration files, simply run: + +```bash +iris uninstall +``` + +## 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 +``` +## 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 +expand-alias = true + +[ui] +style = "modern" # "modern" or "classic" +ghost-text = true +hidden-files = false +max-suggestions = 100 +max-height = 15 +nerd-fonts = true + +[keybindings] +toggle-mode = "ctrl+r" +toggle-menu = "ctrl+space" + +[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 + +# please use free subscription, that is enough for your daily usage +[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. + + +## Default shortcuts + +| Shortcut | Action | Description | +| :--------------------------------- | :---------------------- | :------------------------------------------------------------------------ | +| Shift + Tab | Toggle menu | Show or hide the suggestion menu. | +| Esc | Hide menu | Temporarily hide the menu until the next key press. | +| Tab | Accept suggestion | Insert the currently selected suggestion into the prompt. | +| Enter | Execute command | Close the menu and send the current command to the shell. | +| ↑ | Navigate up / history | Move the selection up, or open command history when the prompt is empty. | +| ↓ | Navigate down / history | Move the selection down, or open command history when the prompt is empty.| +| → | Accept ghost text | Accept the faded ghost text suggestion when the menu is open. | +| ← / → | Move cursor | Move the cursor inside the input buffer. Disabled when the prompt is empty| +| Ctrl + R | Switch mode | Toggle between `spec` and `history` mode. | +| Ctrl + A | Beginning of line | Move the cursor to the start of the command line. | +| Ctrl + E | End of line | Move the cursor to the end of the command line. | +| Ctrl + L | Clear screen | Clear the terminal while preserving the input buffer and redrawing the menu. | +| Ctrl + U | Clear command | Remove the entire current command and close the menu. | +| Ctrl + C | Cancel command | Send `SIGINT`, clear the input buffer, and close the menu. | +| Ctrl + W | Delete word | Delete the word immediately before the cursor. | + +> [!NOTE] +> With Ctrl + A, Ctrl + E, Ctrl + W, Ctrl + U, Ctrl + L, and Ctrl + C: they belong to your shell by default. IRIS handles them directly in raw mode so your cursor and menu stay in sync + ## Theme
Kitty terminal showcase @@ -108,14 +250,34 @@ curl -sSL https://raw.githubusercontent.com/versenilvis/iris/main/scripts/instal -## Docs +## 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 -- [Getting started](./docs/README.md#getting-started): dependencies, installation methods, and shell integration setup -- [Shortcuts](./docs/README.md#shortcuts): core navigation, shortcuts table, mode switching, and ghost text -- [Configuration guide](./docs/README.md#configuration-guide): TOML configuration settings including AI provider options -- [Reporting bugs](./docs/README.md#reporting-bugs): debug mode, log inspection, and crash reporting -- [Developer documentation](./docs/dev/README.md): system architecture overview, engine design, and contribution guide +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** + +If IRIS crashes, it will automatically save a crash log and show the path on your terminal (`~/.iris/crash.log`). Or you can find the path to the latest crash log by running: +```bash +iris crash-log +``` +Please include this file when reporting a crash. +## Developer documentation + +For system architecture overview, engine design, and contribution guide, please refer to the [Developer documentation](./docs/dev/README.md). + ## License This project is licensed under the [0BSD License](LICENSE) - no strings attached. Meaning you can do whatever you want with it. diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 8497806..0000000 --- a/docs/README.md +++ /dev/null @@ -1,169 +0,0 @@ -# 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 | -| :--------------------------------- | :---------------------- | :------------------------------------------------------------------------ | -| Shift + Tab | Toggle menu | Show or hide the suggestion menu. | -| Esc | Hide menu | Temporarily hide the menu until the next key press. | -| Tab | Accept suggestion | Insert the currently selected suggestion into the prompt. | -| Enter | Execute command | Close the menu and send the current command to the shell. | -| ↑ | Navigate up / history | Move the selection up, or open command history when the prompt is empty. | -| ↓ | Navigate down / history | Move the selection down, or open command history when the prompt is empty.| -| → | Accept ghost text | Accept the faded ghost text suggestion when the menu is open. | -| ← / → | Move cursor | Move the cursor inside the input buffer. Disabled when the prompt is empty| -| Ctrl + R | Switch mode | Toggle between `spec` and `history` mode. | -| Ctrl + A | Beginning of line | Move the cursor to the start of the command line. | -| Ctrl + E | End of line | Move the cursor to the end of the command line. | -| Ctrl + L | Clear screen | Clear the terminal while preserving the input buffer and redrawing the menu. | -| Ctrl + U | Clear command | Remove the entire current command and close the menu. | -| Ctrl + C | Cancel command | Send `SIGINT`, clear the input buffer, and close the menu. | -| Ctrl + W | Delete word | Delete the word immediately before the cursor. | - -> [!NOTE] -> With Ctrl + A, Ctrl + E, Ctrl + W, Ctrl + U, Ctrl + L, and Ctrl + C: 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 -expand-alias = true - -[ui] -style = "modern" # "modern" or "classic" -ghost-text = true -hidden-files = false -max-suggestions = 100 -max-height = 15 -nerd-fonts = true - -[keybindings] -toggle-mode = "ctrl+r" -toggle-menu = "ctrl+space" - -[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**