flowpad 0.1.16

Flow CLI & SDK for flowpad

Flow CLI

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

Quick Start

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 (for backend dependency management)

Installation

Install from PyPI:

pip install flowpad

Install a specific version:

pip install flowpad==0.1.12

Install from GitHub (latest):

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

Verify the installation:

flow
# => flow 0.1.12

Uninstallation

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:

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

Backend

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

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

# 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

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

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