Metadata-Version: 2.4
Name: omga-cli
Version: 2.1.0
Summary: OMGA — a polished, keyboard-first AI coding assistant for your terminal.
Author-email: Pouria Hosseini <PouriaHosseini@outlook.com>
License: MIT
Project-URL: Homepage, https://github.com/isPoori/omga-cli
Project-URL: Repository, https://github.com/isPoori/omga-cli
Keywords: cli,ai,coding-assistant,developer-tools,openrouter,omnirouter,9router,terminal,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Terminals
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1.0
Requires-Dist: rich>=13.7.0
Requires-Dist: requests>=2.31.0
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov>=4.0; extra == "test"
Requires-Dist: responses>=0.25.0; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Dynamic: license-file

<h1 align="center">OMGA CLI</h1>
<p align="center">
  <strong>A polished, keyboard-first AI coding assistant for your terminal.</strong><br/>
  Fast · Minimal · Beautiful · Developer-focused
</p>

<p align="center">
  <a href="https://pypi.org/project/omga-cli/"><img alt="PyPI" src="https://img.shields.io/pypi/v/omga-cli"></a>
  <a href="https://www.python.org/downloads/"><img alt="Python" src="https://img.shields.io/badge/python-3.10%2B-blue"></a>
  <a href="https://github.com/isPoori/omga-cli/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/isPoori/omga-cli"></a>
</p>

---

## What is OMGA?

**OMGA** is an AI coding assistant that lives inside your terminal. It reads,
writes and searches your codebase, runs commands, inspects Git state, explains
code, fixes bugs and implements features — all with a clean, modern, fully
keyboard-driven interface.

```
◆ OMGA
```

## Highlights

| | |
|---|---|
| 🧠 **Agentic coding** | Reads, writes, searches and runs in your project |
| 🔌 **Multi-provider** | OpenRouter, OmniRouter and 9Router behind one interface |
| 🎨 **Themes** | Dark, Light, Dracula, Nord, Minimal — a central token system |
| 🟥🟩 **Real diffs** | Added lines in green, removed in red, before applying |
| ⌨️ **Keyboard-first** | Arrow keys, Enter, Escape, search filtering, Ctrl+C |
| 🪄 **First-run wizard** | Provider → API key → model → theme in one guided flow |
| 🔒 **Secure keys** | Keys are never logged, printed or committed (chmod 600) |
| 🩺 **Doctor** | One command to diagnose config, keys, network, terminal |
| ⚡ **Fast** | Lazy module loading, streaming, no startup bloat |

---

## Installation

Requires **Python 3.10+**.

```bash
pip install omga-cli
```

That's it. The `omga` command is now available.

---

## First launch

Run:

```bash
omga
```

On the very first run OMGA detects that no configuration exists and launches an
interactive setup wizard automatically:

```text
Welcome to OMGA.

Let's configure your AI provider.
```

The wizard walks you through, in order:

1. **Provider** — choose OpenRouter, OmniRouter or 9Router
2. **API key** — enter your key (input is hidden, never echoed or logged)
3. **Model** — pick from the live model list (with search), or type one manually
4. **Theme** — choose the terminal theme you prefer

When the wizard finishes you drop straight into the coding assistant. No config
files to edit by hand.

---

## Usage

### Interactive coding assistant

```bash
omga
```

You are greeted with a session header showing the working directory, model and
provider, then a prompt:

```text
What would you like me to do?
❯ write a fastapi endpoint for user auth
```

OMGA will inspect your project, make changes, and show you a red/green diff
**before** applying it — you approve each significant change.

Type `exit` / `quit` or press **Ctrl+C** twice to leave.

### Commands

```text
omga                 Launch the interactive coding assistant
omga init            Run (or re-run) the setup wizard
omga config          Show current configuration
omga config provider Change the AI provider
omga config model    Change the default model
omga config key      Update the API key for the active provider
omga config theme    Change the theme
omga config reset    Reset configuration to defaults
omga doctor          Run diagnostics
omga version         Show version
omga help            Show help
```

---

## Configuration

Configuration lives under an OS-appropriate directory:

