wowbits-cli 0.1.0a7
WowBits AI Platform CLI - Manage connectors and integrations for AI workflows
License: MIT
Requires Python: >=3.9
Keywords: ai, api-management, cli, connectors, integrations, wowbits

# WowBits CLI

A command-line interface for building and running WowBits AI agents. Manage connectors, functions, and agents with ease.

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Commands](#commands)
  - [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. **Run initial setup** to configure your environment:

```bash
wowbits setup
```

This will:
- Create a root directory (default: `~/wowbits`)
- Set up required subdirectories (`functions`, `agent_studio`, `agent_runner`, `data`)
- Configure database connection
- Initialize the database schema

2. **Verify installation**:

```bash
wowbits --version
```

## Commands

### Setup

Initialize the WowBits environment and database.

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

**Options:**
- `--root-dir PATH`: Specify a custom root directory (default: `~/wowbits`)

**What it does:**
- Creates the root directory structure
- Sets up PostgreSQL database connection
- Initializes database schema
- Configures environment variables

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

### Run

Run agents with the ADK server.

#### Run Agent

Start an agent server:

```bash
wowbits run 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
# Run agent with web UI (default)
wowbits run agent my_agent

# Run agent in API-only mode
wowbits run agent my_agent --mode api

# Run on custom host and port
wowbits run agent my_agent --host 127.0.0.1 --port 8080
```

### 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. Run the agent
wowbits run 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

### Environment Variables

The CLI uses the following environment variables:

- `WOWBITS_ROOT_DIR`: Root directory for WowBits (set automatically during `setup`)
- Database connection variables (configured in `.env` file during setup)

### 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_ROOT_DIR environment variable is not set"

**Solution:** Run `wowbits setup` or manually set the environment variable:

```bash
export WOWBITS_ROOT_DIR=~/wowbits
```

Add this to your `~/.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 run 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