# oterm
the text-based terminal client for [Ollama](https://github.com/jmorganca/ollama).
## Features
* intuitive and simple terminal UI, no need to run servers, frontends, just type `oterm` in your terminal.
* multiple persistent chat sessions, stored together with the context embeddings and system prompt customizations in sqlite.
* can use any of the models you have pulled in Ollama, or your own custom models.
* allows for easy customization of the model's system prompt and parameters.
## Installation
Using `brew` for MacOS:
```bash
brew tap ggozad/formulas
brew install ggozad/formulas/oterm
```
Using `pip`:
```bash
pip install oterm
```
## Using
In order to use `oterm` you will need to have the Ollama server running. By default it expects to find the Ollama API running on `http://0.0.0.0:11434`. If you are running Ollama inside docker or on a different host/port, use the `OLLAMA_HOST` environment variable to customize the host/port. Alternatively you can use `OLLAMA_URL` to specify the full http(s) url. Setting `OTERM_VERIFY_SSL` to `False` will disable SSL verification.
```bash
OLLAMA_URL=http://host:port/api
```
The following keyboard shortcuts are supported:
* <kbd>^ Ctrl</kbd>+<kbd>N</kbd> - create a new chat session
* <kbd>^ Ctrl</kbd>+<kbd>E</kbd> - edit the chat session (change template, system prompt or format)
* <kbd>^ Ctrl</kbd>+<kbd>R</kbd> - rename the current chat session
* <kbd>^ Ctrl</kbd>+<kbd>S</kbd> - export the current chat session as markdown
* <kbd>^ Ctrl</kbd>+<kbd>X</kbd> - delete the current chat session
* <kbd>^ Ctrl</kbd>+<kbd>T</kbd> - toggle between dark/light theme
* <kbd>^ Ctrl</kbd>+<kbd>Q</kbd> - quit
* <kbd>^ Ctrl</kbd>+<kbd>L</kbd> - switch to multiline input mode
* <kbd>^ Ctrl</kbd>+<kbd>P</kbd> - select an image to include with the next message
* <kbd>↑</kbd> - navigate through history of previous prompts
While Ollama is inferring the next message, you can press <kbd>Esc</kbd> to cancel the inference.
Note that some of the shortcuts may not work in a certain context, for example pressing <kbd>↑</kbd> while the prompt is in multi-line mode.
### Copy / Paste
It is difficult to properly support copy/paste in terminal applications. You can copy blocks to your clipboard as such:
* clicking a message will copy it to the clipboard.
* clicking a code block will only copy the code block to the clipboard.
For most terminals there exists a key modifier you can use to click and drag to manually select text. For example:
* `iTerm` <kbd>Option</kbd> key.
* `Gnome Terminal` <kbd>Shift</kbd> key.
* `Windows Terminal` <kbd>Shift</kbd> key.
### Customizing models
When creating a new chat, you may not only select the model, but also customize the `template` as well as the `system` instruction to pass to the model. Checking the `JSON output` checkbox will cause the model reply in JSON format. Please note that `oterm` will not (yet) pull models for you, use `ollama` to do that. All the models you have pulled or created will be available to `oterm`.
You can also "edit" the chat to change the template, system prompt or format. Note, that the model cannot be changed once the chat has started. In addition whatever "context" the chat had (an embedding of the previous messages) will be kept.
### Chat session storage
All your chat sessions are stored locally in a sqlite database. You can customize the directory where the database is stored by setting the `OTERM_DATA_DIR` environment variable.
You can find the location of the database by running `oterm --db`.
### Screenshots
## License
This project is licensed under the [MIT License](LICENSE).
Raw data
{
"_id": null,
"home_page": "https://github.com/ggozad/oterm",
"name": "oterm",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Yiorgis Gozadinos",
"author_email": "ggozadinos@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/7d/b6/a16eb00b7e078dbdfb989ddf41b59a2ec6e4242e61f0f892939b37f2a57e/oterm-0.2.7.tar.gz",
"platform": null,
"description": "# oterm\n\nthe text-based terminal client for [Ollama](https://github.com/jmorganca/ollama).\n\n## Features\n\n* intuitive and simple terminal UI, no need to run servers, frontends, just type `oterm` in your terminal.\n* multiple persistent chat sessions, stored together with the context embeddings and system prompt customizations in sqlite.\n* can use any of the models you have pulled in Ollama, or your own custom models.\n* allows for easy customization of the model's system prompt and parameters.\n\n## Installation\n\nUsing `brew` for MacOS:\n\n```bash\nbrew tap ggozad/formulas\nbrew install ggozad/formulas/oterm\n```\n\nUsing `pip`:\n\n```bash\npip install oterm\n```\n\n## Using\n\nIn order to use `oterm` you will need to have the Ollama server running. By default it expects to find the Ollama API running on `http://0.0.0.0:11434`. If you are running Ollama inside docker or on a different host/port, use the `OLLAMA_HOST` environment variable to customize the host/port. Alternatively you can use `OLLAMA_URL` to specify the full http(s) url. Setting `OTERM_VERIFY_SSL` to `False` will disable SSL verification.\n\n```bash\nOLLAMA_URL=http://host:port/api\n```\n\nThe following keyboard shortcuts are supported:\n\n* <kbd>^ Ctrl</kbd>+<kbd>N</kbd> - create a new chat session\n* <kbd>^ Ctrl</kbd>+<kbd>E</kbd> - edit the chat session (change template, system prompt or format)\n* <kbd>^ Ctrl</kbd>+<kbd>R</kbd> - rename the current chat session\n* <kbd>^ Ctrl</kbd>+<kbd>S</kbd> - export the current chat session as markdown\n* <kbd>^ Ctrl</kbd>+<kbd>X</kbd> - delete the current chat session\n* <kbd>^ Ctrl</kbd>+<kbd>T</kbd> - toggle between dark/light theme\n* <kbd>^ Ctrl</kbd>+<kbd>Q</kbd> - quit\n\n* <kbd>^ Ctrl</kbd>+<kbd>L</kbd> - switch to multiline input mode\n* <kbd>^ Ctrl</kbd>+<kbd>P</kbd> - select an image to include with the next message\n* <kbd>\u2191</kbd> - navigate through history of previous prompts\n\nWhile Ollama is inferring the next message, you can press <kbd>Esc</kbd> to cancel the inference.\n\nNote that some of the shortcuts may not work in a certain context, for example pressing <kbd>\u2191</kbd> while the prompt is in multi-line mode.\n\n### Copy / Paste\n\nIt is difficult to properly support copy/paste in terminal applications. You can copy blocks to your clipboard as such:\n\n* clicking a message will copy it to the clipboard.\n* clicking a code block will only copy the code block to the clipboard.\n\nFor most terminals there exists a key modifier you can use to click and drag to manually select text. For example:\n* `iTerm` <kbd>Option</kbd> key.\n* `Gnome Terminal` <kbd>Shift</kbd> key.\n* `Windows Terminal` <kbd>Shift</kbd> key.\n\n\n### Customizing models\n\nWhen creating a new chat, you may not only select the model, but also customize the `template` as well as the `system` instruction to pass to the model. Checking the `JSON output` checkbox will cause the model reply in JSON format. Please note that `oterm` will not (yet) pull models for you, use `ollama` to do that. All the models you have pulled or created will be available to `oterm`.\n\nYou can also \"edit\" the chat to change the template, system prompt or format. Note, that the model cannot be changed once the chat has started. In addition whatever \"context\" the chat had (an embedding of the previous messages) will be kept.\n\n### Chat session storage\n\nAll your chat sessions are stored locally in a sqlite database. You can customize the directory where the database is stored by setting the `OTERM_DATA_DIR` environment variable.\n\nYou can find the location of the database by running `oterm --db`.\n\n### Screenshots\n\n\n\n\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A text-based terminal client for Ollama.",
"version": "0.2.7",
"project_urls": {
"Bug Tracker": "https://github.com/ggozad/oterm/issues",
"Homepage": "https://github.com/ggozad/oterm",
"Repository": "https://github.com/ggozad/oterm"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1b07d4b7a87a76a7ddcd8546d6e1adc4e16d3f63cbe5dfeefd3a92b86caca65c",
"md5": "a07bed6b014c4f427b8bf2a267aa1155",
"sha256": "efbe05239510b86717737b5db7b4310cdec6df46d69cf96c42de56f12292cbdc"
},
"downloads": -1,
"filename": "oterm-0.2.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a07bed6b014c4f427b8bf2a267aa1155",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 26505,
"upload_time": "2024-04-22T06:47:21",
"upload_time_iso_8601": "2024-04-22T06:47:21.011757Z",
"url": "https://files.pythonhosted.org/packages/1b/07/d4b7a87a76a7ddcd8546d6e1adc4e16d3f63cbe5dfeefd3a92b86caca65c/oterm-0.2.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7db6a16eb00b7e078dbdfb989ddf41b59a2ec6e4242e61f0f892939b37f2a57e",
"md5": "e5fdb63eb3e4231a6397c23d8009c2b9",
"sha256": "0540bbbaa6072238a962db12eef3c49b4ef49007d29e62cf1e2b50f8158bf283"
},
"downloads": -1,
"filename": "oterm-0.2.7.tar.gz",
"has_sig": false,
"md5_digest": "e5fdb63eb3e4231a6397c23d8009c2b9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 19566,
"upload_time": "2024-04-22T06:47:23",
"upload_time_iso_8601": "2024-04-22T06:47:23.111549Z",
"url": "https://files.pythonhosted.org/packages/7d/b6/a16eb00b7e078dbdfb989ddf41b59a2ec6e4242e61f0f892939b37f2a57e/oterm-0.2.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-22 06:47:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ggozad",
"github_project": "oterm",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "oterm"
}
JSON
