Metadata-Version: 2.4
Name: ask2cmd
Version: 0.1.0
Summary: Turn natural language into terminal commands.
Author: askcmd contributors
License: MIT
Project-URL: Homepage, https://github.com/dovzilla/askcmd
Project-URL: Repository, https://github.com/dovzilla/askcmd
Keywords: cli,ai,terminal,openai,natural-language
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: openai>=1.0.0
Dynamic: license-file

<p align="center">
  <h1 align="center">askcmd</h1>
  <p align="center"><strong>Stop Googling. Start asking.</strong></p>
  <p align="center">Turn natural language into terminal commands — right from your shell.</p>
</p>

<p align="center">
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.8+-blue.svg" alt="Python 3.8+"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License"></a>
  <a href="https://github.com/dovzilla/askcmd/stargazers"><img src="https://img.shields.io/github/stars/dovzilla/askcmd?style=social" alt="GitHub Stars"></a>
  <a href="https://github.com/dovzilla/askcmd/pulls"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"></a>
</p>

---

## Demo

```
$ ask "list all docker containers"
> docker ps -a

$ ask "kill process on port 3000"
> lsof -ti:3000 | xargs kill -9

$ ask "find large files in this folder"
> find . -type f -size +100M
```

<p align="center">
  <img src="demo.gif" alt="askcmd demo" width="600">
</p>

---

## Why This Exists

You're a developer. You live in the terminal.

And yet — every single day — you open a browser to Google things like:

> *"how to find files larger than 100MB linux"*
> *"tar compress folder command"*
> *"kill process on port 3000 mac"*

You know the command *exists*. You just can't remember the exact flags.

**askcmd** fixes that. One tool. One command. No leaving the terminal.

```bash
ask "undo last git commit but keep changes"
```

That's it.

---

## Install

```bash
pip install ask2cmd
```

Then run the setup wizard to pick your provider and enter your API key:

```bash
ask setup
```

Choose from **OpenAI**, **DeepSeek**, or any OpenAI-compatible API:

```
选择你的 AI 服务商:

  1) OpenAI
  2) DeepSeek
  3) Custom (OpenAI-compatible)
```

Done. You're ready.

---

## Examples

This is where it gets fun.

#### Everyday

```bash
ask "show disk usage sorted by size"
ask "count lines of code in this project"
ask "show my public IP"
ask "what's using port 8080"
```

#### Git

```bash
ask "undo last commit but keep changes"
ask "squash last 3 commits"
ask "show commits from last week by me"
ask "delete all merged branches"
```

#### Docker

```bash
ask "stop all running containers"
ask "remove all dangling images"
ask "show logs for container nginx"
ask "list all volumes not used by any container"
```

#### Files & Search

```bash
ask "find all TODO comments in python files"
ask "find files modified in the last 24 hours"
ask "replace foo with bar in all js files"
ask "find duplicate files in this folder"
```

#### System

```bash
ask "kill process on port 3000"
ask "show top 10 processes by memory"
ask "how much RAM is free"
ask "list all open network connections"
```

#### Fun

```bash
ask "generate a random password 32 chars"
ask "download this youtube video as mp3"  # you rebel
ask "what's the weather in Tokyo from the terminal"
```

Every command is shown to you **before** it runs. You stay in control.

---

## Features

| Feature | Description |
|---------|-------------|
| **Natural language** | Just describe what you want |
| **OS-aware** | Detects macOS / Linux / Windows and adapts commands |
| **Multi-provider** | OpenAI, DeepSeek, or any compatible API |
| **Safe by default** | Always asks for confirmation before running |
| `--explain` | Explains what the command does |
| `--dry-run` | Shows the command without executing |
| `--yes` | Skips confirmation (for the brave) |

---

## Safety

**askcmd never runs anything without your permission.**

Default flow:

```
$ ask "delete all node_modules recursively"

╭──────────────────────────────────────────╮
│ find . -name node_modules -type d        │
│   -prune -exec rm -rf {} +               │
╰──────────────────────────────────────────╯

Run this command? [y/N]:
```

- **Default is N.** You must explicitly approve.
- Use `--dry-run` to preview without any execution.
- Use `--explain` to understand the command before running.
- No telemetry. No data collection. Your queries go to *your* API provider and nowhere else.

You are always in control.

---

## How It Works

```
  You                askcmd             LLM API           Terminal
   │                   │                  │                  │
   │  "kill port 3000" │                  │                  │
   │──────────────────>│                  │                  │
   │                   │  prompt + OS ctx │                  │
   │                   │─────────────────>│                  │
   │                   │  shell command   │                  │
   │                   │<─────────────────│                  │
   │  show command     │                  │                  │
   │<──────────────────│                  │                  │
   │  confirm (y/N)    │                  │                  │
   │──────────────────>│                  │                  │
   │                   │          execute │                  │
   │                   │─────────────────────────────────────>
   │                   │                  │          output  │
   │<─────────────────────────────────────────────────────────
```

1. You describe what you want in plain English
2. `askcmd` builds a prompt with your OS and shell context
3. The LLM returns a single shell command (no markdown, no fluff)
4. You review, confirm, and it runs — or you walk away

No agents. No chains. No frameworks. Just one clean API call.

---

## Roadmap

- [ ] Command history — recall and reuse past generations
- [ ] Shell aliases — auto-create aliases for commands you use often
- [ ] Offline mode — local models via Ollama
- [ ] Plugins — community-contributed prompt packs
- [ ] Clipboard mode — copy command instead of running
- [ ] Multi-command — generate pipelines and scripts
- [ ] i18n — prompts in any language

Want to build one of these? PRs are open.

---

## Contributing

```bash
git clone https://github.com/dovzilla/askcmd.git
cd askcmd
pip install -e .
ask setup
```

That's the whole dev setup. Hack away.

---

## License

MIT — do whatever you want with it.

---

<p align="center">
  <br>
  If this saves you even one Google search, give it a ⭐
  <br><br>
  <a href="https://github.com/dovzilla/askcmd">
    <img src="https://img.shields.io/github/stars/dovzilla/askcmd?style=social" alt="Star on GitHub">
  </a>
</p>
