JSON Schemas

Every floo command supports --json. This page documents every JSON response schema in one place.

Response format

All commands follow the same envelope: Success:

{
  "success": true,
  "data": { ... }
}

Error:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "suggestion": "What to do about it"
  }
}

Usage pattern

floo <command> --json 2>/dev/null | jq '.data'

Stdout = JSON. Stderr = colored output (spinners, tables). Pipe stderr to /dev/null for clean JSON.

Auth

{ "success": true, "data": { "email": "you@example.com" } }

`floo auth logout --json`

{ "success": true, "data": null }

`floo auth whoami --json`

{ "success": true, "data": { "email": "you@example.com", "api_key": "floo_abc1...ef23", "name": "Pat" } }

`floo auth token --json`

{ "success": true, "data": { "api_key": "floo_abc123..." } }

`floo auth register EMAIL --json`

{ "success": true, "data": { "email": "you@example.com" } }

Init

`floo init NAME --json`

{
  "success": true,
  "data": {
    "app_name": "my-app",
    "files_written": ["floo.app.toml", "floo.service.toml"],
    "detection": { "runtime": "nodejs", "framework": "Next.js", "confidence": "high" },
    "service": { "name": "web", "type": "web", "port": 3000 }
  }
}

Deploy

`floo deploy --json`

{
  "success": true,
  "data": {
    "app": { "id": "uuid", "name": "my-app", "status": "live", "url": "https://..." },
    "deploy": { "id": "uuid", "status": "live", "url": "https://...", "build_logs": "..." },
    "detection": { "runtime": "nodejs", "framework": "Next.js", "version": "^14.0.0", "confidence": "high", "reason": "..." },
    "services": ["web"]
  }
}

`floo deploy --dry-run --json`

{
  "success": true,
  "data": {
    "action": "deploy",
    "app": "my-app",
    "services": [{ "name": "web", "path": ".", "port": 3000, "type": "web", "ingress": "public", "runtime": "nodejs", "framework": "Next.js", "confidence": "high" }],
    "warnings": [],
    "valid": true
  }
}

`floo deploy list --json`

{
  "success": true,
  "data": {
    "deploys": [
      { "id": "uuid", "status": "live", "triggered_by": "github", "commit_sha": "abc1234...", "created_at": "ISO8601" }
    ]
  }
}

`floo deploy rollback APP DEPLOY_ID --json`

{ "success": true, "data": { "deploy": { "id": "uuid", "status": "live" } } }

Apps

`floo apps list --json`

{
  "success": true,
  "data": {
    "apps": [
      { "id": "uuid", "name": "my-app", "status": "live", "url": "https://...", "runtime": "nodejs", "created_at": "ISO8601" }
    ]
  }
}

`floo apps status APP --json`

{
  "success": true,
  "data": { "id": "uuid", "name": "my-app", "status": "live", "url": "https://...", "runtime": "nodejs", "created_at": "ISO8601" }
}

`floo apps delete APP --json`

{ "success": true, "data": { "id": "uuid" } }

GitHub

`floo apps github connect REPO --json`

{ "success": true, "data": { "repo_full_name": "owner/repo", "default_branch": "main" } }

`floo apps github disconnect --json`

{ "success": true, "data": { "app": "my-app" } }

`floo apps github status --json`

{ "success": true, "data": { "repo_full_name": "owner/repo", "default_branch": "main", "connected_at": "ISO8601" } }

Environment Variables

`floo env set KEY=VALUE --app APP --json`

{ "success": true, "data": { "key": "DATABASE_URL", "masked_value": "postgres://us...***" } }

`floo env list --app APP --json`

{
  "success": true,
  "data": {
    "env_vars": [
      { "key": "DATABASE_URL", "masked_value": "postgres://us...***" }
    ]
  }
}

`floo env get KEY --app APP --json`

{ "success": true, "data": { "key": "DATABASE_URL", "value": "postgres://user:pass@host/db" } }

`floo env remove KEY --app APP --json`

{ "success": true, "data": { "key": "DATABASE_URL" } }

Services

`floo services list --app APP --json`

{
  "success": true,
  "data": {
    "services": [
      { "name": "web", "service_type": "web", "status": "live", "ingress": "public", "cloud_run_url": "https://..." }
    ]
  }
}

`floo services info NAME --app APP --json`

