wokku-cli 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 820e03562fff67b93f087227eb2da57e79e761c43ac5c108680699ce068a480e
-  data.tar.gz: '077218e9886faadb334a615e225a3f61802688f29f6e9ac53625ca4f505f632d'
+  metadata.gz: 07765bcc128b05f4309dcba3b0b5ac7679a67ecb7db3da6bac86b6ebe947b44d
+  data.tar.gz: 466a009f4a186f7e621e16fbb74bae021b150a0a7bdef4f5f3e22eba417620f5
 SHA512:
-  metadata.gz: 9518d6c33f111278305093a0d55f925772fe3363f4abe95df3d32b83e105d03f3e0bd2001add8f696c717d5e89352926fec2c1220fe7cb74baebc523a8c6812d
-  data.tar.gz: 1326795840aae9837bb480a821e466ce8c64e90a0fc5ed2f01c8929b7adb16da27760aa7d3c459fc65cf60afd18ac5de006be0e790d639af8eb6e09296ae9dcd
+  metadata.gz: e3e6bbadba6e52c20b843542879100f0d4d40428c4b1a3f877c171c6f84452ff67ffc0bce4a15dfe182115bc32b1b7c5ea44000d8d88559c41b6e69c24bcdfde
+  data.tar.gz: '058f35efb1dd358b5183169fbdb35ef5ce7ee68ab708576cbed8ee9b03d01a896d9c465fed9cf53d655283bc4fa3621b944f22117825e7efe9fa87c61ed245e0'

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.5.0 — 2026-06-04
+
+`wokku tunnel` — share a local port at `https://<sub>.wokku.dev` in one command. Pairs with wokku-cloud canonical backlog 3.4.
+
+### Added
+
+- `wokku tunnel PORT [--subdomain S] [--app A]` — provisions a tunnel session via `POST /api/v1/tunnels`, downloads `frpc` v0.62.1 to `~/.wokku/bin/` on first run (~10 MB, one time), writes a per-process `frpc.toml`, execs frpc against the wokku-tunnel gateway, and closes the session on Ctrl-C.
+
+Plan-tiered: Free gets 1 tunnel with a random subdomain and 2h timeout (watermarked); Solo+ unlocks custom subdomains and 3+ concurrent tunnels with no timeout. Server-side enforcement — the CLI just surfaces whichever the API returned.
+
 ## 0.4.0 — 2026-06-01
 
 MCP commands — wire the wokku-plugin Claude Code MCP server with one command. Pairs with wokku-cloud canonical backlog 1.3.

data/lib/wokku/commands/apps_lifecycle.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# --- App lifecycle (rename / clone / lock / unlock / transfer) ---
+
+register "apps:rename", "Rename an app (usage: wokku apps:rename APP NEW_NAME [--force])" do
+  id = ARGV.shift || abort("Usage: wokku apps:rename APP NEW_NAME [--force]")
+  new_name = ARGV.shift || abort("Missing NEW_NAME. Example: wokku apps:rename myapp myapp-renamed")
+  force = ARGV.delete("--force")
+  unless force || !$stdout.tty?
+    print "Rename `#{id}` to `#{new_name}`? This breaks deployed bookmarks. [y/N] "
+    answer = $stdin.gets.to_s.strip.downcase
+    abort "Aborted." unless answer == "y"
+  end
+  data = api(:patch, "/apps/#{id}/rename", { name: new_name })
+  Wokku::Output.status "Renamed to #{(data.is_a?(Hash) ? data['name'] : new_name)}."
+end
+
+register "apps:clone", "Clone an app config (no env vars/data carried). Usage: wokku apps:clone APP NEW_NAME [--no-skip-deploy]" do
+  id = ARGV.shift || abort("Usage: wokku apps:clone APP NEW_NAME [--no-skip-deploy]")
+  new_name = ARGV.shift || abort("Missing NEW_NAME. Example: wokku apps:clone myapp myapp-copy")
+  skip_deploy = !ARGV.delete("--no-skip-deploy")
+  data = api(:post, "/apps/#{id}/clone", { name: new_name, skip_deploy: skip_deploy })
+  Wokku::Output.status "Cloned to #{(data.is_a?(Hash) ? data['name'] : new_name)}. Push code to its remote to deploy."
+end
+
+register "apps:lock", "Set the dokku deploy lock (blocks future git push). Usage: wokku apps:lock APP" do
+  id = ARGV.shift || abort("Usage: wokku apps:lock APP")
+  data = api(:post, "/apps/#{id}/lock")
+  Wokku::Output.status((data.is_a?(Hash) && data["locked"]) ? "locked" : "ok")
+end
+
+register "apps:unlock", "Release the dokku deploy lock. Usage: wokku apps:unlock APP" do
+  id = ARGV.shift || abort("Usage: wokku apps:unlock APP")
+  data = api(:post, "/apps/#{id}/unlock")
+  Wokku::Output.status((data.is_a?(Hash) && data["locked"] == false) ? "unlocked" : "ok")
+end
+
+register "apps:transfer", "Initiate an app transfer to another user (they accept via email). Usage: wokku apps:transfer APP RECIPIENT_EMAIL [--force]" do
+  id = ARGV.shift || abort("Usage: wokku apps:transfer APP RECIPIENT_EMAIL [--force]")
+  recipient = ARGV.shift || abort("Missing RECIPIENT_EMAIL")
+  force = ARGV.delete("--force")
+  unless force || !$stdout.tty?
+    print "Transfer `#{id}` to `#{recipient}`? They must accept via the email link to take ownership. [y/N] "
+    answer = $stdin.gets.to_s.strip.downcase
+    abort "Aborted." unless answer == "y"
+  end
+  data = api(:post, "/apps/#{id}/transfer", { recipient_email: recipient })
+  email = data.is_a?(Hash) ? data["recipient_email"] : recipient
+  Wokku::Output.status "Transfer requested. #{email} will receive an email."
+end

