flukebase 1.0.0
CLI and MCP client for FlukeBase platform - AI-assisted development tools
License: MIT
Requires Python: >=3.11
Keywords: ai, claude, flukebase, mcp, memory

# FlukeBase

CLI and MCP client for AI-assisted development with the FlukeBase platform.

[![PyPI](https://img.shields.io/pypi/v/flukebase)](https://pypi.org/project/flukebase/)
[![Python](https://img.shields.io/pypi/pyversions/flukebase)](https://pypi.org/project/flukebase/)

## Installation

### One-Line Install (Recommended)

**Linux/macOS:**
```bash
curl -sSL https://flukebase.me/install | sh
```

**Windows (PowerShell):**
```powershell
irm https://flukebase.me/install.ps1 | iex
```

### Manual Installation

```bash
# With uv (fastest)
uv tool install flukebase

# With pipx (isolated)
pipx install flukebase

# With pip
pip install flukebase
```

### Requirements

- Python 3.11 or later
- Supports pyenv, asdf, conda, and system Python

## Quick Start

```bash
# Authenticate with FlukeBase
fbc login

# Check installation health
fbc doctor

# View connection status
fbc status

# List your projects
fbc projects
```

## CLI Commands

### Core Commands

| Command | Description |
|---------|-------------|
| `fbc login` | Authenticate with FlukeBase |
| `fbc status` | Check connection status |
| `fbc projects` | List your projects |
| `fbc tools` | List available MCP tools |
| `fbc doctor` | Check installation health |
| `fbc support` | Generate troubleshooting bundle |
| `fbc mcp` | Start MCP server |

### Memory Commands (`fbc mem`)

Store and recall knowledge across sessions.

```bash
# Store a memory
fbc mem remember "API uses OAuth2 with JWT tokens" --type convention --tag auth

# Search memories
fbc mem recall "authentication"

# Advanced search with pagination
fbc mem search "API" --scope myproject --limit 20

# Sync with remote
fbc mem sync myproject --direction both
```

| Command | Description |
|---------|-------------|
| `fbc mem remember` | Store knowledge |
| `fbc mem recall` | Search memories |
| `fbc mem search` | Advanced search with pagination |
| `fbc mem forget` | Remove a memory |
| `fbc mem sync` | Sync with FlukeBase remote |

### WeDo Task Commands (`fbc wedo`)

Manage tasks with the WeDo protocol.

```bash
# Create a task
fbc wedo create TASK-001 "Implement user authentication" --priority high

# List tasks
fbc wedo list --status pending

# Update task status
fbc wedo update TASK-001 completed --note "Implemented OAuth2 flow"

# View progress
fbc wedo progress

# Resume work session
fbc wedo continue
```

| Command | Description |
|---------|-------------|
| `fbc wedo create` | Create a new task |
| `fbc wedo list` | List tasks |
| `fbc wedo update` | Update task status |
| `fbc wedo progress` | View completion stats |
| `fbc wedo continue` | Resume work session |
| `fbc wedo search` | Search tasks |

### Environment Commands (`fbc env`)

Manage environment variables.

```bash
# Pull .env from FlukeBase
fbc env pull --env development

# Show current variables (secrets masked)
fbc env show

# Show with secrets revealed
fbc env show --reveal

# Compare local vs remote
fbc env diff

# Validate required variables
fbc env validate
```

| Command | Description |
|---------|-------------|
| `fbc env pull` | Pull .env from remote |
| `fbc env show` | Display variables (masked) |
| `fbc env diff` | Compare local vs remote |
| `fbc env validate` | Check required variables |

### Session Commands (`fbc session`)

Monitor session health and metrics.

```bash
# Check session health
fbc session health

# View metrics
fbc session metrics --period today

# View history
fbc session history --days 7

# Get productivity score
fbc session score
```

| Command | Description |
|---------|-------------|
| `fbc session health` | Real-time health indicators |
| `fbc session metrics` | Session metrics summary |
| `fbc session history` | View session history |
| `fbc session score` | Calculate productivity score |

### Team Commands (`fbc team`)

View team dashboard and activity.

```bash
# Unified dashboard
fbc team dashboard

# View active agents
fbc team agents

# Activity stream
fbc team activity --limit 20

# Workload distribution
fbc team workload --metric tasks
```

| Command | Description |
|---------|-------------|
| `fbc team dashboard` | Unified dashboard view |
| `fbc team agents` | Show active agents |
| `fbc team activity` | Activity stream |
| `fbc team workload` | Workload distribution |

## MCP Integration

### Claude Code / Claude Desktop

Add to your MCP settings (`~/.config/claude-code/settings.json` or Claude Desktop config):

```json
{
  "mcpServers": {
    "flukebase": {
      "command": "fbc",
      "args": ["mcp"]
    }
  }
}
```

### Available MCP Tools

After connecting, you'll have access to 100+ tools including:

- **Memory**: `mem_remember`, `mem_recall`, `mem_search`, `mem_forget`
- **Tasks**: `wedo_create_task`, `wedo_list_tasks`, `wedo_update_task`
- **Environment**: `env_pull`, `env_show`, `env_diff`, `env_validate`
- **Projects**: `fb_projects`, `fb_sync`, `fb_status`
- **Dashboard**: `fb_dashboard`, `dashboard_agents_live`

Run `fbc tools` to see all available tools.

## Diagnostics

### Health Check

```bash
# Basic health check
fbc doctor

# Verbose output with details
fbc doctor --verbose

# JSON output for scripting
fbc doctor --json
```

### Troubleshooting

```bash
# Generate support bundle
fbc support

# Save to file
fbc support --save support-bundle.json

# JSON output
fbc support --json
```

The support bundle includes:
- System information (OS, architecture)
- Python environment (version, manager, path)
- Configuration status
- Diagnostic results
- Relevant environment variables

## Configuration

Configuration is stored in `~/.flukebase-connect/config.toml`:

```toml
[flukebase]
api_url = "https://flukebase.me/api/v1"
api_token = "fbk_..."
```

### Environment Variables

| Variable | Description |
|----------|-------------|
| `FLUKEBASE_API_URL` | Override API URL |
| `FLUKEBASE_API_TOKEN` | Override API token |
| `FLUKEBASE_CONNECT_HOME` | Override config directory |

## Python Version Managers

The installer automatically detects:

- **pyenv**: `.python-version` files
- **asdf**: `.tool-versions` files
- **conda**: Active conda environments
- **uv**: uv-managed Python
- **venv**: Active virtual environments

## Documentation

- Full documentation: https://flukebase.me/docs
- API Reference: https://flukebase.me/docs/api
- Troubleshooting: https://flukebase.me/docs/troubleshooting

## License

MIT License - See LICENSE for details.