{
  "success": true,
  "data": { "name": "web", "service_type": "web", "status": "live", "ingress": "public", "cloud_run_url": "https://...", "port": 3000 }
}

Domains

`floo domains add HOSTNAME --app APP --json`

{ "success": true, "data": { "hostname": "myapp.com", "status": "pending", "dns_instructions": "CNAME ..." } }

`floo domains list --app APP --json`

{
  "success": true,
  "data": {
    "domains": [
      { "hostname": "myapp.com", "status": "pending", "dns_instructions": "CNAME ..." }
    ]
  }
}

`floo domains remove HOSTNAME --app APP --json`

{ "success": true, "data": { "hostname": "myapp.com" } }

Logs

`floo logs --app APP --json`

{
  "success": true,
  "data": {
    "app_name": "my-app",
    "logs": [
      { "timestamp": "ISO8601", "severity": "ERROR", "message": "..." }
    ]
  }
}

Releases

`floo releases list --json`

{
  "success": true,
  "data": {
    "releases": [
      { "release_number": 1, "tag": "v1.0.0", "commit_sha": "abc1234...", "promoted_by": "pat@example.com", "created_at": "ISO8601" }
    ]
  }
}

`floo releases show ID --json`

{
  "success": true,
  "data": { "tag": "v1.0.0", "release_number": 1, "commit_sha": "abc1234...", "promoted_by": "pat@example.com", "deploy_id": "uuid", "image_digest": "sha256:...", "created_at": "ISO8601" }
}

`floo releases promote --json`

{ "success": true, "data": { "tag": "v1.0.0", "release_url": "https://github.com/owner/repo/releases/tag/v1.0.0" } }

Billing

`floo billing usage --json`

{
  "success": true,
  "data": { "plan": "pro", "spend_cap_cents": 5000, "max_spend_cap_cents": 100000, "current_period_spend_cents": 1234, "spend_cap_exceeded": false }
}

`floo billing spend-cap get --json`

{
  "success": true,
  "data": { "spend_cap": 5000, "current_period_spend_cents": 1234, "spend_cap_exceeded": false }
}

Analytics

`floo analytics my-app --json`

{
  "success": true,
  "data": {
    "app_name": "my-app",
    "period": "30d",
    "requests": 12450,
    "errors": 23,
    "error_rate": 0.0018,
    "latency": { "p50": 45, "p95": 230, "p99": 890 },
    "status_codes": { "2xx": 12200, "3xx": 227, "4xx": 15, "5xx": 8 }
  }
}

Skills

`floo skills install --json`

{
  "success": true,
  "data": {
    "path": "/absolute/path/to/SKILL.md",
    "version": "0.3.0",
    "recommended_permissions": {
      "read_only": ["Bash(floo apps list:*)", "..."],
      "read_write": ["Bash(floo deploy:*)", "..."]
    }
  }
}

Version & Update

`floo version --json`

{ "success": true, "data": { "version": "0.2.0" } }

`floo update --json`

{ "success": true, "data": { "version": "0.2.0", "path": "/usr/local/bin/floo" } }

Commands

Reference

​Response format

​Usage pattern

​Auth

​floo auth login --json

​floo auth logout --json

​floo auth whoami --json

​floo auth token --json

​floo auth register EMAIL --json

​Init

​floo init NAME --json

​Deploy

​floo deploy --json

​floo deploy --dry-run --json

​floo deploy list --json

​floo deploy rollback APP DEPLOY_ID --json

​Apps

​floo apps list --json

​floo apps status APP --json

​floo apps delete APP --json

​GitHub

​floo apps github connect REPO --json

​floo apps github disconnect --json

​floo apps github status --json

​Environment Variables

​floo env set KEY=VALUE --app APP --json

​floo env list --app APP --json

​floo env get KEY --app APP --json

​floo env remove KEY --app APP --json

​Services

​floo services list --app APP --json

​floo services info NAME --app APP --json

​Domains

​floo domains add HOSTNAME --app APP --json

​floo domains list --app APP --json

​floo domains remove HOSTNAME --app APP --json

​Logs

​floo logs --app APP --json

​Releases

​floo releases list --json

​floo releases show ID --json

​floo releases promote --json

​Billing

​floo billing usage --json

​floo billing spend-cap get --json

​Analytics

​floo analytics my-app --json

​Skills

​floo skills install --json

​Version & Update

​floo version --json

​floo update --json