data/lib/wokku/commands/billing.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# --- Billing (plan + usage; checkout/portal stay in the dashboard) ---
+
+register "billing:plan", "Show your current Wokku plan + limits (usage: wokku billing:plan)" do
+  data = api(:get, "/billing/current_plan")
+  data = {} unless data.is_a?(Hash)
+  Wokku::Output.status "plan: #{data['plan'] || 'unknown'}"
+  Wokku::Output.status "max apps: #{data['max_apps']}"        if data.key?("max_apps")
+  Wokku::Output.status "max databases: #{data['max_databases']}" if data.key?("max_databases")
+end
+
+register "billing:usage", "Show month-to-date usage (usage: wokku billing:usage)" do
+  data = api(:get, "/billing/usage")
+  data = {} unless data.is_a?(Hash)
+
+  Wokku::Output.status "current: $#{format('%.2f', data['current_cost_dollars'] || 0.0)}"
+  Wokku::Output.status "projected: $#{format('%.2f', data['projected_cost_dollars'] || 0.0)}"
+  Wokku::Output.status "payment method: #{data['has_payment_method'] ? 'yes' : 'no'}"
+
+  resources = Array(data["resources"])
+  if resources.any?
+    Wokku::Output.status ""
+    Wokku::Output.status "resources:"
+    resources.each do |r|
+      cents = r["current_cost_cents"].to_i
+      Wokku::Output.status "  #{r['resource_type']}  #{r['tier_name']}  $#{format('%.2f', cents / 100.0)}"
+    end
+  end
+end

data/lib/wokku/commands/cdn.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# --- Cloudflare CDN proxy toggle ---
+
+def print_cdn_state(enabled, note: nil)
+  Wokku::Output.status "cdn: #{enabled ? 'on' : 'off'}"
+  warn note if note
+end
+
+register "cdn", "Show Cloudflare CDN proxy state (usage: wokku cdn APP)" do
+  id = ARGV.shift || abort("Usage: wokku cdn APP")
+  data = api(:get, "/apps/#{id}")
+  print_cdn_state(data.is_a?(Hash) && data["cloudflare_proxied"])
+end
+
+register "cdn:on", "Enable Cloudflare CDN proxy (usage: wokku cdn:on APP)" do
+  id = ARGV.shift || abort("Usage: wokku cdn:on APP")
+  data = api(:patch, "/apps/#{id}/cdn", { enabled: true })
+  print_cdn_state(data.is_a?(Hash) ? data["enabled"] : true, note: "DNS propagation may take a minute.")
+end
+
+register "cdn:off", "Disable Cloudflare CDN proxy (usage: wokku cdn:off APP)" do
+  id = ARGV.shift || abort("Usage: wokku cdn:off APP")
+  data = api(:patch, "/apps/#{id}/cdn", { enabled: false })
+  print_cdn_state(data.is_a?(Hash) ? data["enabled"] : false)
+end

