Mobayilo CLI - Implementation Plan

Mobayilo CLI - Implementation Plan

Last Updated: 2026-02-19
Program Status: Phase 5A complete, Phase 5B next

1. Goal

Deliver a production-grade Mobayilo CLI (moby) with:

• secure persistent authentication
• caller-ID-gated outbound calling
• balance/rates visibility
• Stripe top-up flow
• support-ready documentation and predictable UX

2. Scope and Principles

• Production-first defaults for end users.
• Backward-compatible command evolution where possible.
• JSON output for scripting, human output for interactive use.
• Strong auth and rate-limiting on all CLI backend endpoints.
• Small coherent commits and test-backed phase exits.

3. Phase Overview (Progress View)

Phase	Status	Focus
Phase 0	✅ Complete	Discovery, PRD, architecture, phased plan
Phase 1	✅ Complete	Rails auth/token foundation + CLI API base
Phase 2	✅ Complete	Go CLI scaffold and shared packages
Phase 3	✅ Complete	Core commands (login/status/balance/rates/call)
Phase 4	✅ Complete	Billing (topup, --open)
Phase 5A	✅ Complete	Auth UX simplification + support docs + top-up min UX guard
Phase 5B	⏳ Planned (next)	Browser/device login + web token management
Phase 5C	⏳ Planned	Friendly number input and confirm-by-code flow

4. Completed Work (Phase-by-Phase)

4.1 Phase 1: Backend Auth Foundation (Rails First)

Delivered:

• PersonalAccessToken model and secure token format.
• token issuer/verifier services.
• Api::Cli::BaseController (Bearer auth + CLI error contract).
• Rack::Attack throttles for CLI endpoints.

Validated by:

• model + service tests.
• request tests for missing/invalid/revoked/expired tokens.

4.2 Phase 2: Go CLI Scaffold

Delivered:

• Go module in cli/.
• package structure:
  • internal/cmd
  • internal/api
  • internal/auth
  • internal/secrets
  • internal/outfmt
• global flags: --json, --host, --token, --verbose.

Validated by:

• go test ./... with parser/output/storage coverage.

4.3 Phase 3: Core Commands

Delivered:

• moby login
• moby status
• moby balance
• moby rates <iso>
• moby call <destination>
• backend call endpoint and auth integration.

Validated by:

• command unit tests (mock API).
• backend request tests.
• local smoke pass.

4.4 Phase 4: Billing

Delivered:

• moby topup <amount>
• --open browser behavior with print fallback.

Validated by:

• amount and response handling tests.
• local smoke pass.

4.5 Phase 5A: UX Simplification and Support Readiness

Delivered:

• moby auth command group:
  • moby auth login
  • moby auth status
  • moby auth logout
• backward compatibility for legacy moby login and moby status.
• production docs simplified to omit mandatory --host usage.
• support runbook added for helpdesk workflows.
• CLI top-up guard: minimum amount enforced at $5.00 in command validation.

Validated by:

• go test ./...
• moby auth --help manual check.
• moby topup 4 minimum validation manual check.
• docs build (pnpm --dir docs build).

5. Current Command Surface (User-Facing)

• moby auth login --api-token <TOKEN>
• moby auth status
• moby auth logout
• moby balance
• moby rates <ISO>
• moby caller-id request <NATIONAL_NUMBER> --country <ISO>
• moby caller-id confirm <NATIONAL_NUMBER> <SMS_CODE> --country <ISO>
• moby call <E164_DESTINATION>
• moby topup <AMOUNT> [--open] with minimum $5.00 at CLI layer

6. Remaining Roadmap

6.1 Phase 5B (Next): Frictionless Login + Token Management

Objective:

• remove raw token copy/paste for most users.

Planned deliverables:

• browser/device login flow for moby auth login.
• web settings page for CLI token lifecycle (create/revoke/list).
• token expiry options (default 30d, configurable policy).

Planned backend:

• device auth start/poll/approve endpoints.
• short-lived device auth record and state machine.
• throttling and expiry windows.

Planned CLI:

• browser-open login flow.
• polling and secure token persistence.

Exit criteria:

• new user can authenticate without manually pasting token.
• support can revoke/manage tokens in UI.

6.2 Phase 5C: Human-Friendly Number UX

Objective:

• reduce number-format friction for caller ID and calling.

Planned deliverables:

• moby caller-id request accepts flexible number input and guides user.
• moby call accepts flexible number input with normalization help.
• confirm flow target: moby caller-id confirm <code> backed by stored verification reference.

Exit criteria:

• common national-format inputs succeed without user knowing E.164 rules.
• confirm step can run with code-only UX.

7. Risks and Mitigations

• Risk: long-lived token abuse.
  • Mitigation: configurable TTL, revoke support, last-used tracking, scopes.
• Risk: support confusion during command migration.
  • Mitigation: keep aliases, update helpdesk templates, clear docs first.
• Risk: verification UX breaks by Twilio config variance.
  • Mitigation: explicit env checks + actionable CLI error messages.

8. Quality Gates (Per Phase)

• Rails: targeted request/model/service tests for backend changes.
• CLI: go test ./... plus manual smoke for changed command paths.
• Docs: pnpm --dir docs build.
• Delivery: coherent commits, status doc updates after each phase.

9. Recommended Execution Order From Today

1. Phase 5B backend device auth foundations.
2. Phase 5B web CLI token management page.
3. Phase 5B CLI browser-login implementation.
4. Phase 5C caller-id request/confirm UX simplification.
5. Phase 5C call input normalization UX.