{"id":28496673,"url":"https://github.com/9-5/1q","last_synced_at":"2026-03-10T18:09:26.961Z","repository":{"id":297384175,"uuid":"976706134","full_name":"9-5/1q","owner":"9-5","description":"1q is a command-line application that generates the right one-liner based off of natural language queries.","archived":false,"fork":false,"pushed_at":"2025-05-20T15:05:31.000Z","size":243,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-28T21:04:25.111Z","etag":null,"topics":["ai","cli","command-generator","cross-platform","developer-tools","gemini-ai","generative-ai","nlp","productivity","python","textual","tui"],"latest_commit_sha":null,"homepage":"https://oj.hn/1q","language":"Python","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/9-5.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,"zenodo":null}},"created_at":"2025-05-02T15:42:31.000Z","updated_at":"2025-05-20T15:05:37.000Z","dependencies_parsed_at":"2025-06-05T08:10:30.137Z","dependency_job_id":"98630a5c-0721-4911-94a2-357fbf4170c5","html_url":"https://github.com/9-5/1q","commit_stats":null,"previous_names":["9-5/1q"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/9-5/1q","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/9-5%2F1q","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/9-5%2F1q/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/9-5%2F1q/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/9-5%2F1q/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/9-5","download_url":"https://codeload.github.com/9-5/1q/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/9-5%2F1q/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30346612,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T15:55:29.454Z","status":"ssl_error","status_checked_at":"2026-03-10T15:54:58.440Z","response_time":106,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["ai","cli","command-generator","cross-platform","developer-tools","gemini-ai","generative-ai","nlp","productivity","python","textual","tui"],"created_at":"2025-06-08T12:31:03.601Z","updated_at":"2026-03-10T18:09:26.946Z","avatar_url":"https://github.com/9-5.png","language":"Python","readme":"# 1Q - The right one-liner is just one query away.\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![PyPI version](https://badge.fury.io/py/oneq.svg)](https://badge.fury.io/py/oneq)\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"assets/icons/1Q.svg\" alt=\"1Q Icon\" height=25% width=25%\u003e\n\u003c/p\u003e\n\n`1q`, short for 1Query, is a cross-platform command-line utility that lets you use natural language to generate shell commands, command chains, and code snippets right in your terminal. Get the command you need instantly, review it, modify it, and even execute it directly!\n\nhttps://github.com/user-attachments/assets/b3bb7b79-a9f3-4d23-96f6-788cecd5dfa4\n\n## Table of Contents\n\n*   [Features](#features)\n*   [Installation](#installation)\n*   [Getting Started](#getting-started)\n*   [Configuration](#configuration)\n    *   [API Key](#api-key)\n    *   [Output Style](#output-style)\n*   [Interactive Features \u0026 Usage](#️-interactive-features--usage)\n    *   [Inline Mode (stderr prompt)](#inline-mode-stderr-prompt)\n    *   [TUI Mode (Textual Interface)](#tui-mode-textual-interface)\n*   [Command-Line Options](#command-line-options)\n*   [Contributing](#contributing)\n*   [License](#license)\n\n## Features\n\n*   **Natural Language Input:** Simply type what you want to do (e.g., `1q find all files larger than 50MB in my home dir`).\n*   **Gemini Powered:** Leverages Google's powerful Gemini model (specifically `gemini-2.0-flash`) for accurate and relevant command/code generation.\n*   **Context-Aware Refinement:** Didn't get the perfect command on the first try? Refine your request in a conversation! `1q` remembers the context.\n*   **Intelligent Output:**\n    *   **Inline Mode:** For simple queries, get just the raw command printed directly to standard output, perfect for piping (`|`) or immediate use.\n    *   **TUI Mode:** For more complex commands, or when explanations/install steps are needed, `1q` automatically launches a Textual User Interface (TUI) for a clear, structured view.\n    *   **Configurable Default:** Choose whether you prefer `inline`, `tui`, or `auto` (default) detection as your standard output method.\n*   **Interactive Workflow:**\n    *   **Execute:** Run the generated command directly from the TUI or the inline prompt (`x` key or `execute` action).\n    *   **Modify:** Tweak the command in your editor (`m` key or `modify` action) before execution.\n    *   **Copy:** Easily copy the generated command to your clipboard (`c` key or `copy` action).\n*   **Structured Responses:** The AI provides not just the `COMMAND:`, but often includes `EXPLANATION:` and `INSTALL:` steps when necessary, clearly presented in the TUI.\n*   **Configuration:**\n    *   Securely store your Gemini API key via environment variable (`GEMINI_API_KEY`) or a configuration file.\n    *   Set your preferred default output style (`--set-default-output`).\n*   **Cross-Platform:** Built with Python and Textual, runs on Linux, macOS, and Windows.\n\n## Installation\n\n`1Q` requires **Python 3.8 or higher**.\n\nYou can install `1Q` directly from PyPI using pip:\n\n```bash\npip install oneq\n```\n\nIt's often recommended to install Python CLI tools in isolated environments using tools like `pipx`:\n\n```bash\npipx install oneq\n```\n\n*(Optional)* For the inline `copy` action to work reliably, ensure you have a clipboard utility installed (`pyperclip` is used internally):\n*   **Linux:** `sudo apt-get install xclip` or `sudo apt-get install xsel` (for X11), or `wl-copy` (for Wayland).\n*   **macOS:** `pbcopy` is usually built-in.\n*   **Windows:** Should work out of the box.\n\n## Getting Started\n\n1.  **Configure API Key:**\n    `1Q` needs a Google Gemini API key. Get one from [Google AI Studio](https://aistudio.google.com/app/apikey). You can configure it in one of two ways:\n\n    *   **(Recommended) Environment Variable:** Set the `GEMINI_API_KEY` environment variable:\n        ```bash\n        export GEMINI_API_KEY='YOUR_API_KEY_HERE'\n        # Add this line to your shell profile (~/.bashrc, ~/.zshrc, etc.) for persistence\n        ```\n\n    *   **Configuration File:** Run `1q` once without arguments and without the environment variable set. It will launch an interactive setup TUI to securely save your key to a configuration file.\n        ```bash\n        1q\n        ```\n        (Follow the prompts to enter your key and choose a default output style).\n\n2.  **Make your First Query:**\n    Ask `1q` to generate a command:\n    ```bash\n    1q list all python files modified in the last 2 days\n    ```\n\n3.  **Interact with the Result:**\n    *   If the command is simple, it might print directly to your console (inline mode).\n    *   If it's complex or includes details, the TUI will launch.\n\n    *   **Inline Mode:** You'll be prompted for the next action (execute, modify, refine, copy, quit).\n    *   **TUI Mode:** Use keyboard shortcuts (see below) to interact.\n\n    Example TUI:\n    ```\n    ┌────────────────────────── 1Q Response ───────────────────────────┐\n    │ ### COMMAND                                                      │\n    │ find . -name \"*.py\" -type f -mtime -2                            │\n    │                                                                  │\n    │ ### EXPLANATION                                                  │\n    │                                                                  │\n    │ - `find .`: Search in the current directory (`.`) and subdirs.   │\n    │ - `-name \"*.py\"`: Find files matching the pattern '*.py'.        │\n    │ - `-type f`: Only consider regular files.                        │\n    │ - `-mtime -2`: Find files modified within the last 2 days (less  │\n    │   than 2*24 hours ago).                                          │\n    └──────────────────────────────────────────────────────────────────┘\n    [c] Copy Cmd [x] Execute [m] Modify [r] Refine [q] Quit\n    ```\n\n4.  **Refine (If Needed):**\n    If the first command wasn't quite right, choose the `refine` action (or press `r` in the TUI) and enter a follow-up request, like:\n    ```\n    Refine your request (or press Enter to quit): also exclude the venv directory\n    ```\n    `1q` will use the previous conversation context to generate an updated command.\n\n---\n\n## Configuration\n\n### API Key\n\nAs mentioned in *Getting Started*, the API key is loaded in this order:\n\n1.  `GEMINI_API_KEY` environment variable.\n2.  `config.ini` file located in the user's configuration directory.\n\nYou can find the configuration file path using:\n```bash\n1q --show-config-path\n```\n\n### Output Style\n\nControl how `1q` presents results:\n\n*   `auto` (Default): Shows TUI for complex results (with explanation/install) or if markers are present; otherwise, shows inline command.\n*   `tui`: Always uses the Textual User Interface.\n*   `inline`: Always attempts to print the raw command to stdout and details/prompts to stderr.\n\n**Set the default style permanently:**\n```bash\n# Set TUI as the default\n1q --set-default-output=tui\n\n# Set inline as the default\n1q --set-default-output=inline\n\n# Set auto as the default\n1q --set-default-output=auto\n```\nThis modifies the `output_style` key under the `[Settings]` section in your `config.ini`.\n\n**Override the default for a single run:**\n```bash\n# Force TUI for this query\n1q find unused docker images -o tui\n\n# Force inline output for this query\n1q make a directory called temp and cd into it -o inline\n```\n\n## ⌨️ Interactive Features \u0026 Usage\n\n### Inline Mode (stderr prompt)\n\nWhen `1q` runs in `inline` mode (or `auto` for simple commands):\n\n1.  The generated command is printed to **stdout**.\n2.  Explanation/Install steps (if any) are printed to **stderr**.\n3.  A prompt appears on **stderr** asking for your next action:\n    *   `execute`: Run the command immediately.\n    *   `modify`: Open the command in an interactive prompt for editing.\n    *   `refine`: Provide a follow-up natural language instruction.\n    *   `copy`: (If `pyperclip` is available) Copy the command to the clipboard.\n    *   `quit`: Exit `1q`.\n\n### TUI Mode (Textual Interface)\n\nWhen `1q` runs in `tui` mode (or `auto` for complex commands):\n\n*   The response is displayed visually, separating Command, Installation, and Explanation.\n*   Use these keybindings:\n    *   `c`: **Copy** the command to the clipboard.\n    *   `x`: **Execute** the command (exits TUI first).\n    *   `m`: **Modify** the command (exits TUI first, then opens inline editor).\n    *   `r`: **Refine** the query (exits TUI first, then prompts for refinement).\n    *   `q` / `Ctrl+C`: **Quit** the TUI and `1q`.\n\n## Command-Line Options\n\n```bash\nusage: 1q [-h] [-o {auto,tui,inline}] [--show-config-path] [--clear-config]\n          [--set-default-output STYLE] [-v]\n          [query ...]\n\n1Q: Your instant command-line and code snippet generator.\n\npositional arguments:\n  query                 Your natural language query. If omitted, runs setup (if needed) or shows help.\n\noptions:\n  -h, --help            show this help message and exit\n  -o {auto,tui,inline}, --output {auto,tui,inline}\n                        Specify output style for this run: 'auto', 'tui', 'inline'. Overrides config default.\n  -v, --version         show program's version number and exit\n\nConfiguration and Info Actions:\n  --show-config-path    Print the path to the configuration file and exit.\n  --clear-config        Remove the configuration file (prompts for confirmation).\n  --set-default-output STYLE\n                        Set and save the default output style in the config file (auto, tui, inline).\n\nExample: 1q list files in Documents ending with .pdf\n```\n\n## Contributing\n\nContributions are welcome! If you find a bug or have a feature request, please open an issue on the GitHub repository (link to be added).\n\n---\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details (or check `pyproject.toml`).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F9-5%2F1q","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F9-5%2F1q","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F9-5%2F1q/lists"}