data/lib/wokku/commands/cron.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# --- Scheduled tasks (cron) ---
+
+register "cron", "List scheduled tasks for an app (usage: wokku cron APP)" do
+  id = ARGV.shift || abort("Usage: wokku cron APP")
+  data = api(:get, "/apps/#{id}/scheduled_tasks")
+  tasks = data.is_a?(Array) ? data : []
+  if tasks.empty?
+    Wokku::Output.status "no scheduled tasks"
+    next
+  end
+  tasks.each do |t|
+    Wokku::Output.status "#{t['id']}  #{t['schedule']}  #{t['command']}#{t['description'] ? " (#{t['description']})" : ''}"
+  end
+end
+
+register "cron:add", "Add a scheduled task. Usage: wokku cron:add APP --schedule '* * * * *' --command 'CMD' [--description 'DESC']" do
+  id = ARGV.shift || abort("Usage: wokku cron:add APP --schedule '...' --command '...' [--description '...']")
+  schedule = nil
+  command  = nil
+  description = nil
+  while arg = ARGV.shift
+    case arg
+    when "--schedule"    then schedule    = ARGV.shift
+    when "--command"     then command     = ARGV.shift
+    when "--description" then description = ARGV.shift
+    end
+  end
+  abort "Missing --schedule" if schedule.nil? || schedule.empty?
+  abort "Missing --command"  if command.nil?  || command.empty?
+
+  data = api(:post, "/apps/#{id}/scheduled_tasks", { command: command, schedule: schedule, description: description })
+  task_id = data.is_a?(Hash) ? data["id"] : nil
+  Wokku::Output.status "Scheduled task added#{task_id ? " (id=#{task_id})" : ''}."
+end
+
+register "cron:remove", "Remove a scheduled task (usage: wokku cron:remove APP TASK_ID)" do
+  id      = ARGV.shift || abort("Usage: wokku cron:remove APP TASK_ID")
+  task_id = ARGV.shift || abort("Missing TASK_ID")
+  api(:delete, "/apps/#{id}/scheduled_tasks/#{task_id}")
+  Wokku::Output.status "Scheduled task removed."
+end

data/lib/wokku/commands/db_monitor.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# --- Database monitor (connections, cache hit, slow queries) ---
+
+register "db:monitor", "Show database connections, cache hit, size, and slow queries (usage: wokku db:monitor DB)" do
+  id = ARGV.shift || abort("Usage: wokku db:monitor DB")
+  data = api(:get, "/databases/#{id}/monitor")
+
+  if !data.is_a?(Hash) || data["recorded_at"].nil?
+    Wokku::Output.status "no stats collected yet"
+    next
+  end
+
+  size_mb = data["db_size_bytes"] ? (data["db_size_bytes"].to_f / (1024 * 1024)).round(2) : nil
+  Wokku::Output.status "conns: #{data['active_connections']} / #{data['max_connections']}"
+  Wokku::Output.status "size: #{size_mb} MB" if size_mb
+  Wokku::Output.status "cache hit: #{(data['cache_hit_ratio'].to_f * 100).round(2)}%"
+
+  queries = Array(data["top_queries"]).first(5)
+  if queries.any?
+    Wokku::Output.status ""
+    Wokku::Output.status "top queries:"
+    queries.each do |q|
+      qstr = q["query"].to_s.gsub(/\s+/, " ").strip
+      qstr = qstr[0, 80] + "…" if qstr.length > 80
+      Wokku::Output.status "  #{qstr}"
+      Wokku::Output.status "    calls=#{q['calls']} mean=#{q['mean_ms']}ms total=#{q['total_ms']}ms"
+    end
+  end
+end

data/lib/wokku/commands/dev.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "socket"
+require "uri"
+
+# --- wokku dev: prod env + read-only DB tunnel for local dev ---
+
+register "dev",
+         "Run a local command with prod env + read-only DB tunnel. Usage: wokku dev APP [--duration MIN] [--rw] [--local-port N] -- CMD [ARGS...]" do
+  args = ARGV.dup
+  ARGV.clear
+
+  id        = args.shift || abort("Usage: wokku dev APP [flags] -- CMD [ARGS...]")
+  duration  = 30
+  readwrite = false
+  local_port = 5433
+  user_cmd  = nil
+
+  while (arg = args.shift)
+    case arg
+    when "--duration"   then duration = args.shift.to_i
+    when "--rw"         then readwrite = true
+    when "--local-port" then local_port = args.shift.to_i
+    when "--"           then user_cmd = args.dup; break
+    end
+  end
+
+  abort "Missing user command. Add `-- bin/rails s` (or similar) after wokku flags." if user_cmd.nil? || user_cmd.empty?
+
+  session = api(:post, "/apps/#{id}/dev_sessions", { duration_min: duration.positive? ? duration : 30 })
+  session_id = session["session_id"]
+
+  tunnel_args = [
+    "ssh", "-N",
+    "-L", "#{local_port}:#{session['db_remote_host']}:#{session['db_remote_port']}",
+    "-p", session["ssh_port"].to_s,
+    "-o", "ExitOnForwardFailure=yes",
+    "-o", "ServerAliveInterval=30",
+    "-o", "StrictHostKeyChecking=accept-new",
+    "#{session['ssh_user']}@#{session['ssh_host']}"
+  ]
+  tunnel_pid = Process.spawn(*tunnel_args)
+
+  ready = false
+  10.times do
+    begin
+      Socket.tcp("127.0.0.1", local_port, connect_timeout: 0.5) { |s| s.close rescue nil }
+      ready = true
+    rescue StandardError
+      sleep 0.5
+    end
+    break if ready
+  end
+
+  unless ready
+    Process.kill("TERM", tunnel_pid) rescue nil
+    api(:delete, "/apps/#{id}/dev_sessions/#{session_id}") rescue nil
+    abort "SSH tunnel failed to come up on port #{local_port}. Aborting."
+  end
+
+  env_data = api(:get, "/apps/#{id}/config")
+  env = env_data.is_a?(Hash) ? env_data.dup : {}
+
+  if env["DATABASE_URL"].to_s.start_with?("postgres")
+    db = URI.parse(env["DATABASE_URL"])
+    db.host = "localhost"
+    db.port = local_port
+
+    if readwrite
+      warn "⚠️  --rw MODE: writes will hit PROD database. 5s to Ctrl-C..."
+      sleep 5 unless ENV["WOKKU_DEV_SKIP_SLEEP"] == "1"
+    else
+      existing_query = db.query.to_s
+      ro = "options=-c%20default_transaction_read_only%3Don"
+      db.query = existing_query.empty? ? ro : "#{existing_query}&#{ro}"
+    end
+
+    env["DATABASE_URL"] = db.to_s
+  end
+
+  exit_status = nil
+  begin
+    user_pid = Process.spawn(env, *user_cmd)
+    _, status = Process.wait2(user_pid)
+    exit_status = status.exitstatus || 0
+  ensure
+    Process.kill("TERM", tunnel_pid) rescue nil
+    api(:delete, "/apps/#{id}/dev_sessions/#{session_id}") rescue nil
+  end
+
+  exit exit_status if exit_status
+end

data/lib/wokku/commands/github.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# --- GitHub repository connect / disconnect ---
+
+register "github:connect", "Connect a GitHub repo to an app (usage: wokku github:connect APP REPO [--branch BRANCH])" do
+  id   = ARGV.shift || abort("Usage: wokku github:connect APP REPO [--branch BRANCH]")
+  repo = ARGV.shift || abort("Missing REPO. Example: wokku github:connect myapp owner/repo")
+  branch = "main"
+  while arg = ARGV.shift
+    case arg
+    when "--branch" then branch = ARGV.shift || abort("--branch requires a value")
+    end
+  end
+
+  data = api(:post, "/apps/#{id}/github_connect", { repo: repo, branch: branch })
+  message = data.is_a?(Hash) ? data["message"] : nil
+  Wokku::Output.status(message || "Connected to #{repo} (#{branch}).")
+end
+
+register "github:disconnect", "Disconnect the GitHub repo from an app (usage: wokku github:disconnect APP)" do
+  id = ARGV.shift || abort("Usage: wokku github:disconnect APP")
+  data = api(:delete, "/apps/#{id}/github_disconnect")
+  message = data.is_a?(Hash) ? data["message"] : nil
+  Wokku::Output.status(message || "Disconnected.")
+end

data/lib/wokku/commands/https.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# --- HTTPS redirect toggle ---
+
+def print_https_state(enabled)
+  Wokku::Output.status "https redirect: #{enabled ? 'on' : 'off'}"
+end
+
+register "https", "Show HTTPS redirect state (usage: wokku https APP)" do
+  id = ARGV.shift || abort("Usage: wokku https APP")
+  data = api(:get, "/apps/#{id}")
+  print_https_state(data.is_a?(Hash) && data["https_redirect"])
+end
+
+register "https:on", "Enable HTTPS redirect (usage: wokku https:on APP)" do
+  id = ARGV.shift || abort("Usage: wokku https:on APP")
+  data = api(:patch, "/apps/#{id}/https", { enabled: true })
+  print_https_state(data.is_a?(Hash) ? data["enabled"] : true)
+end
+
+register "https:off", "Disable HTTPS redirect (usage: wokku https:off APP)" do
+  id = ARGV.shift || abort("Usage: wokku https:off APP")
+  data = api(:patch, "/apps/#{id}/https", { enabled: false })
+  print_https_state(data.is_a?(Hash) ? data["enabled"] : false)
+end

data/lib/wokku/commands/maintenance.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# --- Maintenance mode toggle ---
+
+def print_maintenance_state(enabled)
+  Wokku::Output.status "maintenance: #{enabled ? 'on' : 'off'}"
+end
+
+register "maintenance", "Show maintenance mode state (usage: wokku maintenance APP)" do
+  id = ARGV.shift || abort("Usage: wokku maintenance APP")
+  data = api(:get, "/apps/#{id}")
+  print_maintenance_state(data.is_a?(Hash) && data["maintenance_enabled"])
+end
+
+register "maintenance:on", "Enable maintenance mode (usage: wokku maintenance:on APP)" do
+  id = ARGV.shift || abort("Usage: wokku maintenance:on APP")
+  data = api(:patch, "/apps/#{id}/maintenance", { enabled: true })
+  print_maintenance_state(data.is_a?(Hash) ? data["enabled"] : true)
+end
+
+register "maintenance:off", "Disable maintenance mode (usage: wokku maintenance:off APP)" do
+  id = ARGV.shift || abort("Usage: wokku maintenance:off APP")
+  data = api(:patch, "/apps/#{id}/maintenance", { enabled: false })
+  print_maintenance_state(data.is_a?(Hash) ? data["enabled"] : false)
+end

data/lib/wokku/commands/metrics.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# --- App runtime metrics (CPU / memory) ---
+
+register "metrics", "Show latest CPU + memory for an app (usage: wokku metrics APP)" do
+  id = ARGV.shift || abort("Usage: wokku metrics APP")
+  data = api(:get, "/apps/#{id}/metrics")
+  minute = data.is_a?(Hash) ? Array(data["minute"]) : []
+
+  if minute.empty?
+    Wokku::Output.status "no metrics collected yet"
+    next
+  end
+
+  last = minute.last
+  cpu = last["cpu_pct"]
+  mem = last["memory_mb"]
+  limit = last["memory_limit_mb"]
+  Wokku::Output.status "cpu: #{cpu}%"
+  Wokku::Output.status "mem: #{mem} MB#{limit ? " / #{limit} MB" : ''}"
+end

data/lib/wokku/commands/monitor.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# --- App HTTP request monitor (req-rate, latency, error %) ---
+
+register "monitor", "Show request totals and slow URLs (usage: wokku monitor APP)" do
+  id = ARGV.shift || abort("Usage: wokku monitor APP")
+  data = api(:get, "/apps/#{id}/monitor")
+  totals = data.is_a?(Hash) ? (data["totals"] || {}) : {}
+
+  if totals["req_count"].to_i.zero?
+    Wokku::Output.status "no requests in the last 24h"
+    next
+  end
+
+  Wokku::Output.status "req: #{totals['req_count']}"
+  Wokku::Output.status "rpm: #{totals['rpm']}"
+  Wokku::Output.status "p50: #{totals['p50_ms']}ms"
+  Wokku::Output.status "p95: #{totals['p95_ms']}ms"
+  Wokku::Output.status "error rate: #{((totals['error_rate'].to_f * 100).round(2))}%"
+
+  slow = Array(data["recent_slow"]).first(3)
+  if slow.any?
+    Wokku::Output.status ""
+    Wokku::Output.status "top slow:"
+    slow.each do |s|
+      Wokku::Output.status "  #{s['method']} #{s['path']} #{s['response_time_ms']}ms (#{s['status']})"
+    end
+  end
+end

data/lib/wokku/commands/notifications.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# --- Notifications (team-scoped channels) ---
+
+register "notifications", "List your notifications (usage: wokku notifications)" do
+  data = api(:get, "/notifications")
+  rows = data.is_a?(Array) ? data : []
+  if rows.empty?
+    Wokku::Output.status "no notifications"
+    next
+  end
+  rows.each do |n|
+    events = Array(n["events"]).join(",")
+    Wokku::Output.status "#{n['id']}  #{n['channel']}  #{events}"
+  end
+end
+
+register "notifications:add",
+         "Add a notification (email only in v1). Usage: wokku notifications:add --team TEAM_ID --channel email --events EVENT1,EVENT2" do
+  team_id = nil
+  channel = nil
+  events  = nil
+  while arg = ARGV.shift
+    case arg
+    when "--team"     then team_id = ARGV.shift
+    when "--channel"  then channel = ARGV.shift
+    when "--events"   then events  = ARGV.shift
+    end
+  end
+  abort "Missing --team TEAM_ID"         if team_id.nil? || team_id.empty?
+  abort "Missing --channel email"        if channel.nil? || channel.empty?
+  abort "v1 only supports --channel email (use the dashboard for slack/webhook/etc.)" unless channel == "email"
+  abort "Missing --events. Example: --events deploy_succeeded,deploy_failed" if events.nil? || events.empty?
+
+  data = api(:post, "/notifications", {
+    team_id: team_id,
+    channel: channel,
+    events: events.split(",").map(&:strip)
+  })
+  id = data.is_a?(Hash) ? data["id"] : nil
+  Wokku::Output.status "Notification added#{id ? " (id=#{id})" : ''}."
+end
+
+register "notifications:remove", "Remove a notification (usage: wokku notifications:remove NOTIFICATION_ID)" do
+  id = ARGV.shift || abort("Usage: wokku notifications:remove NOTIFICATION_ID")
+  data = api(:delete, "/notifications/#{id}")
+  message = data.is_a?(Hash) ? data["message"] : nil
+  Wokku::Output.status(message || "Notification removed.")
+end

data/lib/wokku/commands/previews.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# --- PR previews ---
+
+register "previews", "List PR preview apps (usage: wokku previews APP)" do
+  id = ARGV.shift || abort("Usage: wokku previews APP")
+  data = api(:get, "/apps/#{id}/previews")
+  rows = data.is_a?(Array) ? data : []
+  if rows.empty?
+    Wokku::Output.status "no preview apps"
+    next
+  end
+  rows.each do |p|
+    line = "##{p['pr_number']}  #{p['branch']}  #{p['status']}  #{p['name']}"
+    line += "  #{p['url']}" if p["url"]
+    Wokku::Output.status line
+  end
+end
+
+register "previews:destroy", "Queue cleanup of a PR preview (usage: wokku previews:destroy APP PR_NUMBER)" do
+  id  = ARGV.shift || abort("Usage: wokku previews:destroy APP PR_NUMBER")
+  pr  = ARGV.shift || abort("Missing PR_NUMBER")
+  data = api(:delete, "/apps/#{id}/previews/#{pr}")
+  message = data.is_a?(Hash) ? data["message"] : nil
+  Wokku::Output.status(message || "Preview destroy queued.")
+end

data/lib/wokku/commands/teams.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+# --- Teams + team members ---
+
+register "teams", "List the teams you have access to (usage: wokku teams)" do
+  data = api(:get, "/teams")
+  rows = data.is_a?(Array) ? data : []
+  if rows.empty?
+    Wokku::Output.status "no teams"
+    next
+  end
+  rows.each do |t|
+    Wokku::Output.status "#{t['id']}  #{t['name']}"
+  end
+end
+
+register "teams:create", "Create a team (usage: wokku teams:create NAME)" do
+  name = ARGV.shift || abort("Usage: wokku teams:create NAME")
+  data = api(:post, "/teams", { name: name })
+  team_id = data.is_a?(Hash) ? data["id"] : nil
+  Wokku::Output.status "Team created#{team_id ? " (id=#{team_id})" : ''}."
+end
+
+register "teams:members", "List members of a team (usage: wokku teams:members TEAM_ID)" do
+  team_id = ARGV.shift || abort("Usage: wokku teams:members TEAM_ID")
+  data = api(:get, "/teams/#{team_id}/members")
+  rows = data.is_a?(Array) ? data : []
+  if rows.empty?
+    Wokku::Output.status "no members"
+    next
+  end
+  rows.each do |m|
+    Wokku::Output.status "#{m['id']}  #{m['email']}  #{m['role']}"
+  end
+end
+
+register "teams:members:add", "Add a member to a team. Usage: wokku teams:members:add TEAM_ID --email EMAIL [--role member|admin]" do
+  team_id = ARGV.shift || abort("Usage: wokku teams:members:add TEAM_ID --email EMAIL [--role member|admin]")
+  email = nil
+  role  = "member"
+  while arg = ARGV.shift
+    case arg
+    when "--email" then email = ARGV.shift
+    when "--role"  then role  = ARGV.shift
+    end
+  end
+  abort "Missing --email" if email.nil? || email.empty?
+
+  data = api(:post, "/teams/#{team_id}/members", { email: email, role: role })
+  membership_id = data.is_a?(Hash) ? data["id"] : nil
+  Wokku::Output.status "Added member#{membership_id ? " (id=#{membership_id})" : ''}."
+end
+
+register "teams:members:remove", "Remove a member from a team (usage: wokku teams:members:remove TEAM_ID MEMBERSHIP_ID)" do
+  team_id = ARGV.shift || abort("Usage: wokku teams:members:remove TEAM_ID MEMBERSHIP_ID")
+  membership_id = ARGV.shift || abort("Missing MEMBERSHIP_ID. Get it from `wokku teams:members TEAM_ID`.")
+  api(:delete, "/teams/#{team_id}/members/#{membership_id}")
+  Wokku::Output.status "Member removed."
+end

data/lib/wokku/commands/tunnel.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+require "rbconfig"
+require "tempfile"
+
+# --- wokku tunnel: share a local port at https://<sub>.wokku.dev ---
+#
+# Path B per project_wokku_tunnel_path_decision (memory): frp gateway.
+# Wraps a downloaded `frpc` (one-time bootstrap, no platform-specific
+# gem dependency). User runs `wokku tunnel 3000`; we POST to the API
+# to provision a TunnelSession, write a per-process frpc.toml, exec
+# frpc, and DELETE the session on exit.
+
+FRPC_VERSION = "0.62.1"
+
+def tunnel_frpc_path
+  File.join(Dir.home, ".wokku", "bin", "frpc")
+end
+
+def tunnel_frpc_platform
+  case RbConfig::CONFIG["host_os"]
+  when /darwin/  then "darwin_#{tunnel_frpc_arch}"
+  when /linux/   then "linux_#{tunnel_frpc_arch}"
+  when /mswin|mingw|cygwin/ then "windows_amd64"
+  else abort "Unsupported OS: #{RbConfig::CONFIG['host_os']}"
+  end
+end
+
+def tunnel_frpc_arch
+  case RbConfig::CONFIG["host_cpu"]
+  when /arm64|aarch64/ then "arm64"
+  when /x86_64|amd64/  then "amd64"
+  else abort "Unsupported CPU: #{RbConfig::CONFIG['host_cpu']}"
+  end
+end
+
+def tunnel_ensure_frpc!
+  return tunnel_frpc_path if File.executable?(tunnel_frpc_path)
+
+  warn "→ fetching tunnel helper (frpc #{FRPC_VERSION}, ~10 MB, one time)…"
+  platform = tunnel_frpc_platform
+  archive  = "frp_#{FRPC_VERSION}_#{platform}.tar.gz"
+  url      = "https://github.com/fatedier/frp/releases/download/v#{FRPC_VERSION}/#{archive}"
+  ext      = platform.start_with?("windows") ? ".zip" : ".tar.gz"
+  archive  = archive.sub(/\.tar\.gz\z/, ext)
+  url      = url.sub(/\.tar\.gz\z/, ext)
+
+  Dir.mktmpdir do |tmp|
+    archive_path = File.join(tmp, archive)
+    unless system("curl", "-fL", url, "-o", archive_path)
+      abort "Failed to download frpc from #{url}"
+    end
+    if ext == ".zip"
+      system("unzip", "-q", archive_path, "-d", tmp) || abort("unzip failed")
+    else
+      system("tar", "-C", tmp, "-xzf", archive_path) || abort("tar failed")
+    end
+    frpc_dir = Dir[File.join(tmp, "frp_#{FRPC_VERSION}_*")].first || abort("frpc not found in archive")
+    src = File.join(frpc_dir, platform.start_with?("windows") ? "frpc.exe" : "frpc")
+    FileUtils.mkdir_p(File.dirname(tunnel_frpc_path))
+    FileUtils.cp(src, tunnel_frpc_path)
+    File.chmod(0o755, tunnel_frpc_path)
+  end
+
+  tunnel_frpc_path
+end
+
+register "tunnel",
+         "Share a local port at https://<sub>.wokku.dev. Usage: wokku tunnel PORT [--subdomain S] [--app APP]" do
+  args = ARGV.dup
+  ARGV.clear
+
+  local_port    = args.shift&.to_i
+  abort "Usage: wokku tunnel PORT [--subdomain S] [--app APP]" unless local_port&.positive?
+
+  subdomain = nil
+  app_id    = nil
+  while (arg = args.shift)
+    case arg
+    when "--subdomain" then subdomain = args.shift
+    when "--app"       then app_id    = args.shift
+    end
+  end
+
+  payload = {}
+  payload[:subdomain]     = subdomain if subdomain
+  payload[:app_record_id] = app_id    if app_id
+
+  session = api(:post, "/tunnels", payload)
+  if session.is_a?(Hash) && session["error"]
+    abort "Failed to create tunnel: #{session['error']}"
+  end
+
+  tunnel_id  = session["tunnel_id"]
+  token      = session["token"]
+  frps_host  = session["frps_host"]
+  frps_port  = session["frps_port"]
+  public_url = session["public_url"]
+  sub        = session["subdomain"]
+
+  warn ""
+  warn "  → tunnel: #{public_url} → localhost:#{local_port}"
+  warn "  → press Ctrl-C to close"
+  warn ""
+
+  frpc = tunnel_ensure_frpc!
+
+  cfg = Tempfile.new([ "frpc-", ".toml" ])
+  cfg.write(<<~TOML)
+    serverAddr = "#{frps_host}"
+    serverPort = #{frps_port}
+
+    [[proxies]]
+    name      = "wokku-#{sub}"
+    type      = "http"
+    localPort = #{local_port}
+    subdomain = "#{sub}"
+
+    [proxies.metadatas]
+    token = "#{token}"
+  TOML
+  cfg.close
+
+  cleanup = lambda do
+    File.unlink(cfg.path) rescue nil
+    api(:delete, "/tunnels/#{tunnel_id}") rescue nil
+  end
+
+  %w[INT TERM].each do |sig|
+    Signal.trap(sig) do
+      cleanup.call
+      exit 0
+    end
+  end
+
+  status = system(frpc, "-c", cfg.path)
+  cleanup.call
+  exit(status ? 0 : 1)
+end

data/lib/wokku/commands/vitals.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# --- Core Web Vitals read (p75 per metric) ---
+
+register "vitals", "Show p75 per Core Web Vital (usage: wokku vitals APP)" do
+  id = ARGV.shift || abort("Usage: wokku vitals APP")
+  data = api(:get, "/apps/#{id}/vitals")
+  latest = data.is_a?(Hash) ? (data["latest"] || {}) : {}
+
+  if latest.values.all?(&:nil?)
+    Wokku::Output.status "no vitals collected yet"
+    next
+  end
+
+  %w[CLS LCP INP FCP TTFB].each do |metric|
+    row = latest[metric]
+    if row.nil?
+      Wokku::Output.status "#{metric}: —"
+    else
+      Wokku::Output.status "#{metric}: #{row['p75']} (n=#{row['sample_count']})"
+    end
+  end
+end

data/lib/wokku/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module Wokku
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wokku-cli
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Johannes Dwicahyo
@@ -43,16 +43,29 @@ files:
 - lib/wokku/commands/activity.rb
 - lib/wokku/commands/addons.rb
 - lib/wokku/commands/apps.rb
+- lib/wokku/commands/apps_lifecycle.rb
 - lib/wokku/commands/auth.rb
+- lib/wokku/commands/billing.rb
 - lib/wokku/commands/buildpacks.rb
+- lib/wokku/commands/cdn.rb
 - lib/wokku/commands/certs.rb
 - lib/wokku/commands/checks.rb
 - lib/wokku/commands/config.rb
+- lib/wokku/commands/cron.rb
 - lib/wokku/commands/databases.rb
+- lib/wokku/commands/db_monitor.rb
+- lib/wokku/commands/dev.rb
 - lib/wokku/commands/do.rb
 - lib/wokku/commands/domains.rb
+- lib/wokku/commands/github.rb
+- lib/wokku/commands/https.rb
 - lib/wokku/commands/logs.rb
+- lib/wokku/commands/maintenance.rb
 - lib/wokku/commands/mcp.rb
+- lib/wokku/commands/metrics.rb
+- lib/wokku/commands/monitor.rb
+- lib/wokku/commands/notifications.rb
+- lib/wokku/commands/previews.rb
 - lib/wokku/commands/ps.rb
 - lib/wokku/commands/releases.rb
 - lib/wokku/commands/run.rb
@@ -60,8 +73,11 @@ files:
 - lib/wokku/commands/shell.rb
 - lib/wokku/commands/ssh_keys.rb
 - lib/wokku/commands/storage.rb
+- lib/wokku/commands/teams.rb
 - lib/wokku/commands/templates.rb
+- lib/wokku/commands/tunnel.rb
 - lib/wokku/commands/version.rb
+- lib/wokku/commands/vitals.rb
 - lib/wokku/config.rb
 - lib/wokku/helpers.rb
 - lib/wokku/output.rb