| Path | Content |
|---|---|
| `~/.config/omga/config.json` | user configuration (no secrets) |
| `~/.config/omga/secrets.json` | API keys only, mode-restricted (`chmod 600`) |
| `~/.config/omga/history.txt` | shell history |
| `~/.config/omga/logs/omga.log` | diagnostic logs (secrets redacted) |

API keys are stored **separately** from configuration and never appear in
`config.json`. Precedence for any value:

```text
CLI arguments  →  environment variables  →  user config  →  defaults
```

### Environment variables

| Variable | Purpose |
|---|---|
| `OMGA_API_KEY` | Generic API key (any provider) |
| `OMGA_OPENROUTER_API_KEY` | API key for the OpenRouter provider |
| `OMGA_OMNIROUTER_API_KEY` | API key for the OmniRouter provider |
| `OMGA_9ROUTER_API_KEY` | API key for the 9Router provider |
| `OMGA_<PROVIDER>_BASE_URL` | Override a provider's base URL |
| `OMGA_THEME` | Force a theme (e.g. `light`) |
| `OMGA_DEBUG=1` | Enable debug logging |

---

## Providers

OMGA routes to multiple provider services through a single `AIProvider`
interface. Each provider implements the same contract:

```python
interface AIProvider:
    id, name, base_url
    validate_credentials() -> bool
    list_models() -> list[Model]
    chat(messages, **kwargs) -> AsyncIterable[ChatEvent]
```

Providers are selected during setup (`omga init`) or with
`omga config provider`.

> **Note on OmniRouter and 9Router:** these are OpenAI-compatible AI gateways.
> Their exact public endpoints were not reachable from the environment used to
> build OMGA, so their default base URLs are best-effort placeholders. If yours
> differs, set the corresponding `OMGA_OMNIROUTER_BASE_URL` /
> `OMGA_9ROUTER_BASE_URL` environment variable.

---

## Themes

Themes are a **central token system** — the UI never hard-codes a colour, it
references semantic tokens (`added`, `removed`, `error`, `success`, `muted`,
...).

Built-in themes: **Dark**, **Light**, **Dracula**, **Nord**, **Minimal**.

Change anytime with `omga config theme` or `omga init`.

---

## Security

- API keys are stored in a mode-restricted file (`chmod 600`) and are never
  printed, logged, echoed, or committed.
- The logger redacts secret-looking values defensively.
- Shell commands the agent proposes go through a safety layer: `rm -rf /`
  and other filesystem-rooting commands are hard-blocked; `git reset --hard`,
  `git clean`, `rm`, `mv`, destructive shell commands require explicit approval.
- File edits are shown as a diff and require approval before being applied.
- Path-traversal outside the project root is rejected.
- OMGA never commits to Git automatically.

### A note about the old codebase

An earlier version of this project accidentally contained a hard-coded
OpenRouter API key in `core/config.py`. It was purged in the rewrite. **If you
ever used that key, treat it as compromised and rotate it.** Anyone who clones
the old history can read it.

---

## Development

```bash
git clone https://github.com/isPoori/omga-cli
cd omga-cli
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,test]"

omga --version            # run the CLI from source
pytest                    # run the test suite
python -m build           # build sdist + wheel
```

### Project layout

```text
omga/
├── cli/            command wiring, entry point
├── config/         configuration store + secrets
├── providers/      AIProvider protocol + OpenRouter/OmniRouter/9Router
├── tools/          filesystem, search, shell, git, safety layer
├── agent/          the coding agent loop + hooks + REPL interface
├── ui/             theme tokens, menus, rendering, console facade
├── project.py      project discovery
├── wizard.py       first-run setup wizard
├── doctor.py       `omga doctor` diagnostics
└── paths.py        OS-appropriate state locations
```

## Testing

```bash
pytest
```

Coverage includes configuration precedence & secret isolation, theme token
completeness, command-safety rules, diff rendering, provider streaming
(mocked), the agent loop (fake provider), path-traversal rejection, and CLI
wiring. **No test requires a real API key** — external calls are mocked.

## Contributing

Contributions, bug reports and feature requests are welcome. Please open an
issue or pull request on the [repository](https://github.com/isPoori/omga-cli).
Follow the existing structure and add tests for new behaviour.

## License

[MIT](LICENSE) © Pouria Hosseini
