FloopFloop CLI

FloopFloop CLI

O FloopFloop CLI (floop) é um cliente de linha de comandos de binário único para a plataforma FloopFloop. Faz tudo o que a consola web faz — criar projetos a partir de um prompt, ver as implementações em direto, refinar projetos num chat REPL — sem sair do terminal.

Ao contrário das chaves de API (que exigem o plano Business), os tokens de dispositivo do CLI estão associados ao teu plano de conta normal, tal como quando inicias sessão na web. O CLI é para pessoas; as chaves de API são para scripts.

Instalar

Escolhe o binário certo para a tua máquina e coloca-o no teu $PATH. A grelha de instalação completa (com botões de cópia) está disponível em 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

O primeiro arranque no macOS ou Windows vai avisar que o binário ainda não está assinado. No macOS, clica com o botão direito → Abrir, ou executa xattr -d com.apple.quarantine /usr/local/bin/floop. No Windows, clica em "Mais informações" → "Executar mesmo assim".

Iniciar sessão

Autoriza o dispositivo na tua conta FloopFloop. O CLI abre o browser, clicas em Aprovar, e o CLI recebe um token de longa duração associado a esta máquina.

floop login

Numa máquina sem interface gráfica (SSH, CI, Docker), usa o fluxo de dispositivo em alternativa:

floop login --device

Vais receber um código para colar em floopfloop.com/device. Após aprovação, o CLI recebe o token e guarda-o em ~/.floop/config.json com permissões 0600.

Verifica a sessão ativa com floop whoami. Termina a sessão com floop logout. Gere todos os dispositivos com sessão iniciada em Conta → Dispositivos.

Comandos

floop new <prompt>

Cria um novo projeto e (por defeito) aguarda que fique disponível.

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

floop list (alias ls)

Lista os teus projetos numa tabela ou em JSON.

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

floop status <project>

Mostra o estado de construção de um projeto. Aceita o ID do projeto ou o subdomínio. Adiciona --watch para transmitir o progresso em tempo real até que a construção atinja um estado terminal.

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

floop chat <project>

Abre um REPL interativo associado a um projeto. Cada linha que escreves é enviada como um refinamento, com progresso de construção em direto. Comandos de barra:

• /help — mostra todos os comandos de barra
• /status — estado pontual
• /open — abre o URL em direto
• /clear — limpa o ecrã
• /exit — sai do REPL (Ctrl+D também funciona)

Durante uma construção, Ctrl+C para de acompanhar; a construção continua a correr no servidor. Prime Ctrl+C novamente (ou /exit) para realmente sair do REPL.

floop refine <project> "<message>"

Refinamento não interativo — o gémeo de scripting de floop chat. Envia uma mensagem de refinamento e sai, sem entrar no REPL. Útil para pipelines de CI ("refinar a página inicial quando este branch é integrado") ou ajustes pontuais.

floop refine my-bot "tighten the dashboard table padding"
floop refine my-bot "fix the typo in the hero" --code-only --watch
floop refine my-bot "swap the brand colour to teal" --json

floop cancel <project> · floop reactivate <project> [--watch]

Cancela uma construção em curso ou reativa um projeto anteriormente cancelado. O reactivate inicia uma nova construção com o prompt mais recente do projeto; com --watch o comando acompanha a nova construção até um estado terminal (live / failed / cancelled / archived) em vez de retornar imediatamente. Mesmo padrão de polling com deduplicação de floop status --watch e floop refine --watch.

floop cancel my-bot
floop reactivate my-bot
floop reactivate my-bot --watch
floop reactivate my-bot --watch --json

floop open <project>

Abre o URL em direto do projeto no teu browser predefinido. Recorre a https://<subdomain>.floop.tech se a API ainda não tiver disponibilizado um URL personalizado.

floop upgrade

Substitui o binário floop pela versão mais recente do GitHub Release. Verifica o SHA256 contra o SHA256SUMS publicado antes de substituir. Adiciona --check para verificar apenas se existe uma atualização sem instalar.

floop upgrade
floop upgrade --check

Funciona apenas para binários compilados. Se instalaste via npm ou estás a executar node dist/index.js a partir do código-fonte, o comando recusa e indica a ferramenta correta.

floop docs · floop feedback

Atalhos rápidos: floop docs abre esta página, floop feedback abre o formulário de suporte / reporte de problemas em floopfloop.com.

floop completion <bash|zsh|fish|powershell>

Imprime um script de autocompletar para a shell no stdout. Instala por 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)

Atualmente o autocompletar é estático — conhece os nomes de comandos e subcomandos, mas não os subdomínios dos teus projetos. O autocompletar dinâmico via cache local está no roadmap.

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

Lê ou altera as definições locais do CLI. Chaves configuráveis: apiUrl(substitui o URL base da API — útil para staging ou auto-alojamento) e telemetry (true/false).

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

