{"id":15230101,"url":"https://github.com/lucianoayres/nino-cli","last_synced_at":"2025-05-16T08:32:20.667Z","repository":{"id":257321639,"uuid":"857914724","full_name":"lucianoayres/nino-cli","owner":"lucianoayres","description":"Nino is a CLI tool that interacts with local language models via Ollama's serve mode, enabling real-time responses and easy output saving directly from the terminal.","archived":false,"fork":false,"pushed_at":"2024-11-09T09:57:35.000Z","size":14588,"stargazers_count":6,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-11-09T10:30:05.265Z","etag":null,"topics":["cli","golang","llama","ollama","wrapper"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lucianoayres.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-15T23:41:53.000Z","updated_at":"2024-11-09T09:54:30.000Z","dependencies_parsed_at":"2024-09-29T02:43:27.599Z","dependency_job_id":"24d08deb-4df9-4ab5-ad4e-3b04e17b3040","html_url":"https://github.com/lucianoayres/nino-cli","commit_stats":{"total_commits":156,"total_committers":2,"mean_commits":78.0,"dds":0.02564102564102566,"last_synced_commit":"e8601ae2ef9f209b0780c30f7eb38170442fe56e"},"previous_names":["lucianoayres/gollama","lucianoayres/nino-cli"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucianoayres%2Fnino-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucianoayres%2Fnino-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucianoayres%2Fnino-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucianoayres%2Fnino-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lucianoayres","download_url":"https://codeload.github.com/lucianoayres/nino-cli/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225415249,"owners_count":17470859,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","golang","llama","ollama","wrapper"],"created_at":"2024-09-29T02:43:38.326Z","updated_at":"2024-11-19T19:44:43.515Z","avatar_url":"https://github.com/lucianoayres.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🐾 nino CLI\n\n![nino-banner-github](https://github.com/user-attachments/assets/4a2c91af-e212-46f9-9f07-e68ca42d65f7)\n\n## Run LLMs from the Command Line (Always Free)\n\n[About](#about-nino) · [What's New?](#whats-new) · [Features](#features) · [Practical Examples](#practical-examples) · [Ollama Dependency](#ollama-dependency) · [Requirements](#requirements) · [Installation](#installation) · [Usage](#usage) · [Context History](#context-history) · [Using Env Vars](#using-environment-variables) · [Command-line Flags](#command-line-flags) · [Makefile](#makefile-usage) · [GitHub Actions](#github-actions) · [TODOs](#todos) · [Acknowledgements](#acknowledgements) · [License](#license) · [Contribution](#contribution)\n\n## About Nino\n\nNino is a Golang command-line tool that simplifies interaction with local language models served by [Ollama](https://github.com/jmorganca/ollama). It allows you to send prompts to models, receive real-time streaming responses directly in your terminal, and configure models using straightforward command-line arguments.\n\nNino enhances the basic interaction provided by Ollama by displaying full model responses in the terminal and enabling you to save outputs to a file, offering a seamless experience for working with language models.\n\n🎧 [Listen to the Nino CLI Audio Overview](https://notebooklm.google.com/notebook/43c94b77-3ee3-475d-a2a5-478ae3112068/audio)\n\n### What's New?\n\n-   🤗 **Support for Hugging Face GGUF models**: You can now run any GGUF models hosted on Hugging Face using `Nino` with Ollama's infrastructure.\n\n### Example: Running Hugging Face GGUF Models\n\nYou can now run Hugging Face models with `nino` by simply providing the repository URL. First pull the model using Ollama:\n\n```bash\nollama pull hf.co/bartowski/Llama-3.2-1B-Instruct-GGUF\n```\n\nThen use the Hugging Face model with Nino:\n\n```bash\n./nino -m \"hf.co/bartowski/Llama-3.2-1B-Instruct-GGUF\" -p \"Explain me the core concepts of Linear Algebra\"\n```\n\nYou can now explore a wide range of models and tailor the performance for your needs using **nino**.\nFor more advanced customizations, refer to the [Hugging Face and Ollama documentation](https://huggingface.co/docs/hub/ollama).\n\n## Features\n\nEnhance command-line workflows with Nino CLI:\n\n-   💎 Pipe outputs to the AI for real-time analysis.\n-   🤗 Run any Hugging Face GGUF models\n-   💡 Remembers your last interaction for a more conversational experience.\n-   🖼️ Analyze images with multimodal models.\n-   🐶 Pass file contents as prompts and save AI responses to text files.\n-   💻 Seamlessly integrate with command-line tools.\n-   🔒 Data never leaves your computer, ensuring privacy.\n\n💖 Best of all, it's completely free, forever!\n\n## Practical Examples\n\n### Example 1: Analyzing Live Bitcoin Data\n\nUsing the Nino CLI to request the AI to generate an investment strategy based on live bitcoin performance data:\n\n```bash\n./nino \"Analyze Bitcoin's performance data and develop a long-term investment strategy: $(btcq -all-data)\"\n```\n\nThis command uses Bash's native command substitution to pull Bitcoin historical data through [btcq](https://github.com/lucianoayres/btcq-cli), another CLI tool. The analysis is conducted using the Llama 3.2 model.\n\n![nino-cli-screenshot-bitcoin-live-data-analysis](https://github.com/user-attachments/assets/bc96f1f6-d528-4461-b67a-2c6c83104b74)\n\n### Example 2: Advanced Image Analysis\n\nNino CLI supports multimodal models like `llava`, allowing analysis beyond text by processing images:\n\n```bash\n./nino -m \"llava\" -p \"Describe this image in a short sentence\" -image ./assets/images/sample-01.png\n```\n\n![nino-cli-screenshot-advanced-image-analysis](https://github.com/user-attachments/assets/1833cabc-973f-41bb-a716-5be69ba18e7a)\n\nUsers can pass an image file to analyze visual data, recognize patterns, or extract insights from images.\n\n### Example 3: Utilizing Optional Arguments\n\nDiscover how to enhance Nino CLI's functionality with optional arguments.\n\n![nino-cli-screenshot-optional-arguments](https://github.com/user-attachments/assets/f774cc0f-47e5-4579-8efb-9fbb86b2d682)\n\n### Example 4: Enabling Verbose Mode\n\nUse the `-verbose` or `-v` flag to enable detailed logging for debugging and performance validation:\n\n```bash\n./nino -m llama3.2 -p \"Explain the concept of chemical equilibrium.\" -verbose\n```\n\nThis will display detailed logs of the request payload, response status, and operation timings, aiding in troubleshooting and performance assessment.\n\n## Ollama Dependency\n\nNino relies on the [Ollama CLI tool](https://github.com/jmorganca/ollama) to interact with local language models. Ollama must be installed and running on your machine or server for nino to function properly.\n\n### Install Ollama\n\nFollow the instructions on the [Ollama GitHub repository](https://github.com/jmorganca/ollama) to install and set up Ollama. Ensure that Ollama is available in your system’s `$PATH`.\n\n### Pull the Model\n\nTo pull the desired model (e.g., `llama3.2`), execute the following command:\n\n```bash\nollama pull llama3.2\n```\n\n### Start the Ollama Server\n\nOnce Ollama is installed and the chosen model pulled, you need to start the server. This command will run the Ollama server on `http://localhost:11434/api/generate` (default URL and port):\n\n```bash\nollama serve\n```\n\n\u003e **Note:** The `-model` parameter in nino **must match** the model that you run on Ollama. For example, if you start `llama3.2` in Ollama, you must pass `llama3.2` as the `-model` in nino. Otherwise, nino will not be able to communicate with the correct model.\n\nOllama should now be running, and nino can interact with it by sending prompts.\n\n## Requirements\n\n-   Go 1.23+ installed on your system\n-   [Ollama](https://github.com/jmorganca/ollama) installed and running locally or on your server\n-   Ensure that the Ollama server is running via `ollama serve`\n\n## Installation\n\n### Method 1: Download the Binary from GitHub Releases\n\n1. Download the `nino` binary from the [GitHub release page](https://github.com/lucianoayres/nino-cli/releases).\n\n2. Add execution permission:\n\n    ```bash\n    chmod +x ./nino\n    ```\n\n3. Optionally, move the binary to your local binary folder to make it accessible from anywhere:\n\n    ```bash\n    sudo mv ./nino /usr/local/bin/\n    ```\n\n### Method 2: Clone and Build from Source\n\n1. Clone this repository:\n\n    ```bash\n    git clone https://github.com/lucianoayres/nino.git\n    cd nino\n    ```\n\n2. Build the project:\n\n    ```bash\n    make\n    ```\n\n## Usage\n\nAfter building the project and ensuring that the Ollama server is running, you can run nino with the following commands:\n\n### Using Default Model and URL\n\nYou can use nino with just a prompt as the only argument. By default, it will use the `llama3.2` model and connect to the default URL and port for the local Ollama server:\n\n```bash\n./nino \"Who said the quote, 'A person who never made a mistake never tried anything new'?\"\n```\n\nTo prevent unintended line breaks or splitting of arguments in the shell, it's recommended to enclose the prompt in double quotes.\n\n```bash\n./nino \"What's the typical temperature range for a CPU while gaming?\"\n```\n\n### Using `-model` and `-prompt` Arguments\n\n```bash\n./nino -model llama3.2 -prompt \"Which country has the most time zones?\"\n```\n\n### Using `-prompt-file` Argument\n\nYou can pass a text file containing the prompt using the `-prompt-file` flag:\n\n```bash\n./nino -model llama3.2 -prompt-file ./prompts/question.txt\n```\n\nThis will read the contents of `question.txt` and send it as the prompt to the language model.\n\n### Using Multiline Input\n\nWrap the prompt text with \"\"\":\n\n```bash\n./nino \"\"\"Hey!\n\u003e Explain me:\n\u003e - Neural Networks\n\u003e - How LLM Works\n\u003e \"\"\"\n```\n\n### Using Multimodal Models\n\nFor models that support image inputs (like `llava`), you can include images using the `-image` or `-i` flag:\n\n```bash\n./nino -model llava -prompt \"What's in this image?\" -image ./assets/images/sample-01.png\n```\n\nYou can pass multiple images as arguments:\n\n```bash\n./nino -model llava -prompt \"Describe each image in a single word.\" -image ./assets/images/sample-01.png -image ./assets/images/sample-02.png\n```\n\n### Using an Alternative Model\n\nThis example uses all parameters with the `mistral` model. Ensure Ollama is running with `mistral`:\n\n```bash\n./nino -model mistral -prompt \"What is the capital of Australia?\" -url http://localhost:55555/api/generate -output result.txt\n```\n\n### Using JSON Format Responses\n\nTo get a JSON response, use the `-format \"json\"` flag and ensure your prompt explicitly requests a JSON response:\n\n```bash\n./nino -model llama3.2 -prompt \"What are the top 5 most abundant chemical elements on Earth? Respond using JSON.\" -format \"json\"\n```\n\n### Using an Output File\n\nYou can optionally save the model's output to a file while still printing it to the console with the following command:\n\n```bash\n./nino -model llama3.2 -prompt \"What's the Japanese word for 'Thank you'?\" -output answer.txt\n```\n\n### Using Command Substitution\n\nYou can dynamically generate input for nino by using shell command substitution with the $(...) syntax. This allows the output of a shell command to be used as a prompt input:\n\n```bash\n./nino \"Analyze my project directory and suggest maintenance improvements: $(ls -la)\"\n```\n\nAdditionally, you can pass a shell script output as input:\n\n```bash\n./nino \"$(./prompts/generate_commit_message.sh)\"\n```\n\n### Disabling the Loading Animation\n\nUse the `-no-loading` flag to disable the loading animation for a cleaner output:\n\n```bash\n./nino -no-loading \"Explain the concept of chemical equilibrium.\"\n```\n\n### Using Silent Mode\n\nYou can suppress the model output and loading animation and only save the output to a file:\n\n```bash\n./nino -model llama3.2 -prompt \"What color models are available in CSS?\" -silent -output answer.txt\n```\n\n### Enabling Verbose Mode\n\nUse the `-verbose` or `-v` flag to enable detailed logging for debugging and performance validation:\n\n```bash\n./nino -model llama3.2 -prompt \"Explain the concept of chemical equilibrium.\" -verbose\n```\n\nThis will display detailed logs of the request payload, response status, and operation timings, aiding in troubleshooting and performance assessment.\n\n## Context History\n\n### ⚠️ Feature temporariry disabled due to performance issues\n\nNino automatically maintains context between requests for the same model, allowing for more coherent and conversational interactions. To disable context for a particular request, use the `no-context` flag:\n\n```bash\n./nino -model llama3.2 -no-context -prompt \"What's the Linux command to list hidden files in a directory?\"\n```\n\nNote: The context is limited to the last interaction, not the entire conversation history.\n\n### Reseting Context History\n\nIf you wish to reset the context entirely, you can delete the `context.json` file for the specific model. The context files are stored in the following directory:\n\n-   If `XDG_DATA_HOME` is set:\n    -   Context files are located at `$XDG_DATA_HOME/nino/models/MODEL_NAME/context.json`\n-   If `XDG_DATA_HOME` is not set:\n    -   Context files are located at `~/.local/share/nino/models/MODEL_NAME/context.json`\n\nReplace `MODEL_NAME` with the name of the model you're using (e.g., `llama3.2`). Deleting this file will remove the saved context for that model.\n\n## Using Environment Variables\n\nNino allows you to configure default settings through environment variables. These include the model and URL for requests, a system prompt that automatically prefixes all user prompts, and the keep-alive duration for how long the model stays active after a request. Below are details on how to configure each of these options.\n\n### 1. Default Model and URL\n\nYou can set default values for the model and URL used in requests, so you don't need to pass them every time via the command line.\n\n-   **Set a default model**:\n\n    ```bash\n    export NINO_MODEL=\"llama3.2\"\n    ```\n\n-   **Set a default URL**:\n\n    ```bash\n    export NINO_URL=\"http://localhost:11434/api/generate\"\n    ```\n\nIf these environment variables are set, Nino will use them as defaults. You can still override these defaults by passing the `-model` and `-url` flags at runtime.\n\n### 2. Keep-Alive Duration\n\nThe `NINO_KEEP_ALIVE` variable controls how long the model stays active after a request before shutting down. By default, this value is **60 minutes** (`60m`).\n\n-   **Set a custom keep-alive duration**:\n\n    ```bash\n    export NINO_KEEP_ALIVE=\"90m\"\n    ```\n\nIn this example, the model will remain active for 90 minutes after a request.\n\n### 3. System Prompt\n\nYou can set a default system prompt to be automatically added to every user prompt. This is useful for ensuring consistent instructions across all interactions.\n\n-   **Set a default system prompt**:\n\n    ```bash\n    export NINO_SYSTEM_PROMPT=\"Do not use markdown in your answer:\"\n    ```\n\nOnce set, this system prompt cannot be overridden in individual prompts. You must clear it to change it.\n\n### 4. Clearing Environment Variables\n\nTo clear any of the environment variables mentioned above, use:\n\n```bash\nunset NINO_MODEL\nunset NINO_URL\nunset NINO_KEEP_ALIVE\nunset NINO_SYSTEM_PROMPT\n```\n\n## Command-line Flags\n\n-   `-model` or `-m` : The model to use (default: \"llama3.2\").\n    -   Note: This must match the model that is currently running on Ollama.\n-   `-prompt` or `-p` : The prompt to send to the language model (required unless `-prompt-file` is used).\n-   `-prompt-file` or `-pf` : The path to a text file containing the prompt (optional).\n    -   Note: If both `-prompt` and `-prompt-file` are provided, `-prompt` takes precedence.\n-   `-image` or `-i`: Path to local image file to include in the request (optional).\n    -   Note: This flag is compatible only with multimodal models that support image inputs. It can be used multiple times to include multiple images in a single request.\n-   `-url` or `-u` : The host and port where the Ollama server is running (optional).\n    -   Note: The default `http://localhost:11434/api/generate` will be used if no URL is passed.\n-   `-format` or `-f` : Specifies the format of the response from the model.\n    -   Note: Currently, the only supported value is `json`. This flag also requires that your prompt explicitly instructs the model to respond in JSON format.\n-   `-output` or `-o`: Specifies the filename where the model output will be saved (optional).\n-   `-no-loading` or `-nl` : Disable the loading animation (optional).\n-   `-no-stream` or `-ns`: Disables streaming mode, displaying the entire response at once instead of progressively showing it on the screen.\n    -   Note: This may result in a longer wait time before the response is displayed.\n-   `-no-context` or `-nc` : Disable the context from the previous request (optional).\n    -   Note: Previous context won't be used for this response, but the new context will be cached.\n-   `-silent` or `-s` : Suppresses model output and loading animation (optional).\n    -   Note: Requires `-output` flag.\n-   `-verbose` or `-v` : Enables verbose logging for debugging and performance validation (optional).\n    -   Note: When enabled, detailed logs including request payloads and operation timings are displayed to aid in troubleshooting and performance assessment.\n\n## Makefile\n\nThe `Makefile` in the nino project automates several key tasks like installing dependencies, building, testing, and cleaning the project.\n\n## GitHub Actions\n\n[Sample workflows](https://github.com/lucianoayres/nino-cli/tree/main/.github/workflows) using Nino CLI for AI-Generated content integration:\n\n-   [Generate Daily Quote](https://github.com/lucianoayres/nino-cli/actions/workflows/generate-daily-quote.yml): Generate a quote, export it to a file and save it as artifact on GitHub daily at midnight (00:00 UTC).\n\n-   [Save Output to File](https://github.com/lucianoayres/nino-cli/actions/workflows/save-output-to-file.yml): Dispatch the workflow with selected inputs by the user, export the model response to a file, commit it, and then push the changes to the remote repository.\n\n### Triggering the Workflow via REST API\n\nYou can trigger the GitHub Actions workflow with a REST API call using the following example. Be sure to replace placeholders with your actual `GitHub Token`, `Username`, `Repository name`, and `Workflow filename`. Example:\n\n```bash\ncurl -X POST \\\n  -H \"Accept: application/vnd.github+json\" \\\n  -H \"Authorization: Bearer YOUR_GITHUB_TOKEN\" \\\n  https://api.github.com/repos/lucianoayres/nino-cli/actions/workflows/save-output-to-file.yml/dispatches \\\n  -d '{\"ref\":\"main\", \"inputs\": {\"model\": \"llama3.2\", \"prompt\": \"Explain me the BM25 ranking algorithm\", \"output_filename\": \"result.txt\"}}'\n```\n\n#### Steps to Generate a Personal Access Token (PAT) on GitHub\n\nTo trigger workflows via the API, you’ll need a GitHub personal access token. Follow these steps to generate one:\n\n1. Click on your profile photo in GitHub, go to **Settings**, and navigate to **Developer Settings**.\n2. Under **Personal Access Tokens**, click [Generate a new token](https://github.com/settings/tokens?type=beta).\n3. Set the **Expiration** time and select a **Repository** as the scope.\n4. In **Repository Permissions**, ensure `Actions` and `Workflows` have `Read \u0026 Write` access.\n5. Generate and copy the token for use in your API call.\n\n## TODOs\n\n-   [x] Launch v1.0\n-   [x] Create GitHub Actions Recipes\n-   [x] Add Multimodal Model Support\n-   [x] Add JSON format Argument\n-   [x] Add Stream Mode Argument\n-   [ ] Add Context Support\n-   [ ] Fix the Performance Issue with Context Data Loading\n-   [ ] Increase Test Coverage\n-   [ ] Add Custom Modelfiles\n-   [ ] Add Run With Docker Method\n\n### 🦖 Create Custom AI Models with Modelzilla\n\nLooking to build your own AI models? Use [**Modelzilla**](https://github.com/lucianoayres/modelzilla) 🦖 to effortlessly generate customized Modelfiles.\n\n## Acknowledgements\n\nI would like to thank the developers of [Ollama](https://github.com/jmorganca/ollama) for providing the core tools that nino relies on. Additionally, a big thanks to the open-source community for creating the resources that made this project possible.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.\n\n## Contribution\n\nContributions are welcome! Please fork the repository and submit a pull request if you'd like to propose any changes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucianoayres%2Fnino-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flucianoayres%2Fnino-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucianoayres%2Fnino-cli/lists"}