floop

floop is an agent skill and CLI for uploading local project versions to floop-server and reading server comments.

floop gives agents a small, repeatable workflow:

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

It does not build files, validate artifact internals, generate UI, or decide which files belong in a version. Other tools or users create the files. floop stores local project/version state, uploads version directories, caches server comments, and updates comment status.

Quick Start for Agents

Use this flow when a user asks to publish with floop:

1. Confirm which floop server to use.
   • SaaS: https://floop-server.vercel.app
   • Custom/self-hosted: ask for the full server URL, for example http://localhost:3000
2. After the server URL is known, tell the user where to create an API key: <server-url>/dashboard -> top-right user menu -> API Keys.
3. Initialize floop with the server URL and key:

floop init --server-url <server-url> --api-key <key>

4. Create or select a local project:

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

5. Create or select a version:

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

6. Put uploadable files in .floop/<project>/<version>/.
7. Upload:

floop review upload --project <project> --version <version> --json-output

8. Give the user previewUrl. The CLI upload API does not require or return a shareUrl; users can open the preview UI and click Share.
9. Read comments when requested:

floop comments --project <project> --version <version> --version-id <server-version-id> --json-output

10. Resolve only comments that were addressed by a newer uploaded version:

floop resolve <comment-id> --project <project> --version-id <server-version-id> --status resolved

Agent rules:

• Do not invent API keys or search unrelated files for secrets.
• Do not leave commands waiting for hidden API key input.
• Do not treat missing shareUrl as an upload failure.
• Do not modify artifact files unless the user asked for that work.

Install

pip install floop
floop --version

Enable the Agent Skill

Install the floop skill into the agent platform used by the current project:

floop enable copilot
floop enable cursor
floop enable claude
floop enable trae
floop enable qwen-code
floop enable opencode
floop enable openclaw

The installed skill is named floop.

Quick Start for Humans

cd your-project

# Initialize workspace and server settings.
floop init --server-url http://localhost:3000 --api-key <key>

# Create/select local state.
floop projects create my-review
floop projects use my-review
floop versions create v1 --project my-review --artifact-type custom --entrypoint index.html
floop versions use v1 --project my-review

# Put uploadable files in .floop/my-review/v1/, then upload.
floop review upload --project my-review --version v1 --json-output

# Read server comments.
floop comments --project my-review --version v1 --version-id <server-version-id> --json-output

Server Setup

floop init accepts server settings:

floop init --server-url <server-url> --api-key <key>

If the API key is not available yet:

1. Open <server-url>/dashboard.
2. Use the top-right user menu.
3. Choose API Keys.
4. Create a key.
5. Rerun floop init --server-url <server-url> --api-key <key>.

You can also set FLOOP_API_KEY in the environment or in .floop/floop.env.

Upload Contract

The upload API succeeds when it returns previewUrl.

{
  "uploaded": true,
  "previewUrl": "https://...",
  "shareUrl": null
}

shareUrl is not part of the CLI upload contract. Open the preview UI and use the Share button when a share link is needed.

Workspace Layout

.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 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 does not move or delete legacy files automatically.

Commands

Workspace

floop init --server-url <server-url> --api-key <key>
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> --server-url <server-url> --api-key <key>
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

floop owns	Other tools or users own
.floop/ workspace	Source files
projects.csv project/version selection	File generation
Server project binding	File validation
Version upload	Build systems
Server comments cache	Artifact internals
Comment status updates	Content changes

Supported Agents

Agent	Command
GitHub Copilot	floop enable copilot
Cursor	floop enable cursor
Claude Code	floop enable claude
Trae IDE	floop enable trae
Qwen Code	floop enable qwen-code
OpenCode	floop enable opencode
OpenClaw	floop enable openclaw

Development

Run the full test gate:

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