FloopFloop CLI

FloopFloop CLI

The FloopFloop CLI (floop) is a single-binary command-line client for the FloopFloop platform. It does everything the web console does — create projects from a prompt, watch deploys live, refine projects in a chat REPL — without leaving your terminal.

Unlike API keys (which are gated to the Business plan), CLI device tokens are scoped to your normal account plan, exactly like signing in on the web. The CLI is for humans; API keys are for scripts.

Install

Pick the right binary for your machine and put it on your $PATH. The full install grid (with copy buttons) lives at floopfloop.com/cli.

macOS (Apple Silicon)

curl -L https://github.com/FloopFloopAI/floop-cli/releases/latest/download/floop-darwin-arm64 -o /usr/local/bin/floop
chmod +x /usr/local/bin/floop

macOS (Intel)

curl -L https://github.com/FloopFloopAI/floop-cli/releases/latest/download/floop-darwin-x64 -o /usr/local/bin/floop
chmod +x /usr/local/bin/floop

Linux x64

curl -L https://github.com/FloopFloopAI/floop-cli/releases/latest/download/floop-linux-x64 -o /usr/local/bin/floop
chmod +x /usr/local/bin/floop

Windows x64

# In PowerShell:
Invoke-WebRequest https://github.com/FloopFloopAI/floop-cli/releases/latest/download/floop-windows-x64.exe -OutFile $env:USERPROFILE\floop.exe

The first launch on macOS or Windows will warn that the binary isn't signed yet. On macOS, right-click → Open, or run xattr -d com.apple.quarantine /usr/local/bin/floop. On Windows, click "More info" → "Run anyway".

Sign in

Authorize the device against your FloopFloop account. The CLI opens your browser, you click Approve, the CLI receives a long-lived token bound to this machine.

floop login

On a headless machine (SSH, CI, Docker), use the device flow instead:

floop login --device

You'll get a code to paste at floopfloop.com/device. Once approved, the CLI receives the token and saves it to ~/.floop/config.json with 0600 permissions.

Verify the active session with floop whoami. Sign out with floop logout. Manage all signed-in devices from Account → Devices.

Commands

floop new <prompt>

Create a new project and (by default) wait for it to go live.

floop new "a crypto RSI dashboard for BTC and ETH" --subdomain my-rsi

floop list (alias ls)

List your projects in a table or as JSON.

floop list
floop list --json
floop list --team team_abc123

floop status <project>

Show the build status of a project. Accepts either the project ID or the subdomain. Add --watch to stream progress in place until the build reaches a terminal state.

floop status my-rsi
floop status my-rsi --watch
floop status my-rsi --json

floop chat <project>

Open an interactive REPL bound to a project. Each line you type is sent as a refinement, with live build progress. Slash commands:

• /help — show all slash commands
• /status — one-shot status
• /open — open the live URL
• /clear — clear the screen
• /exit — leave the REPL (Ctrl+D also works)

During a build, Ctrl+C stops watching; the build keeps running server-side. Press Ctrl+C again (or /exit) to actually quit the REPL.

floop cancel <project> · floop reactivate <project>

Cancel a running build or reactivate a previously cancelled project.

floop open <project>

Open the project's live URL in your default browser. Falls back to https://<subdomain>.floop.techif the API hasn't surfaced a custom URL yet.

floop upgrade

Replace the floop binary with the latest GitHub Release. Verifies the SHA256 against the published SHA256SUMS before swapping. Add --check to only check for an update without installing.

floop upgrade
floop upgrade --check

Only works for compiled binaries. If you installed via npm or are running node dist/index.js from source, the command will refuse and point at the right tool.

floop docs · floop feedback

Quick shortcuts: floop docs opens this page, floop feedback opens the support / issue-report form on floopfloop.com.

floop completion <bash|zsh|fish|powershell>

Print a shell completion script to stdout. Install per shell:

# bash
echo 'source <(floop completion bash)' >> ~/.bashrc

# zsh — save to a directory on $fpath
floop completion zsh > "${fpath[1]}/_floop"

# fish
floop completion fish > ~/.config/fish/completions/floop.fish

# PowerShell
floop completion powershell | Out-String | Invoke-Expression
# (or append to your $PROFILE to persist)

Today the completion is static — it knows command + subcommand names, not your project subdomains. Dynamic completion via a local cache is on the roadmap.

floop config get [key] · floop config set <key> <value>

Read or change local CLI settings. Settable keys: apiUrl (override the API base URL — useful for staging or self-hosted) and telemetry (true/false).

floop config get
floop config get telemetry
floop config set telemetry false
floop config set apiUrl https://staging.floopfloop.com

Token storage is intentionally NOT settable via config set — that path keeps tokens out of shell history. Use floop login / floop logout to manage the active session.

floop usage

Show your plan, available credits (this month + rolled over + lifetime used), and current-period usage (projects created, builds, refinements, storage, bandwidth) against your plan limits.

floop usage
floop usage --json

floop conversations <project> (alias history)

Print the project's chat history — user messages, assistant responses, and deployment markers (● Deployed v2) in chronological order. Add --limit 10 to show only the last 10 entries.

