Mobayilo CLI - Project Status

Mobayilo CLI - Project Status

Last Updated: 2026-02-20 Phase: Phase 7B Local Agent Runtime (In Progress)

---

🟢 Phase 0: Discovery & Documentation

Objective: Establish scope, architecture, and implementation direction for the Mobayilo CLI.

• Analyze Mobayilo Web App codebase.
• Draft CLI PRD.
• Draft CLI Project Summary.
• Draft CLI Project Status.
• Analyze gogcli reference architecture and command patterns.
• Propose phased implementation plan for backend + CLI delivery.

🟡 Phase 1: Backend API Hardening

Objective: Deliver secure CLI authentication and core backend CLI endpoints in Rails.

• Implement PersonalAccessToken in Rails.
• Create Api::Cli::TokensController for authentication.
• Create Api::Cli::ProfileController for balance/account info.
• Create Api::Cli::CallsController for triggering calls.

Test checklist (Phase 1)

• PersonalAccessToken model tests (validations, hashing, scopes, expiry/revocation behavior).
• Token issuer/verifier service tests.
• Request specs for CLI auth failures (401), expired tokens, and revoked tokens.
• Request specs for POST /api/cli/tokens, GET /api/cli/me, and POST /api/cli/calls.
• Rack::Attack throttle coverage for CLI endpoints.

Exit criteria:

• PersonalAccessToken migration and model are merged.
• CLI auth base (Api::Cli::BaseController) is in place and enforced.
• POST /api/cli/tokens, GET /api/cli/me, and POST /api/cli/calls are implemented. ✅ Phase 1 test checklist items are green.

⚪ Phase 2: CLI Scaffolding (Go)

Objective: Create a production-ready Go CLI foundation with Kong, secure token storage, and shared output primitives.

• Initialize Go project.
• Setup Kong for command parsing.
• Implement Keychain integration for token storage.

Test checklist (Phase 2)

• go test ./... passes for scaffolded packages.
• Keyring/token storage tests.
• Output formatting tests (--json vs human output).
• Root/global flag parsing tests (--json, --host, --token, --verbose).

Exit criteria:

• cli/ Go module is initialized with Kong command tree and package structure.
• Secure token storage and HTTP client foundations are implemented.
• Global flags work as documented.
• Phase 2 test checklist items are green.

⚪ Phase 3: Core Commands

Objective: Implement core user workflows (login, status, balance, rates, call) with stable UX and test coverage.

• moby login
• moby balance
• moby rates
• moby call

Test checklist (Phase 3)

• Unit tests for moby login, moby status, moby balance, moby rates, moby call with mocked API.
• Error-path tests for invalid destination, auth failures, and API error responses.
• Basic integration smoke tests against local Rails API.

Exit criteria:

• Core commands are implemented end-to-end with stable output formats.
• CLI command errors return consistent, actionable messages and exit codes. ✅ Phase 3 test checklist items are green.

⚪ Phase 4: Billing

Objective: Add top-up workflow support in CLI, including checkout URL handling and optional browser-open behavior.

• moby topup (opens Stripe Checkout in browser).

Test checklist (Phase 4)

• Unit tests for moby topup <amount> validation.
• Response handling tests for checkout URL extraction.
• --open fallback tests (open failure falls back to printing URL).
• Billing smoke test against local Rails API.

Exit criteria:

• moby topup supports URL output and optional browser-open flow.
• Billing command behavior is documented and test-covered. ✅ Phase 4 test checklist items are green.

🟢 Phase 5A: UX Simplification & Support Readiness

Objective: Reduce command friction for end users and provide support-ready production guidance.

• Add moby auth command group (auth login, auth status, auth logout).
• Keep legacy moby login and moby status working for compatibility.
• Default to production host behavior in user-facing docs (no required --host for standard usage).
• Enforce CLI top-up minimum of $5.00 at command validation layer.
• Add/refresh support docs:
  • cli-production-quickstart.md
  • cli-helpdesk-playbook.md

Test checklist (Phase 5A)

• go test ./... passes with new auth command group and top-up validation updates.
• Root parser test coverage includes moby auth status.
• Command tests cover auth logout token deletion behavior.
• Manual check: moby auth --help renders expected subcommands.
• Manual check: moby topup 4 returns minimum amount validation error.
• Docs build passes (pnpm --dir docs build).

Exit criteria:

• End-user docs show simplified production commands using moby auth ....
• Support team has a copy-paste runbook for guiding customers.
• Top-up minimum behavior is consistently enforced at CLI entry point. ✅ Phase 5A test checklist items are green.

