kiwi-ai-cli 0.2.1

Kiwi AI Terminal Agent — connect your local machine to AI-powered automation

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 installs CLI tools in isolated environments — no conflicts, no venv to manage.

# 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

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). Use pipx instead, or run inside a virtual environment:

python3 -m venv ~/.kiwi-env
source ~/.kiwi-env/bin/activate
pip install kiwi-ai-cli

Windows

pip install kiwi-ai-cli

Upgrade

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

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

Verify your version:

pip show kiwi-ai-cli

Quick Start

# 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

# 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 [e-mail]

# 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.

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:

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)