This technical specification outlines the architecture, technology choices, and component design for a scalable Command Line Interface (CLI) application capable of interacting with multiple SaaS providers.
- Goal: Build an extensible CLI tool to query, manage, and automate workflows across disparate SaaS platforms (HubSpot, Semrush, Meta Ads, etc.).
- Key Challenge: normalizing authentication, rate limiting, and data structures across widely different APIs.
- Architectural Pattern: Modular/Plugin-based Architecture using the Adapter Pattern.
2. Architectural Design
The application will follow a Layered Architecture to separate the CLI user interface from the business logic and the external API integrations.
- Presentation Layer (CLI Interface):
- Handles user input (commands, flags, interactive prompts).
- Renders output (JSON, Tables, Spinners).
- Tools: Commander or Oclif (Node), Cobra (Go).
- Application Layer (Controller/Orchestrator):
- Parses the intent (e.g., "Get contacts").
- Routes requests to the correct Provider Adapter.
- Manages cross-cutting concerns: Authentication, Config, Logging.
- Adapter Layer (SaaS Integrations):
- Abstracts specific API details (endpoints, headers) into a common interface.
- Example: HubSpotAdapter and MetaAdapter both implement a generic fetchAnalytics() method.
- Infrastructure Layer:
- Network: HTTP Client with retry logic and rate limiting.
- Storage: Local configuration (YAML/JSON) and Secure Credential Storage (Keychain).
3. Technology Stack Options
Choose the stack that best aligns with your team's expertise and distribution goals.
| Component | Option A: Node.js (TypeScript) | Option B: Go (Golang) |
|---|---|---|
| Best For | Web developers, rapid iteration, huge ecosystem. | Performance, single-binary distribution. |
| Framework | Oclif (Open CLI Framework) or Commander.js. | Cobra (Industry standard for CLIs). |
| HTTP Client | Axios or Got (Excellent interceptors). | Resty or standard net/http. |
| Security | keytar (Node wrapper for system keychain). | keyring (Go library). |
| Distribution | npm install -g my-cli | brew install, apt, or direct binary download. |
Recommendation: If you plan to extend this with heavy logic or have a team of web developers, Node.js/TypeScript is often faster to develop. If you need a zero-dependency binary to ship to servers, Go is superior.
4. Component Detail: The "Provider" Adapter System
To support "Host of applications," you must avoid hardcoding API calls in your main logic. Instead, use an Interface/Contract.
TypeScript
interface SaasProvider {
name: string;
authenticate(): Promise<void>;
getEntity(entityType: string, id: string): Promise<any>;
listEntities(entityType: string, filters: any): Promise<any[]>;
}
| Provider | Authentication Strategy | Key Considerations |
|---|---|---|
| HubSpot | OAuth2 (Recommended) or Private App Token. | Rate limits are strictly enforced (e.g., 100 req/10s). The CLI must handle 429 errors with exponential backoff. |
| Semrush | API Key (passed in query params). | Costs "Units" per query. The CLI should implement a "Dry Run" mode to estimate cost before fetching. |
| Meta Ads | OAuth2 (User Access Token). | Tokens expire. The CLI requires a local callback server (e.g., localhost:3000) to capture the OAuth code during initial login. |
5. Core Modules Specification
- Storage: Never store API keys or tokens in plain text config.json files.
- Mechanism: Use the OS's native secure store (macOS Keychain, Windows Credential Manager, Linux Secret Service).
- Contexts: Support multiple profiles (e.g., my-cli login hubspot --profile=client-a).
- Problem: Meta Ads and HubSpot will ban your IP if you spam requests.
- Solution: Implement a Token Bucket algorithm or a simple request queue.
- Global Limit: Max 10 requests/second.
- Provider Limit: Configurable per adapter (e.g., Semrush = 5 req/sec).
Design your CLI to be intuitive using a noun -> verb or service -> noun -> verb pattern.
- cli hubspot contacts list --limit=50
- cli meta campaigns pause --id=12345
- cli semrush domain-overview --domain=example.com --export=csv
6. Development Roadmap
- Phase 1: Skeleton & Auth: Set up the CLI framework (Oclif/Cobra) and the Secure Storage manager. Implement cli login <service>.
- Phase 2: HubSpot MVP: Implement the HubSpotAdapter with basic GET requests (Contacts/Deals).
- Phase 3: The Generic HTTP Layer: Abstract the HTTP calls to handle retries and rate limiting automatically.
- Phase 4: Meta & Semrush: Add these adapters to prove the extensibility of your architecture.
- Phase 5: Output Formats: Add flags for --json (for piping to jq) and --table (for human readability).