Metadata-Version: 2.4
Name: kiwi-ai-cli
Version: 0.2.2
Summary: Kiwi AI Terminal Agent — connect your local machine to AI-powered automation
Project-URL: Homepage, https://meetkiwi.ai
Author-email: Kiwi AI <support@meetkiwi.ai>
License-Expression: MIT
Keywords: agent,ai,automation,cli,kiwi,llm,remote-execution,terminal
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.25.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: websockets>=12.0
Description-Content-Type: text/markdown

# Kiwi AI CLI

Connect your local machine to AI-powered automation. The Kiwi CLI agent runs on your machine and executes terminal commands on behalf of the LLM agent via a secure WebSocket connection.

## Installation

### Using pipx (recommended for macOS / Linux)

[pipx](https://pypa.github.io/pipx/) installs CLI tools in isolated environments — no conflicts, no venv to manage.

```bash
# Install pipx if you don't have it
brew install pipx     # macOS
sudo apt install pipx # Ubuntu/Debian

# Install kiwi-cli
pipx install kiwi-ai-cli
```

### Using pip

```bash
pip install kiwi-ai-cli
```

> **Getting `externally-managed-environment` error?** Modern macOS/Linux with Homebrew or system Python blocks system-wide pip installs ([PEP 668](https://peps.python.org/pep-0668/)). Use `pipx` instead, or run inside a virtual environment:
> ```bash
> python3 -m venv ~/.kiwi-env
> source ~/.kiwi-env/bin/activate
> pip install kiwi-ai-cli
> ```

### Windows

```bash
pip install kiwi-ai-cli
```

## Upgrade

```bash
# If installed with pipx
pipx upgrade kiwi-ai-cli

# If installed with pip
pip install --upgrade kiwi-ai-cli
```

Verify your version:

```bash
pip show kiwi-ai-cli
```

## Quick Start

```bash
# Connect to Kiwi AI (production server, restricted mode)
kiwi connect

# You'll be prompted for email and password
# Once connected, the LLM agent can run commands on your machine
```

## Usage

```bash
# Connect to production (default)
kiwi connect

# Connect to a specific server
kiwi connect --server dev
kiwi connect --server local
kiwi connect --server wss://custom.server.com

# Provide email upfront (password is always prompted securely)
kiwi connect --email you@example.com

# Skip login with an existing token
kiwi connect --token <your-jwt-token>

# Allow access to additional directories
kiwi connect --allow ~/Documents --allow ~/Projects

# Full access mode (no path restrictions)
kiwi connect --scope full
```

## Flags

| Flag | Description |
|------|-------------|
| `--server` | Server preset (`app`, `dev`, `local`) or a full WebSocket/HTTP URL. Default: `app` (production) |
| `--email` | Email address for login. Prompts interactively if not provided |
| `--token` | Access token to skip email/password login (e.g., from shared auth) |
| `--scope` | `restricted` (default) limits commands to the current directory. `full` removes all path restrictions |
| `--allow` | Additional allowed directory path. Can be used multiple times. Only applies in restricted mode |

## Execution Modes

### Restricted Mode (default)

Commands are validated before execution. The LLM can only access files within:
- The directory where you ran `kiwi connect`
- Any directories added via `--allow`

Paths like `/dev/null`, `/dev/stdin`, etc. are always allowed.

### Full Mode

No path validation. The LLM can execute any command. Use with caution.

```bash
kiwi connect --scope full
```

## Server Presets

| Preset | URL |
|--------|-----|
| `app` (default) | `wss://api.meetkiwi.ai` |
| `dev` | `wss://dev.api.myautobots.com` |
| `local` | `ws://localhost:8000` |

You can also pass a full URL:

```bash
kiwi connect --server https://my-server.com
```

## How It Works

1. You run `kiwi connect` on your machine
2. The CLI authenticates and opens a WebSocket connection to the server
3. When the LLM needs to run a command, the server sends it through the WebSocket
4. The CLI executes it locally and streams the output back
5. The LLM sees the output and decides what to do next

Commands can run in **one-off mode** (independent, no state) or in **persistent sessions** (shell state like `cd`, `export`, environment variables carry over between commands).

## Requirements

- Python 3.10+
- A Kiwi AI account ([meetkiwi.ai](https://meetkiwi.ai))