🟡 Phase 5B: Frictionless Login & Token Management

Objective: Remove manual token copy/paste for most users and provide first-class token lifecycle controls.

• Add browser/device auth flow for moby auth login.
• Add backend device auth endpoints (start, poll, approve, deny).
• Add short-lived device auth records with expiry and throttling policy.
• Add web “CLI Access” settings page (desktop/mobile web):
  • create token with expiry and scope options
  • list tokens with created/last-used/expiry metadata
  • revoke one token or all tokens
• Add token expiry policy defaults (target: 30d default, configurable max).

Test checklist (Phase 5B)

• Rails request tests for device auth lifecycle (happy path + expiry + denial + rate limits).
• Rails tests for token settings page API/controllers and revoke flows.
• CLI tests for moby auth login browser/poll flow and storage behavior.
• CLI tests for auth error paths and retry behavior during polling.
• End-to-end smoke test from fresh machine state (auth login -> auth status).

Exit criteria:

• End user can run moby auth login without manually handling raw token strings.
• Support/admin can create/revoke/manage tokens from web settings.
• Token expiry defaults/policies are visible and enforced.

🟡 Phase 5C: Human-Friendly Number UX

Objective: Make caller-ID verification and calling resilient to non-E.164 user input.

• Improve moby caller-id request to accept flexible number formats and interactive prompts.
• Add country inference/prompt fallback and clear normalization preview before submission.
• Update backend/CLI confirm flow to support moby caller-id confirm <code> using stored verification reference.
• Improve moby call input UX to accept common local formats and normalize safely.
• Keep script-safe mode with explicit non-interactive behavior (--json, --no-prompt).

Test checklist (Phase 5C)

• CLI unit tests for number normalization from common user formats.
• CLI unit tests for prompt fallback when country/format is ambiguous.
• CLI tests for code-only confirm flow.
• Backend request tests for verification-reference confirm path.
• Manual smoke test with real caller-id request/confirm/call user journey.

Exit criteria:

• Users can complete caller-id request and call flow without knowing E.164 rules upfront.
• Caller-id confirm works with code-only command UX.
• Interactive flow remains deterministic and script mode remains stable.

🟡 Phase 6A: Distribution & Release Pipeline

Objective: Deliver reproducible CLI releases with installable binaries for end users (no source checkout required).

• Finalize release artifact matrix (darwin/linux + amd64/arm64).
• Add/validate GoReleaser config for moby binary + archives + checksums.
• Add tag-driven GitHub Actions release workflow.
• Publish release notes template including install commands and checksums.
• Add release verification runbook (artifact integrity + smoke checks).

Test checklist (Phase 6A)

• Dry-run release pipeline from tag candidate.
• Verify artifact download + checksum validation for all supported OS/arch.
• Manual install smoke on macOS and Linux from release artifacts.

Exit criteria:

• A tagged release publishes signed/verifiable assets and checksums.
• End users can install moby without cloning repository source.
• Release runbook is documented and repeatable.

🟡 Phase 6B: Installer Experience (mobycli.mobayilo.com/install.sh)

Objective: Provide a one-line installer with safe defaults and clear post-install onboarding.

• Implement install.sh hosted from mobycli.mobayilo.com.
• Detect platform (os/arch) and resolve compatible release asset.
• Verify downloaded artifact against published checksums before install.
• Install to user path (~/.local/bin) with optional privileged path support.
• Print next-step commands (moby auth login, moby auth status --json).
• Surface upgrade command in onboarding output (moby self-update).

Test checklist (Phase 6B)

• Fresh machine test: curl -fsSL https://mobycli.mobayilo.com/install.sh | sh.
• Negative-path tests: unsupported OS/arch and checksum mismatch via local scripted test (scripts/test_install_sh.sh).
• Reinstall/upgrade behavior test from older version to latest via local scripted test (scripts/test_install_sh.sh).

Exit criteria:

• Installer works on supported targets and fails safely on unsupported targets.
• Checksum verification is mandatory before binary installation.
• Post-install onboarding output is consistent with current CLI UX.

🟡 Phase 6C: Website Launch (mobycli.mobayilo.com)

Objective: Publish an install-first CLI site for users and support teams.

• Create static landing page with sections: Install, Quickstart, Commands, Troubleshooting, Links.
• Use production-first command examples (moby auth login, moby balance, moby call).
• Add copy-ready snippets for install and first-run smoke flow.
• Make moby self-update visible in public install/quickstart snippets.
• Configure DNS/TLS for mobycli.mobayilo.com.
• Add helpdesk-facing link to support playbook and customer quickstart.
• Add deployment workflow and website runbook.

