floop-client

floop-client is the CLI for project/version uploads and server comments.

floop-client is intentionally small. It helps agents and users choose the right local project/version, upload the right files to floop-server, read server comments, and resolve comments after a newer version addresses them.

It does not build artifacts, validate design tokens, generate UI, or decide which files belong to another tool. The tool or user that owns the files places them in a floop version directory; floop handles the upload and comment loop.

Core Flow

Create/select project -> Create/select version -> Add files -> Upload -> Read comments -> Resolve comments

Installation

pip install floop

Verify:

floop --version

Quick Start

# 1. Initialize workspace
cd your-project
floop init

# 2. Install the floop skill into your AI agent
floop enable copilot     # or: cursor, claude, trae, qwen-code, opencode, openclaw

# 3. Create and select a local project
floop projects create my-review
floop projects use my-review

# 4. Create and select a version
floop versions create v1 --project my-review --artifact-type custom --entrypoint index.html
floop versions use v1 --project my-review

# 5. Put uploadable files in .floop/my-review/v1/

# 6. Configure server access and upload
floop review set --project my-review
floop review upload --project my-review --version v1 --json-output

# 7. Read server comments and cache them locally
floop comments --project my-review --version v1 --version-id <server-version-id> --json-output

# 8. Resolve addressed comments after a newer version has been uploaded
floop resolve <comment-id> --project my-review --version-id <server-version-id> --status resolved

Workspace

.floop/
├─ floop.env              # Server URL + API key only
├─ projects.csv           # Local projects, server bindings, selected project/version
└─ <projectid>/
   └─ <version>/
      ├─ floop.version.json
      ├─ floop.upload.json
      ├─ floop.comments.json
      └─ ...uploadable files...

.floop/floop.env contains secrets. floop-client warns through docs and command copy, but it does not create or edit .floop/.gitignore; ignore policy belongs to the host repository.

Legacy workspaces under .floop/projects/<project>/versions/<version>/ are readable for compatibility. floop-client does not move or delete legacy files automatically.

Commands

Workspace

floop init
floop preview

Projects

floop projects
floop projects create <project>
floop projects use <project>

Versions

floop versions --project <project>
floop versions create <version> --project <project> --artifact-type <type> --entrypoint index.html
floop versions use <version> --project <project>

When a project and version are selected, commands that support defaults can use the selected values.

Server

floop review set --project <project>
floop review upload --project <project> --version <version> --json-output
floop comments --project <project> --version <local-version> --version-id <server-version-id> --json-output
floop resolve <comment-id> --project <project> --version-id <server-version-id> --status resolved

Responsibility Boundary

Supported Agents

For Contributors

Run the full test gate:

PYTHONPATH=src python3 -m pytest --cov=floop --cov-report=term-missing --cov-fail-under=100