diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/docs/ai/introduction.md | 157 | ||||
| -rw-r--r-- | docs/docs/ai/settings.md | 16 | ||||
| -rw-r--r-- | docs/docs/configuration/config.md | 4 | ||||
| -rw-r--r-- | docs/mkdocs.yml | 3 | ||||
| -rw-r--r-- | docs/pyproject.toml | 5 | ||||
| -rw-r--r-- | docs/uv.lock | 9 |
6 files changed, 191 insertions, 3 deletions
diff --git a/docs/docs/ai/introduction.md b/docs/docs/ai/introduction.md new file mode 100644 index 00000000..39c45eec --- /dev/null +++ b/docs/docs/ai/introduction.md @@ -0,0 +1,157 @@ +# Atuin AI + +Atuin AI is a separate binary that enables command generation and other information lookup via an LLM directly from your terminal. It is completely opt-in, and will not change the behavior of Atuin at all if you choose not to use it. + +Atuin AI requires an account on [Atuin Hub](https://hub.atuin.sh/), and you'll be prompted to login upon first use of the binary. + +## Getting Started + +Atuin AI currently supports zsh, bash, and fish shells. To get started, add the following to your shell's initialization file: + +```bash +eval "$(atuin ai init)" +``` + +Once you've set it up and restarted your shell, you can invoke Atuin AI by pressing question mark (`?`) on an empty terminal line. + +## Settings + +For a list of settings that control the behavior of Atuin AI, see [its dedicated settings documentation](./settings.md). + +## Features + +### Command generation + +Prompt the LLM to create a command, and get one back, no fuss. Press `enter` to run, or `tab` to insert. + +``` +┌Ask questions or generate a command:──────────────────────────┐ +│ │ +│ > Get a list of running docker containers │ +│ │ +├──────────────────────────────────────────────────────────────┤ +│ │ +│ $ docker ps │ +│ │ +└────[Enter]: Run [Tab]: Insert [f]: Follow-up [Esc]: Cancel┘ +``` + +### Follow-up + +You can follow-up with `f` to specify a refinement prompt to update the command that will be inserted. + +``` +┌Ask questions or generate a command:──────────────────────────┐ +│ │ +│ > Get a list of running docker containers │ +│ │ +├──────────────────────────────────────────────────────────────┤ +│ │ +│ $ docker ps │ +│ │ +├──────────────────────────────────────────────────────────────┤ +│ │ +│ > Actually I want to get all docker containers │ +│ │ +├──────────────────────────────────────────────────────────────┤ +│ │ +│ $ docker ps -a │ +│ │ +└────[Enter]: Run [Tab]: Insert [f]: Follow-up [Esc]: Cancel┘ +``` + +You can also follow-up with questions to get responses in natural language. + +``` +┌Ask questions or generate a command:──────────────────────────┐ +│ │ +│ > Get a list of running docker containers │ +│ │ +├──────────────────────────────────────────────────────────────┤ +│ │ +│ $ docker ps │ +│ │ +├──────────────────────────────────────────────────────────────┤ +│ │ +│ > Actually I want to get all docker containers │ +│ │ +├──────────────────────────────────────────────────────────────┤ +│ │ +│ $ docker ps -a │ +│ │ +├──────────────────────────────────────────────────────────────┤ +│ │ +│ > What other useful flags to `docker ps` should I know? │ +│ │ +├──────────────────────────────────────────────────────────────┤ +│ │ +│ Here are some handy `docker ps` flags: │ +│ │ +│ - `-q` — Only show container IDs (great for piping to │ +│ other commands) │ +│ - `-s` — Show container sizes │ +│ - `-n 5` — Show the last 5 created containers │ +│ - `-l` — Show only the latest created container │ +│ - `--no-trunc` — Don't truncate output (shows full IDs and │ +│ commands) │ +│ - `-f` or `--filter` — Filter by condition, e.g.: │ +│ - `-f status=exited` — only exited containers │ +│ - `-f name=myapp` — filter by name │ +│ - `-f ancestor=nginx` — filter by image │ +│ - `--format` — Custom output using Go templates, e.g.: │ +│ `--format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"` │ +│ │ +│ A common combo is `docker ps -aq` to get all container │ +│ IDs, useful for bulk operations like `docker rm $(docker │ +│ ps -aq)`. │ +│ │ +└────[Enter]: Run [Tab]: Insert [f]: Follow-up [Esc]: Cancel┘ +``` + +You can use `enter` or `tab` at any time to run or insert the last suggested command, even if it was suggested in a previous turn. + +### Conversational and search usage + +If you prompt the LLM with a question that doesn't imply you want to generate a command, it can respond in natural language, and use web search if necessary to fetch the data it needs. + +``` +┌Ask questions or generate a command:──────────────────────────┐ +│ │ +│ > What is the latest version of atuin? │ +│ │ +├──────────────────────────────────────────────────────────────┤ +│ │ +│ ✓ Used 2 tools │ +│ │ +│ The latest version of Atuin is **v18.12.0**, available on │ +│ the [GitHub releases │ +│ page](https://github.com/atuinsh/atuin/releases). │ +│ │ +└─────────────────────────────────[f]: Follow-up [Esc]: Cancel┘ +``` + +### Dangerous or low-confidence command detection + +The LLM scores its confidence in the command, as well as how dangerous the command is. This information is shown if a threshold is exceeded, and requires an extra confirmation step before running automatically with `enter`. + +The Atuin Hub server also monitors suggested commands for dangerous patterns the LLM didn't catch, and appends its own assessment at the end of the LLM's own assessment. + +``` +┌Ask questions or generate a command:──────────────────────────┐ +│ │ +│ > Delete all files from $HOME │ +│ │ +├──────────────────────────────────────────────────────────────┤ +│ │ +│ $ rm -rf $HOME/* │ +│ │ +│ ! This will PERMANENTLY delete ALL files and directories in │ +│ your home directory, including documents, downloads, │ +│ configurations, SSH keys, and everything else. This is │ +│ irreversible and will likely break your system. Also note │ +│ this won't delete hidden (dot) files — if you want those │ +│ too, that's even more destructive.; [Server] Recursive │ +│ delete of critical directory │ +│ │ +└────[Enter]: Run [Tab]: Insert [f]: Follow-up [Esc]: Cancel┘ +``` diff --git a/docs/docs/ai/settings.md b/docs/docs/ai/settings.md new file mode 100644 index 00000000..eb868f91 --- /dev/null +++ b/docs/docs/ai/settings.md @@ -0,0 +1,16 @@ +# AI Settings + +All the settings that control the behavior of [Atuin AI](./introduction.md) are specified in an `[ai]` section in your `config.toml`. See [the configuration documentation](../../configuration/config/) for more detailed information about Atuin's configuration system. + +### send_cwd + +Default: `false` + +Whether or not to include your current working directory in the context sent to the LLM. By default, only your OS and current shell are sent. + +**Example config** + +```toml +[ai] +send_cwd = true +``` diff --git a/docs/docs/configuration/config.md b/docs/docs/configuration/config.md index 8f0c6024..2bc1a682 100644 --- a/docs/docs/configuration/config.md +++ b/docs/docs/configuration/config.md @@ -873,3 +873,7 @@ columns = ["exit", "duration", "command"] # Make directory expand instead of command columns = ["duration", "time", { type = "directory", expand = true }, { type = "command", expand = false }] ``` + +## ai + +The settings for Atuin AI are listed in [a separate section](../../ai/settings/). diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 26bf0bee..32df120c 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -89,6 +89,9 @@ nav: - Docker: self-hosting/docker.md - Kubernetes: self-hosting/kubernetes.md - Systemd: self-hosting/systemd.md + - AI: + - Introduction: ai/introduction.md + - Settings: ai/settings.md - Known Issues: known-issues.md - Integrations: integrations.md - FAQ: faq.md diff --git a/docs/pyproject.toml b/docs/pyproject.toml index e3bef982..2d58e8c7 100644 --- a/docs/pyproject.toml +++ b/docs/pyproject.toml @@ -11,5 +11,10 @@ dependencies = [ "mkdocs-redirects>=1.2.2", ] +[tool.uv] +override-dependencies = [ + "click==8.2.1", +] + [dependency-groups] dev = [] diff --git a/docs/uv.lock b/docs/uv.lock index 9575e6ea..e9f9b420 100644 --- a/docs/uv.lock +++ b/docs/uv.lock @@ -2,6 +2,9 @@ version = 1 revision = 3 requires-python = ">=3.11" +[manifest] +overrides = [{ name = "click", specifier = "==8.2.1" }] + [[package]] name = "atuin-cli-docs" version = "1.0.0" @@ -133,14 +136,14 @@ wheels = [ [[package]] name = "click" -version = "8.3.1" +version = "8.2.1" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "colorama", marker = "sys_platform == 'win32'" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/3d/fa/656b739db8587d7b5dfa22e22ed02566950fbfbcdc20311993483657a5c0/click-8.3.1.tar.gz", hash = "sha256:12ff4785d337a1bb490bb7e9c2b1ee5da3112e94a8622f26a6c77f5d2fc6842a", size = 295065, upload-time = "2025-11-15T20:45:42.706Z" } +sdist = { url = "https://files.pythonhosted.org/packages/60/6c/8ca2efa64cf75a977a0d7fac081354553ebe483345c734fb6b6515d96bbc/click-8.2.1.tar.gz", hash = "sha256:27c491cc05d968d271d5a1db13e3b5a184636d9d930f148c50b038f0d0646202", size = 286342, upload-time = "2025-05-20T23:19:49.832Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/98/78/01c019cdb5d6498122777c1a43056ebb3ebfeef2076d9d026bfe15583b2b/click-8.3.1-py3-none-any.whl", hash = "sha256:981153a64e25f12d547d3426c367a4857371575ee7ad18df2a6183ab0545b2a6", size = 108274, upload-time = "2025-11-15T20:45:41.139Z" }, + { url = "https://files.pythonhosted.org/packages/85/32/10bb5764d90a8eee674e9dc6f4db6a0ab47c8c4d0d83c27f7c39ac415a4d/click-8.2.1-py3-none-any.whl", hash = "sha256:61a3265b914e850b85317d0b3109c7f8cd35a670f963866005d6ef1d5175a12b", size = 102215, upload-time = "2025-05-20T23:19:47.796Z" }, ] [[package]] |