Metadata-Version: 2.4
Name: wowbits-cli
Version: 0.1.0b7
Summary: WowBits AI Platform CLI - Manage connectors and integrations for AI workflows
Project-URL: Homepage, https://github.com/wowbits/wowbits-cli
Project-URL: Documentation, https://github.com/wowbits/wowbits-cli#readme
Project-URL: Repository, https://github.com/wowbits/wowbits-cli
Project-URL: Issues, https://github.com/wowbits/wowbits-cli/issues
Author-email: WowBits AI <support@wowbits.ai>
License: MIT
Keywords: ai,api-management,cli,connectors,integrations,wowbits
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.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Requires-Dist: psycopg2-binary>=2.9.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: sqlalchemy>=2.0.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# WowBits CLI

CLI and API for building and running WowBits AI agents. The CLI is a thin client; all operations go through the WowBits API.

## Architecture (API-first)

- **One API instance = one workspace.** The API is started with `WOWBITS_ROOT_DIR` set to the workspace path.
- **CLI** requires `WOWBITS_API_URL` and only calls the API (no direct DB or subprocess).
- **Layout:** `core/` (business logic), `api/` (FastAPI), `cli/` (HTTP client), `db/`, `pylibs/`.

**To use the CLI:** Start the API first (see [Running the API](#running-the-api)), then set `WOWBITS_API_URL` (e.g. `http://localhost:8000`) and run `wowbits` commands.

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Commands](#commands)
  - [Start](#start)
  - [Stop](#stop)
  - [Setup](#setup)
  - [List](#list)
  - [Create](#create)
  - [Update](#update)
  - [Delete](#delete)
  - [Run](#run)
  - [Pull](#pull)
- [Examples](#examples)
- [Configuration](#configuration)
- [Troubleshooting](#troubleshooting)

## Installation

Install the WowBits CLI using pip:

```bash
pip install wowbits-cli
```

Or install from source:

```bash
git clone https://github.com/wowbits/wowbits-cli.git
cd wowbits-cli/src
pip install -e .
```

## Quick Start

1. **Create a workspace directory** and set it as the API's workspace:

```bash
export WOWBITS_ROOT_DIR=~/wowbits   # or your path
mkdir -p $WOWBITS_ROOT_DIR
```

2. **Start the WowBits API** (from this repo, with the same workspace):

```bash
cd wowbits-cli/src
export WOWBITS_ROOT_DIR=~/wowbits
pip install -r requirements.txt
wowbits start
```

3. **Use the CLI** (in another terminal):

```bash
export WOWBITS_API_URL=http://localhost:8000
wowbits setup --db-url "sqlite:///$WOWBITS_ROOT_DIR/data/wowbits.db"
wowbits list agents
```

4. **Verify installation**:

```bash
wowbits --version
```

## Running the API

The API serves one workspace per process (Option B). You can start it with the CLI or manually.

**Option 1: `wowbits start`** (recommended)

```bash
export WOWBITS_ROOT_DIR=/path/to/workspace
wowbits start
# Or with host/port (runs as daemon; use wowbits stop to stop):
wowbits start --host 0.0.0.0 --port 8000
# Run attached to terminal instead of daemon:
wowbits start --foreground
# Stop the daemon:
wowbits stop
```

**Option 2: Run uvicorn directly**

```bash
export WOWBITS_ROOT_DIR=/path/to/workspace
cd wowbits-cli/src
uvicorn api.main:app --host 0.0.0.0 --port 8000
```

Optional: create a `.env` in the workspace with `WOWBITS_DB_CONNECTION_STRING=...` so the API can connect to the DB after setup.

## Commands (CLI)

### Start

Start the WowBits API server for the current workspace. Does **not** require `WOWBITS_API_URL` (you are starting the API, not calling it).

```bash
wowbits start [--host HOST] [--port PORT] [--root-dir PATH]
```

**Options:**
- `--host`: Host to bind (default: `0.0.0.0`)
- `--port`, `-p`: Port (default: `8000`)
- `--root-dir`: Workspace path. If omitted, uses `WOWBITS_ROOT_DIR` from the environment.
- `--foreground`, `-f`: Run attached to the terminal instead of as a daemon.

By default the server runs as a daemon: logs go to `workspace/logs/system/api.log`, PID to `workspace/logs/system/api.pid`. Use `wowbits stop` to stop it.

**Example:** Run `wowbits start` (starts API as daemon; use `wowbits stop` to stop). In another terminal set `WOWBITS_API_URL=http://localhost:8000` and use other `wowbits` commands. Use `wowbits start --foreground` to run attached to the terminal.

### Stop

Stop the WowBits API server when it was started with `wowbits start` (daemon mode).

```bash
wowbits stop [--root-dir PATH]
```

**Options:**
- `--root-dir`: Workspace path. If omitted, uses `WOWBITS_ROOT_DIR`.

Sends SIGTERM to the process whose PID is stored in the workspace `.wowbits-api.pid` file, then removes the file. If the process is already gone, the PID file is removed.

### Setup

Initialize the workspace (create dirs, DB tables, init data, save `.env`). **Requires the API to be running** and `WOWBITS_API_URL` set.

```bash
wowbits setup [--db-url URL]
```

**Options:**
- `--db-url URL`: Database URL (e.g. `sqlite:///./data/wowbits.db`). If omitted, you will be prompted.

**What it does:** Calls the API to create workspace subdirs, create tables, load YAML from `data/`, and write `WOWBITS_DB_CONNECTION_STRING` to the workspace `.env`.

### List

List available resources.

#### List Functions

```bash
wowbits list functions
```

Displays all Python functions registered in the database.

#### List Connectors

```bash
wowbits list connectors
```

Shows all configured connectors (API keys, credentials, etc.).

#### List Agents

```bash
wowbits list agents
```

Lists all agents available in the system.

### Create

Create new resources.

#### Create Function

Register Python functions from your functions directory:

```bash
wowbits create function [--dir PATH]
```

**Options:**
- `--dir PATH`: Custom functions directory (default: `WOWBITS_ROOT_DIR/functions`)

**What it does:**
- Scans the functions directory for `.py` files
- Installs dependencies from `functions/requirements.txt` if present
- Registers functions in the database
- Updates existing functions if they already exist

**Function Structure:**
Place your Python functions in `WOWBITS_ROOT_DIR/functions/`. Each `.py` file should contain a function with the same name as the file (without `.py` extension).

Example: `functions/my_function.py` should contain a function named `my_function`.

#### Create Connector

Create a new connector (API credentials, etc.):

```bash
wowbits create connector [--provider PROVIDER] [--config JSON]
```

**Options:**
- `--provider PROVIDER`: Provider name (e.g., `openai`, `anthropic`)
- `--config JSON`: JSON configuration string (if omitted, interactive mode is used)

**Interactive Mode:**
If `--config` is not provided, the CLI will prompt you for configuration values:

```bash
wowbits create connector --provider openai
```

**JSON Config Mode:**
Provide configuration as a JSON string:

```bash
wowbits create connector --provider openai --config '{"api_key": "sk-..."}'
```

**Available Providers:**
Run `wowbits list providers` (if available) or check the providers configuration for supported providers.

#### Create Agent

Create an agent from a YAML configuration file:

```bash
wowbits create agent NAME [-c PATH]
```

**Arguments:**
- `NAME`: Agent name (looks for `WOWBITS_ROOT_DIR/agent_studio/NAME.yaml`)
- `-c, --config PATH`: Custom path to YAML configuration file (optional)

**Example:**
```bash
wowbits create agent my_agent
```

This will look for `~/wowbits/agent_studio/my_agent.yaml` and create the agent based on that configuration.

### Update

Update existing resources.

#### Update Connector

Update an existing connector's configuration:

```bash
wowbits update connectors NAME --config JSON
```

**Arguments:**
- `NAME`: Connector name or ID
- `--config JSON`: JSON configuration string

**Example:**
```bash
wowbits update connectors openai --config '{"api_key": "sk-new-key"}'
```

### Delete

Delete resources.

#### Delete Connector

Remove a connector:

```bash
wowbits delete connectors NAME
```

**Arguments:**
- `NAME`: Connector name or ID

**Example:**
```bash
wowbits delete connectors old_connector
```

### Start

Start agents with the ADK server.

#### Start Agent

Start an agent server:

```bash
wowbits start agent NAME [--mode MODE] [--host HOST] [--port PORT]
```

**Arguments:**
- `NAME`: Agent name

**Options:**
- `--mode, -m MODE`: Execution mode - `web` (ADK web UI) or `api` (ADK API server only). Default: `web`
- `--host HOST`: Host to bind the server to. Default: `0.0.0.0`
- `--port, -p PORT`: Port to run the server on. Default: `5151`

**Examples:**
```bash
# Start agent with web UI (default)
wowbits start agent my_agent

# Start agent in API-only mode
wowbits start agent my_agent --mode api

# Start on custom host and port
wowbits start agent my_agent --host 127.0.0.1 --port 8080

# Stop the running agent
wowbits stop agent my_agent
```

### Pull

Pull resources from remote repositories.

#### Pull Functions

Fetch Python functions from a GitHub repository:

```bash
wowbits pull functions [FUNCTION_NAMES...] --repo-url URL
```

**Arguments:**
- `FUNCTION_NAMES`: Specific function names to pull, or `*` or omit to pull all functions

**Options:**
- `--repo-url URL`: GitHub repository URL (required)

**Examples:**
```bash
# Pull all functions from a repo
wowbits pull functions --repo-url https://github.com/org/repo

# Pull specific functions
wowbits pull functions function1 function2 --repo-url https://github.com/org/repo

# Pull all functions (explicit)
wowbits pull functions * --repo-url https://github.com/org/repo
```

**What it does:**
- Fetches `.py` files from the repository's `functions/` directory (or repo root)
- Saves them to `WOWBITS_ROOT_DIR/functions/`
- Fetches `requirements.txt` if available
- Registers/updates functions in the database

## Examples

### Complete Workflow Example

```bash
# 1. Initial setup
wowbits setup

# 2. Create a connector for OpenAI
wowbits create connector --provider openai
# Follow interactive prompts to enter API key

# 3. Pull functions from a repository
wowbits pull functions --repo-url https://github.com/org/my-functions

# 4. Or create functions locally
# Edit ~/wowbits/functions/my_function.py
wowbits create function

# 5. Create an agent from YAML config
# Edit ~/wowbits/agent_studio/my_agent.yaml
wowbits create agent my_agent

# 6. Start the agent
wowbits start agent my_agent
```

### Function Example

Create a function file `~/wowbits/functions/calculate_sum.py`:

```python
def calculate_sum(a: int, b: int) -> int:
    """Add two numbers together."""
    return a + b
```

Then register it:

```bash
wowbits create function
```

### Agent YAML Example

Create `~/wowbits/agent_studio/my_agent.yaml`:

```yaml
name: my_agent
description: A simple agent example
model: gpt-4
connector: openai
skills:
  - name: basic_skill
    tools:
      - calculate_sum
```

Then create the agent:

```bash
wowbits create agent my_agent
```

**Multi-document YAML format:** When using multiple YAML documents (e.g. tools, skills, and agents in one file), use the `kind` field with WowBits-prefixed values so you can easily filter WowBits configs on GitHub:

- `kind: wowbits_tool` — tool definition
- `kind: wowbits_skill` — skill definition  
- `kind: wowbits_agent` — agent definition

Legacy values `tool`, `skill`, and `agent` are still accepted.

## Configuration

### Configuration

- **WOWBITS_API_URL** (required for CLI): Base URL of the WowBits API (e.g. `http://localhost:8000`).
- **WOWBITS_ROOT_DIR** (required for API): Workspace path. Set when starting the API; one API process serves one workspace.
- **WOWBITS_DB_CONNECTION_STRING**: Database URL. Set in workspace `.env` or before starting the API after running `wowbits setup --db-url ...`.

### Directory Structure

After running `wowbits setup`, your root directory will have this structure:

```
~/wowbits/
├── functions/          # Python function files
│   ├── __init__.py
│   ├── requirements.txt
│   └── *.py           # Your function files
├── agent_studio/      # Agent YAML configurations
│   └── *.yaml
├── agent_runner/      # Generated agent code
│   └── __init__.py
├── data/             # Data files
└── .env              # Environment configuration
```

### Database Configuration

Database connection is configured in the `.env` file in your root directory. The setup command will prompt you for database credentials.

## Troubleshooting

### "WOWBITS_API_URL is not set"

**Solution:** Start the WowBits API (see [Running the API](#running-the-api)), then set the URL:

```bash
export WOWBITS_API_URL=http://localhost:8000
```

Add to `~/.zshrc` or `~/.bashrc` to make it persistent.

### Database Connection Errors

**Solution:** Check your `.env` file in `WOWBITS_ROOT_DIR` and verify database credentials are correct.

### Function Not Found

**Solution:** 
1. Ensure the function file exists in `WOWBITS_ROOT_DIR/functions/`
2. Run `wowbits create function` to register it
3. Verify with `wowbits list functions`

### Agent Creation Fails

**Solution:**
1. Verify the YAML file exists at `WOWBITS_ROOT_DIR/agent_studio/NAME.yaml`
2. Check YAML syntax for errors
3. Ensure referenced connectors and functions exist

### Port Already in Use

**Solution:** Use a different port:

```bash
wowbits start agent my_agent --port 8080
```

## Getting Help

- View help for any command: `wowbits COMMAND --help`
- View general help: `wowbits --help`
- Check version: `wowbits --version`

## License

MIT License - see LICENSE file for details.

## Support

- GitHub Issues: https://github.com/wowbits/wowbits-cli/issues
- Documentation: https://github.com/wowbits/wowbits-cli#readme
