wowbits-cli 0.1.0b1

WowBits AI Platform CLI - Manage connectors and integrations for AI workflows

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), then set WOWBITS_API_URL (e.g. http://localhost:8000) and run wowbits commands.

Table of Contents

• Installation
• Quick Start
• Commands
  • Start
  • Stop
  • Setup
  • List
  • Create
  • Update
  • Delete
  • Run
  • Pull
• Examples
• Configuration
• Troubleshooting

Installation

Install the WowBits CLI using pip:

pip install wowbits-cli

Or install from source:

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:

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):

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

3. Use the CLI (in another terminal):

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

4. Verify installation:

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)

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

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

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/.wowbits-api.log, PID to workspace/.wowbits-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).

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.

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

wowbits list functions

Displays all Python functions registered in the database.

List Connectors

wowbits list connectors

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

List Agents

wowbits list agents

Lists all agents available in the system.

Create

Create new resources.

Create Function

Register Python functions from your functions directory:

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.):

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:

wowbits create connector --provider openai

JSON Config Mode: Provide configuration as a JSON string:

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:

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:

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:

wowbits update connectors NAME --config JSON

Arguments:

• NAME: Connector name or ID
• --config JSON: JSON configuration string

Example:

wowbits update connectors openai --config '{"api_key": "sk-new-key"}'

Delete

Delete resources.

Delete Connector

Remove a connector:

wowbits delete connectors NAME

Arguments:

• NAME: Connector name or ID

Example:

wowbits delete connectors old_connector

Run

Run agents with the ADK server.

Run Agent

Start an agent server:

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:

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

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:

# 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

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

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

Then register it:

wowbits create function

Agent YAML Example

Create ~/wowbits/agent_studio/my_agent.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:

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), then set the URL:

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:

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