Skip to content

add-workflows.md

Latest commit

 

History

History
245 lines (177 loc) · 4.52 KB

add-workflows.md

File metadata and controls

245 lines (177 loc) · 4.52 KB

Add Workflows

Use pubflow add when you already have a project and want to add Pubflow pieces without recreating the app.

The goal is simple: keep your project structure, add only what is needed, and get clear next steps.

Quick Start

Add AI context:

pubflow add context

Add env vars:

pubflow add env

Add a Flowfull client:

pubflow add client

Add Bridge Validation middleware:

pubflow add middleware

Check the project:

pubflow inspect

Add Context

pubflow add context

This installs local Pubflow context for coding agents and IDEs.

Default output:

.pubflow/context/pubflow-context.md
AGENTS.md

Use full context when you want all reference files:

pubflow add context --full

Add editor-specific references:

pubflow add context --cursor
pubflow add context --copilot
pubflow add context --claude
pubflow add context --all

Add Env

pubflow add env

Adds Pubflow env vars to .env.example and optionally .env.

Frontend projects get public-safe env names:

Vite / React: VITE_FLOWLESS_URL, VITE_FLOWFULL_API_URL, VITE_BRIDGE_VALIDATION_SECRET
Expo: EXPO_PUBLIC_FLOWLESS_URL, EXPO_PUBLIC_FLOWFULL_API_URL, EXPO_PUBLIC_BRIDGE_VALIDATION_SECRET
Next.js: NEXT_PUBLIC_FLOWLESS_URL, NEXT_PUBLIC_FLOWFULL_API_URL, NEXT_PUBLIC_BRIDGE_VALIDATION_SECRET

Backend projects get:

FLOWLESS_URL=https://your-flowless-instance.com
BRIDGE_VALIDATION_SECRET=replace-me
FLOWFULL_API_URL=http://localhost:3001
PUBFLOW_VALIDATION_MODE=standard

FLOWLESS_URL points to your Flowless instance. FLOWFULL_API_URL points to the current Flowfull/backend API. BRIDGE_VALIDATION_SECRET is sent as X-Bridge-Secret during Bridge Validation.

Add Client

pubflow add client

The CLI detects your project and recommends a client.

Examples:

pubflow add client react
pubflow add client react-native
pubflow add client universal-js
pubflow add client python
pubflow add client go
pubflow add client rust
pubflow add client elixir

Recommended installs use latest versions where the package manager supports it:

npm install @pubflow/flowfull-client@latest
npm install @pubflow/core@latest @pubflow/react@latest swr zod
npm install @pubflow/react-native@latest
python -m pip install --upgrade flowfull-python
go get github.com/pubflow/flowfull-go@latest
cargo add flowfull

Elixir projects get a safe manual hint:

{:flowfull, "~> 0.1.3"}

Client docs:

Add Middleware

pubflow add middleware

This adds Bridge Validation middleware for supported backends.

Supported targets:

  • Node / TypeScript
  • Python / FastAPI
  • Go / Gin
  • Rust / Axum
  • Elixir / Phoenix

Generated files use bridge as the default namespace:

src/bridge/auth.ts
app/bridge/auth.py
internal/bridge/auth.go
src/bridge/auth.rs
lib/bridge_auth.ex

If a bridge file already exists, the CLI falls back to pubflow naming to avoid overwriting your code.

Rust/Axum projects may need these dependencies if they are not already installed:

cargo add axum chrono reqwest serde serde_json thiserror tower

Bridge Validation uses:

POST {FLOWLESS_URL}/auth/bridge/validate
X-Session-ID: <sessionId>
X-Bridge-Secret: <BRIDGE_VALIDATION_SECRET>

Generated middleware gives you helpers like:

optionalAuth()
requireAuth()
requireUserType()
require_roles()
require_roles_csv()
requirePermission()
requireAdmin()

Exact helper names vary by language/framework, but the pattern is the same.

Detection

The CLI detects common project types from files like:

package.json
app.json
requirements.txt
pyproject.toml
go.mod
Cargo.toml
mix.exs

It also detects package managers:

npm
bun
pnpm
yarn
pip
go
cargo
mix

When the project is unclear, the CLI asks instead of guessing.

Safety

pubflow add is designed to be safe:

  • It creates new middleware files instead of editing route files directly.
  • It does not overwrite existing middleware files.
  • It writes placeholders, never real secrets.
  • It updates .env.example by default.
  • It updates .env only when you confirm.
  • Agent/editor references use marked blocks so they can be updated without duplicating content.

Hints

Every add command prints next steps. You can also review hints later:

pubflow hints
pubflow hints clients
pubflow hints middleware
pubflow hints env
pubflow hints context