semvec/pypi-packages huggingface dataset:
pyphi-cli 0.2.0
Natural language CLI that converts instructions into shell commands using LLMs
License: MIT
Requires Python: >=3.9

# phi

`phi` is a global CLI tool that converts natural‑language instructions into real shell commands using LLMs and executes them on your machine.

Example:

```bash
phi apply the current stash
phi show processes running on port 6379
phi kill the process on port 6379
```

---

## Installation

Install `phi` globally using pip:

```bash
pip install phi
```

Verify installation:

```bash
phi --help
```

The `phi` command is now available globally in your terminal.

---

## LLM API Keys

`phi` currently uses OpenAI by default.

You **must** export an API key before running any command.

### OpenAI

```bash
export OPENAI_API_KEY="sk-..."
```

To make this persistent, add it to your shell config file:

- `~/.zshrc`
- `~/.bashrc`
- `~/.profile`

---

## First Run & Configuration

On the **first run**, `phi` automatically creates a user‑level configuration file that stores environment information such as OS, shell, and tool preferences.

### Config file location

- **macOS / Linux**
  ```
  ~/.config/phi/config.json
  ```

- **Windows**
  ```
  %APPDATA%\phi\config.json
  ```

---

## Config File Structure

Example `config.json`:

```json
{
  "os": "Darwin",
  "shell": "zsh",
  "provider": "openai",
  "preferred_tools": [
    {
      "name": "git",
      "description": "Use git commands assuming GitLab remotes and standard workflows"
    },
    {
      "name": "lsof",
      "description": "Use lsof on macOS instead of Linux tools like fuser"
    }
  ]
}
```

### Fields

- **os**  
  Automatically detected operating system (`Darwin`, `Linux`, `Windows`).

- **shell**  
  Detected from your environment (`zsh`, `bash`, etc.).

- **provider**  
  LLM provider to use (`openai` by default).

- **preferred_tools**  
  Optional list of tools that `phi` should prefer when generating commands.

  Each tool entry contains:
  - `name`: tool name
  - `description`: how and when the tool should be used

You can edit this file manually at any time.

---

## Usage

Run `phi` followed by a natural‑language instruction:

```bash
phi list all git branches
phi check if redis is running
phi show processes using port 6379
```

`phi` will:

1. Convert your instruction into shell commands using an LLM
2. Execute them in your terminal
3. Print the output

---

## Notes

- `phi` executes **real shell commands** — use with care
- Commands are generated to match your OS automatically
- Safety checks, retries, and confirmations are planned for future versions

---

## License

MIT