floop conversations my-bot
floop history my-bot --limit 5
floop conversations my-bot --json

floop keys <list|create|rm>

Manages programmatic API keys (flp_…) for use in CI/CD scripts. Different from floop login's device tokens — those are for humans, scoped to your normal plan; API keys are programmatic, require the Business plan, can be revoked individually from the dashboard or by name/id with floop keys rm.

floop keys list
floop keys create "github-actions"     # raw key shown ONCE — copy it
# In CI:
export FLOOP_TOKEN=flp_…
floop list --json | jq …
# Later:
floop keys rm "github-actions"

The rm subcommand refuses to revoke the API key the call is being made with — bring a different key (or revoke from the dashboard) if you really want to nuke it.

floop library <list|clone>

Browse public library projects and clone them into your account.

floop library list
floop library list --search "trading bot" --sort popular
floop library clone <projectId> --subdomain my-fork

Chat REPL: /attach <file> + interactive picker

Inside floop chat, attach a file to your next refinement message:

floop chat my-bot
you ▸ /attach ./mockup.png
✓ Attached mockup.png (320 KB, image/png)
  Attached to your NEXT message. 1 file(s) pending.
you ▸ make the dashboard look like this

The CLI uploads via the existing presigned-PUT flow; allowed types are png/jpg/gif/svg/webp/ico/pdf/txt/csv/doc/docx, max 5 MB. The attachment is consumed by the next message you send — typing more slash commands or pressing enter on a blank line keeps it pending.

floop chat with no project argument drops into a numbered picker over your projects. With one project, picks it directly.

floop subdomain check <slug> · floop subdomain suggest "<prompt>"

Scripting helpers for floop new. check exits 0 if the slug is free, 1 otherwise. suggestprints an available slug derived from a prompt — pipe directly into --subdomain:

# Pre-flight check
floop subdomain check my-bot && echo "available"

# Auto-pick a slug from the prompt
SLUG=$(floop subdomain suggest "a crypto rsi dashboard for btc")
floop new "a crypto rsi dashboard for btc" --subdomain "$SLUG"

floop secrets <list|set|rm> <project> [<key>]

Manage write-only environment variables on a project. Values are never returned by the API — list only surfaces metadata (key, last 4 chars, timestamps). The set subcommand reads the value from --value, --from-env, or stdin (in that order) — prefer stdin or --from-env for sensitive values so they don't end up in shell history.

# List
floop secrets list my-bot

# Set (most secure: from a local env var)
export STRIPE_KEY="sk_live_..."
floop secrets set my-bot STRIPE_KEY --from-env STRIPE_KEY

# Set (reads from stdin)
floop secrets set my-bot STRIPE_KEY < ./stripe.key

# Remove
floop secrets rm my-bot STRIPE_KEY

Keys must be UPPER_SNAKE_CASE, start with a letter, max 64 chars (matches the project secret validator).

Scripting

Every command supports --json. Combined with jq and the FLOOP_TOKEN environment variable (which bypasses the interactive login), the CLI is suitable for CI/CD use.

# Create a project, capture its ID, poll for live URL
PROJECT=$(floop new "test page" --no-wait --json | jq -r '.project.id')

# Wait until live (or terminal failure)
while true; do
  STATUS=$(floop status "$PROJECT" --json | jq -r '.status.status')
  case "$STATUS" in
    live)      echo "shipped"; break ;;
    failed)    echo "build failed"; exit 1 ;;
    cancelled) echo "cancelled"; exit 1 ;;
  esac
  sleep 5
done

Environment variables

Exit codes

Documented exit codes for shell scripting:

Configuration file

The CLI stores its session at ~/.floop/config.json with permissions 0600 (owner read/write only). The file holds:

{
  "apiUrl": "https://www.floopfloop.com",
  "token": "flp_cli_…",
  "tokenPrefix": "flp_cli_a1b2…",
  "user": { "id": "...", "email": "you@example.com", "name": "..." }
}

OS keychain support (macOS Keychain, Windows Credential Manager) is on the roadmap.

Privacy & telemetry

On its first interactive run, the CLI asks if you want to share anonymous usage data. It is opt-in — choose n and nothing is ever sent. Choose y and the CLI emits one POST to /api/cli/telemetry per command exit, containing exactly:

• anonymousId — random hex generated on opt-in, never joined to your account
• command — top-level command name (e.g. new, list)
• exitCode
• durationMs
• version — CLI version
• os — darwin / win32 / linux

We do notsend: prompts, project names, file contents, command arguments, your email, your IP address (the backend logs the request IP for rate-limiting; it's not joined to telemetry rows). The full payload is the six fields above.

The skip list — telemetry never fires for floop config, floop completion, floop help, --help, or --version (these are either circular, often piped, or content-free). Telemetry has a hard 1-second timeout and never delays the CLI exit.

Disable any time: floop config set telemetry false. Or hand-edit ~/.floop/config.json.

Source & releases

Pre-built binaries for macOS, Windows, and Linux are published to GitHub Releases on every cli-v* tag. The release notes include install instructions and SHA256 checksums.

For a list of release artifacts, browse the latest releases.