O armazenamento de tokens não é intencionalmente configurável via config set— esse caminho mantém os tokens fora do histórico da shell. Usa floop login / floop logout para gerir a sessão ativa.

floop usage

Mostra o teu plano, créditos disponíveis (este mês + acumulados + utilizados ao longo do tempo), e utilização do período atual (projetos criados, construções, refinamentos, armazenamento, largura de banda) face aos limites do teu plano.

floop usage
floop usage --json

floop conversations <project> (alias history)

Imprime o histórico de chat do projeto — mensagens do utilizador, respostas do assistente e marcadores de implementação (● Deployed v2) em ordem cronológica. Adiciona --limit 10 para mostrar apenas as últimas 10 entradas.

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

floop keys <list|create|rm>

Gere chaves de API programáticas (flp_…) para uso em scripts de CI/CD.Diferentes dos tokens de dispositivo de floop login — esses são para pessoas, associados ao teu plano normal; as chaves de API são programáticas, exigem o plano Business, podem ser revogadas individualmente a partir do dashboard ou por nome/id com 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"

O subcomando rmrecusa revogar a chave de API com que a chamada está a ser feita — usa uma chave diferente (ou revoga a partir do dashboard) se realmente queres eliminá-la.

floop library <list|clone>

Navega pelos projetos da biblioteca pública e clona-os para a tua conta.

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

Chat REPL: /attach <file> + seletor interativo

Dentro de floop chat, anexa um ficheiro à tua próxima mensagem de refinamento:

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

O CLI faz o carregamento via o fluxo presigned-PUT existente; os tipos permitidos são png/jpg/gif/svg/webp/ico/pdf/txt/csv/doc/docx, máximo 5 MB. O anexo é consumido pela próxima mensagem que enviares — escrever mais comandos de barra ou premir enter numa linha em branco mantém-no pendente.

floop chat sem argumento de projeto abre um seletor numerado sobre os teus projetos. Com um projeto, seleciona-o diretamente.

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

Auxiliares de scripting para floop new. O check sai com 0 se o slug estiver livre, 1 caso contrário. O suggestimprime um slug disponível derivado de um prompt — redireciona diretamente para --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>]

Gere variáveis de ambiente de escrita exclusiva num projeto. Os valores nunca são devolvidos pela API — o list expõe apenas metadados (chave, últimos 4 caracteres, timestamps). O subcomando set lê o valor de --value, --from-env, ou stdin (por essa ordem) — prefere stdin ou --from-env para valores sensíveis para que não fiquem no histórico da shell.

# 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

As chaves devem ser UPPER_SNAKE_CASE, começar com uma letra, máximo 64 caracteres (corresponde ao validador de segredos do projeto).

Scripting

Todos os comandos suportam --json. Combinado com jq e a variável de ambiente FLOOP_TOKEN (que contorna o login interativo), o CLI é adequado para uso em CI/CD.

# 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

Variáveis de ambiente

Códigos de saída

Códigos de saída documentados para scripting em shell:

Ficheiro de configuração

O CLI guarda a sua sessão em ~/.floop/config.json com permissões 0600 (apenas leitura/escrita do proprietário). O ficheiro contém:

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

O suporte a chaveiro do sistema operativo (macOS Keychain, Windows Credential Manager) está no roadmap.

Privacidade & telemetria

Na primeira execução interativa, o CLI pergunta se queres partilhar dados de utilização anónimos. É opt-in — escolhe n e nunca é enviado nada. Escolhe y e o CLI emite um POST para /api/cli/telemetry por saída de comando, contendo exatamente:

• anonymousId — hex aleatório gerado no opt-in, nunca associado à tua conta
• command — nome do comando de nível superior (ex.: new, list)
• exitCode
• durationMs
• version — versão do CLI
• os — darwin / win32 / linux

Não enviamos: prompts, nomes de projetos, conteúdo de ficheiros, argumentos de comandos, o teu email, o teu endereço IP (o backend regista o IP do pedido para limitação de taxa; não é associado às linhas de telemetria). O payload completo são os seis campos acima.

A lista de exclusões — a telemetria nunca é ativada para floop config, floop completion, floop help, --help, ou --version (estes são circulares, frequentemente redireccionados, ou sem conteúdo). A telemetria tem um limite fixo de 1 segundo e nunca atrasa a saída do CLI.

Desativa em qualquer altura: floop config set telemetry false. Ou edita manualmente ~/.floop/config.json.

Código-fonte & versões

Os binários pré-compilados para macOS, Windows e Linux são publicados nas GitHub Releases a cada tag cli-v*. As notas de versão incluem instruções de instalação e checksums SHA256.

Para uma lista de artefactos de versão, consulta as versões mais recentes.