# Flow CLI

A local desktop CLI and UI for FlowPad — manage hooks, traces, and agentic workflows from your terminal.

## Quick Start

```bash
pip install flowpad
flow          # prints version
flow start    # launches the UI server and opens browser
```

## Requirements

- Python >= 3.10
- Node.js (for frontend development)
- [uv](https://docs.astral.sh/uv/) (for backend dependency management)

## Installation

Install from PyPI:

```bash
pip install flowpad
```

Install a specific version:

```bash
pip install flowpad==0.1.12
```

Install from GitHub (latest):

```bash
pip install git+https://github.com/langware-labs/flow-cli.git
```

Verify the installation:

```bash
flow
# => flow 0.1.12
```

## Uninstallation

```bash
pip uninstall flowpad
```

## CLI Commands

| Command | Description |
|---------|-------------|
| `flow` | Print version |
| `flow start` | Start the UI server and open browser |
| `flow trace` | Start server and trace hook events in real-time |
| `flow setup <agent>` | Setup FlowPad for a coding agent (e.g. `claude-code`) |
| `flow hooks set` | Install Flow hooks into Claude Code settings |
| `flow hooks list` | List configured hooks |
| `flow hooks clear` | Remove Flow hooks from Claude Code settings |
| `flow config list` | List configuration values |
| `flow config set key=value` | Set a configuration value |
| `flow auth login` | Login to FlowPad (opens browser or accepts API key) |
| `flow auth logout` | Logout and remove stored credentials |
| `flow ping <string>` | Send a test ping to the local server |

## Project Structure

```
flow-cli/
├── sdk/
│   ├── python/
│   │   └── flow_sdk/        # Python SDK package (import flow_sdk)
│   │       ├── cli/          # CLI commands (Typer app)
│   │       ├── core/         # Core infrastructure
│   │       ├── api/          # API types
│   │       ├── db/           # Database drivers (SQLite)
│   │       ├── builtin/      # Built-in entities
│   │       ├── actions/      # Action system
│   │       ├── hooks/        # Hook system
│   │       ├── rules/        # Rules engine
│   │       ├── discovery/    # Service discovery
│   │       ├── fs_records/   # File system record CRUD
│   │       ├── fs_store/     # File system storage
│   │       ├── mcp_server/   # MCP server
│   │       └── client.py     # FlowpadClient
│   └── typescript/
│       └── src/              # TypeScript SDK
├── server/                   # FastAPI server (import server)
│   ├── run.py                # Server entry point
│   ├── server.py             # FastAPI app
│   ├── routes/               # API endpoints
│   ├── middleware/            # Request middleware
│   ├── reporters/            # Event reporters
│   └── static/               # Built UI assets (generated)
├── ui/                       # Frontend source (React/Vite)
│   ├── src/
│   ├── vite.config.ts
│   └── package.json
├── tests/                    # All tests (unit, api, cli)
├── pyproject.toml
└── build_ui.py               # Builds UI into server/static/
```

## Development

### Prerequisites (Windows)

This repo uses git symlinks. On Windows, enable symlink support so they are checked out correctly:

```bash
# Enable symlinks globally (requires Developer Mode or elevated shell)
git config --global core.symlinks true
```

### Backend

```bash
uv sync                        # install Python dependencies
python -m server.run           # start backend server on port 9007
```

The backend serves the API at `http://localhost:9007`. Bootstrap endpoint: `http://localhost:9007/api/v1/graph/bootstrap`

### Frontend

```bash
cd ui
npm install                    # install Node dependencies
npm run dev                    # start Vite dev server on port 4097
```

The frontend runs at `http://localhost:4097` and proxies API calls to the backend.

### Running Tests

```bash
# All backend tests (from repo root)
python -m pytest tests/ -v

# Unit tests only
python -m pytest tests/unit/ -v

# API tests only
python -m pytest tests/api/ -v

# Frontend tests (requires running backend for api/react tests)
cd ui && npx vitest run

# Frontend build + lint
cd ui && npm run build && npm run lint
```

### Building for pip install

```bash
# Build UI assets into server/static/ (required before packaging)
python build_ui.py

# Build the wheel
uv build
```

`build_ui.py` must run before `uv build` — it compiles the frontend into `server/static/assets/` which gets included in the wheel. Without this step, the pip-installed server will serve the HTML shell but 404 on JS/CSS assets.

## Deployment

Use the deploy script to bump version, tag, push, and publish:

```bash
./scripts/deploy_to_github.sh              # runs tests first
./scripts/deploy_to_github.sh --skip-tests # skip tests
./scripts/deploy_to_github.sh --no-pypi    # skip PyPI upload
```

This will:
1. Increment the patch version in `sdk/python/flow_sdk/_version.py`
2. Run tests (unless `--skip-tests`)
3. Commit and tag the release
4. Push to GitHub
5. Build UI assets and wheel
6. Publish to PyPI (unless `--no-pypi`)
7. Validate the installed package