Test checklist (Phase 6C)

• Cross-device rendering check (mobile + desktop).
• Link integrity check (install script URL, docs links, GitHub links).
• First-time user journey test from site -> install -> login -> status.

Exit criteria:

• mobycli.mobayilo.com is live with HTTPS and install path documented.
• A new user can complete first successful auth flow from website instructions alone.
• Helpdesk can use the same page for customer guidance.

🟡 Phase 6D: Private Repo Public Distribution Bridge

Objective: Keep source private while making installer downloads public and auth-free for end users.

• Refactor installer latest-version resolution from GitHub API to mobycli.mobayilo.com/releases/latest.json.
• Keep checksum verification against published checksums.txt in the public release path.
• Extend release workflow to deploy site payload with versioned release assets to Cloudflare Pages.
• Extend site deploy workflow to preserve/sync latest release payload from GitHub Releases.
• Update runbooks to document the public distribution bridge architecture.

Test checklist (Phase 6D)

• Local installer regression script passes after metadata-path refactor (scripts/test_install_sh.sh).
• Tag release validates releases/latest.json + versioned archive URLs on mobycli.mobayilo.com (v0.1.3).
• Public fresh-machine install succeeds with private source repository (curl -fsSL .../install.sh | sh) using the latest keyring fix release (>= v0.1.4).

Exit criteria:

• End users install successfully without GitHub credentials.
• Source repository remains private.
• Website deploys do not regress installer release payload availability.

🟡 Phase 7A: Backend Voice Agent Foundation

Objective: Enable terminal-first calling on desktop by issuing CLI-authenticated Twilio Voice tokens for a local moby-agent runtime.

• Add POST /api/cli/voice/token under bearer-token auth.
• Issue short-lived Twilio Voice access token for CLI actor identity.
• Add scope guard for voice token endpoint (cli and/or voice scope).
• Extend Twilio identity resolver for CLI voice identities (cli-user:*, cli-seat:*).
• Add Rack::Attack throttle for voice-token endpoint.

Test checklist (Phase 7A)

• Request tests for POST /api/cli/voice/token: missing token, expired token, insufficient scope, happy path.
• Service tests for voice token issuer (identity, expiry, voice grant wiring).
• Identity resolver tests for CLI identity prefixes and backward compatibility.
• Rack::Attack throttle registration test includes api/cli/voice/token.

Exit criteria:

• CLI-authenticated endpoint returns valid Twilio Voice token payload for a local agent.
• Twilio webhook identity resolution works for CLI-agent initiated calls.
• Scope, expiry, and auth boundaries are covered by tests.

🟡 Phase 7B: Local Agent Runtime & CLI Integration

Objective: Deliver an opt-in desktop-audio path for CLI calls via a local moby-agent runtime using Twilio Voice JS.

• Add local agent command group (moby agent run, moby agent status).
• Add local agent HTTP protocol (/health, /v1/calls, /v1/next_call, /v1/ui/ready).
• Add CLI API client support for POST /api/cli/voice/token.
• Add moby call --agent flow: mint voice token, queue call to local agent.
• Keep existing callback mode as fallback when agent path fails.
• Evaluate default mode switch from callback to agent after manual validation.

Test checklist (Phase 7B)

• Go tests for CreateVoiceToken API client method.
• Go tests for moby call --agent success path.
• Go tests for moby call --agent fallback-to-callback path.
• Go tests for moby agent status health handling.
• Manual macOS validation: moby agent run + moby call --agent with mic permission.

Exit criteria:

• Users can place a CLI call through local desktop audio when agent is running.
• moby call remains reliable via callback fallback if agent is unavailable.
• Agent path is documented for support and production quickstart.

---

Current Blockers

• Local dry-run limitation: this dev sandbox cannot reach external Go module proxy (proxy.golang.org), so GoReleaser snapshot validation must run in CI or a network-enabled machine.
• Latest CLI binary with keyring fallback fix must be published via a new release tag (>= v0.1.4).

Next Steps

1. Run manual macOS validation for moby agent run + moby call --agent.
2. Document agent usage in production quickstart/helpdesk docs.
3. Decide whether to keep --agent opt-in or switch default call mode after validation.
4. Publish next release tag (v0.1.4 or newer) so installers pick up keyring and agent improvements.