ContextBase CLI - Project Overview

A powerful Command Line Interface for interacting with the ContextBase MCP API

Project Description

ContextBase CLI is a command-line tool that provides a simple and efficient way to interact with the ContextBase MCP API. It allows users to manage their memory keys through straightforward commands, including storing, retrieving, searching, and managing data. The CLI offers a convenient interface for developers who prefer working in terminal environments.

Technology Stack

TypeScript

Node.js

Commander.js

Axios

Conf

npm

High-Level Architecture

flowchart TD User[Terminal User] --- CLI[ContextBase CLI] CLI --- API[ContextBase MCP API] API --- Storage[Memory Storage] subgraph CLI_Components["CLI Components"] Entry["Entry Point"] --- CommandParser["Command Parser"] CommandParser --- Commands["Commands"] Commands --- AuthCommands["Authentication Commands"] Commands --- MemoryCommands["Memory Commands"] AuthCommands --- Signup["signup"] AuthCommands --- Login["login"] AuthCommands --- Logout["logout"] MemoryCommands --- Set["set"] MemoryCommands --- Get["get"] MemoryCommands --- List["list"] MemoryCommands --- Search["search"] MemoryCommands --- Delete["delete"] end CLI --- CLI_Components classDef user fill:#d1e7dd,stroke:#20c997 classDef cli fill:#cfe2ff,stroke:#0d6efd classDef api fill:#e2e3e5,stroke:#6c757d classDef storage fill:#f8d7da,stroke:#dc3545 class User user class CLI cli class API api class Storage storage

Detailed Component Architecture

flowchart TD subgraph Core_CLI["Core CLI"] EntryPoint["bin/contextbase.ts"] --> CommanderSetup["Commander.js Setup"] CommanderSetup --> RegisterCommands["Register Commands"] RegisterCommands --> AuthCommands["Authentication Commands"] RegisterCommands --> MemoryCommands["Memory Operations"] AuthCommands --> SignupCommand["signup Command"] AuthCommands --> LoginCommand["login Command"] AuthCommands --> LogoutCommand["logout Command"] MemoryCommands --> SetCommand["set Command"] MemoryCommands --> GetCommand["get Command"] MemoryCommands --> ListCommand["list Command"] MemoryCommands --> SearchCommand["search Command"] MemoryCommands --> DeleteCommand["delete Command"] end subgraph Support_Modules["Support Modules"] API["api.ts"] --> AxiosInstance["Axios Instance"] API --> Interceptors["Request Interceptors"] Config["config.ts"] --> TokenStorage["Token Storage"] TokenStorage --> SetToken["setToken()"] TokenStorage --> GetToken["getToken()"] TokenStorage --> ClearToken["clearToken()"] end EntryPoint --> API CommandImplementations --> API CommandImplementations --> Config classDef core fill:#f0f7ff,stroke:#3b82f6 classDef support fill:#f0fdf4,stroke:#22c55e class Core_CLI core class Support_Modules support

Project Structure

contextbase-cli/ ├── dist/ # Compiled JavaScript files ├── node_modules/ # Dependencies ├── src/ # Source code │ ├── bin/ # CLI entry point │ │ └── contextbase.ts # Main CLI script │ ├── commands/ # Command implementations │ │ ├── delete.ts # Delete command │ │ ├── get.ts # Get command │ │ ├── list.ts # List command │ │ ├── login.ts # Login command │ │ ├── logout.ts # Logout command │ │ ├── search.ts # Search command │ │ ├── set.ts # Set command │ │ └── signup.ts # Signup command │ ├── api.ts # API client │ └── config.ts # Configuration and token management ├── .gitignore # Git ignore file ├── LICENSE # License file ├── README.md # Documentation ├── package.json # Package metadata and dependencies ├── package-lock.json # Dependency lock file └── tsconfig.json # TypeScript configuration

Command Flow

sequenceDiagram participant User as Terminal User participant CLI as ContextBase CLI participant Commander as Commander.js participant Command as Command Module participant API as API Client participant Backend as ContextBase API User->>CLI: Run command (e.g., contextbase set key value) CLI->>Commander: Parse command and options Commander->>Command: Execute command handler Command->>API: Make API request API->>Backend: Send HTTP request Backend->>API: Return response API->>Command: Process response Command->>User: Display result

Authentication Flow

sequenceDiagram participant User as Terminal User participant CLI as ContextBase CLI participant Config as Config Module participant API as API Client participant Backend as ContextBase API User->>CLI: contextbase login email password CLI->>API: POST /api/auth/login API->>Backend: Send credentials Backend->>API: Return JWT token API->>Config: Store token locally Config->>User: Display success message Note over User,Backend: For subsequent operations User->>CLI: contextbase get key CLI->>API: Prepare request API->>Config: Get stored token Config->>API: Return token API->>Backend: Send authenticated request Backend->>API: Return data API->>User: Display result

Command Structure

flowchart LR subgraph Authentication_Commands["Authentication Commands"] Signup["signup email password"] --- SignupDesc["Create new account"] Login["login email password"] --- LoginDesc["Authenticate user"] Logout["logout"] --- LogoutDesc["Clear stored token"] end subgraph Memory_Commands["Memory Commands"] Set["set key value [--ttl]"] --- SetDesc["Store key-value pair"] Get["get key [--json]"] --- GetDesc["Retrieve value by key"] List["list [--json]"] --- ListDesc["List all memory keys"] Search["search query [--json]"] --- SearchDesc["Search for keys"] Delete["delete key"] --- DeleteDesc["Remove a key"] end classDef auth fill:#dbeafe,stroke:#3b82f6 classDef memory fill:#dcfce7,stroke:#22c55e class Authentication_Commands auth class Memory_Commands memory

API Integration

flowchart TD subgraph API_Module["API Module (api.ts)"] AxiosCreate["Create Axios Instance"] --> BaseURL["Set Base URL"] BaseURL --> Headers["Set Default Headers"] Headers --> Interceptor["Add Request Interceptor"] Interceptor --> GetToken["Get Token from Config"] GetToken --> AddAuth["Add Authorization Header"] end subgraph API_Usage["API Usage in Commands"] LoginCmd["login.ts"] --> PostLogin["api.post('/api/auth/login')"] SignupCmd["signup.ts"] --> PostSignup["api.post('/api/auth/signup')"] SetCmd["set.ts"] --> PostMemory["api.post('/api/memory')"] GetCmd["get.ts"] --> GetMemory["api.get('/api/memory/{key}')"] ListCmd["list.ts"] --> GetAllMemory["api.get('/api/memory')"] SearchCmd["search.ts"] --> GetSearch["api.get('/api/memory/search/{query}')"] DeleteCmd["delete.ts"] --> PostDelete["api.post('/api/memory/delete')"] end API_Module --> API_Usage classDef module fill:#f0f7ff,stroke:#3b82f6 classDef usage fill:#f0fdf4,stroke:#22c55e class API_Module module class API_Usage usage

Configuration Management

flowchart TD subgraph Config_Module["Config Module (config.ts)"] ConfSetup["Create Conf Instance"] --> ProjectName["Set Project Name"] ProjectName --> TokenFunctions["Token Management Functions"] TokenFunctions --> SetToken["setToken()"] TokenFunctions --> GetToken["getToken()"] TokenFunctions --> ClearToken["clearToken()"] end subgraph Config_Usage["Config Usage"] Login["login.ts"] --> UseSetToken["setToken()"] Signup["signup.ts"] --> UseSetToken Logout["logout.ts"] --> UseClearToken["clearToken()"] API["api.ts"] --> UseGetToken["getToken()"] end Config_Module --> Config_Usage classDef module fill:#f0f7ff,stroke:#3b82f6 classDef usage fill:#f0fdf4,stroke:#22c55e class Config_Module module class Config_Usage usage

Command Implementation Flow

flowchart LR A["Command Definition"] --> B["Parse Arguments"] B --> C["Validate Input"] C --> D["Call API"] D --> E["Process Response"] E --> F["Format Output"] F --> G["Display Result"] style A fill:#d4f4e2,stroke:#34d399,stroke-width:3px,color:#065f46,font-weight:bold style B fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e40af style C fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e40af style D fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e40af style E fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e40af style F fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e40af style G fill:#d4f4e2,stroke:#34d399,stroke-width:3px,color:#065f46,font-weight:bold

User Flow

flowchart LR A["Install CLI"] --> B["Authenticate"] B --> C["Perform Operations"] C --> D["View Results"] D --> E["Continue Operations"] E --> C style A fill:#d4f4e2,stroke:#34d399,stroke-width:3px,color:#065f46,font-weight:bold style B fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e40af style C fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e40af style D fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e40af style E fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e40af

Commander.js Integration

flowchart TD subgraph Commander_Setup["Commander.js Setup"] Initialize["Initialize Commander"] --> SetMetadata["Set CLI Metadata"] SetMetadata --> RegisterCommands["Register Commands"] RegisterCommands --> DefineArguments["Define Command Arguments"] DefineArguments --> DefineOptions["Define Command Options"] DefineOptions --> SetHandlers["Set Command Handlers"] SetHandlers --> ParseArgs["Parse Command Line Args"] end subgraph Command_Definition["Command Definition Example"] Command["program.command('set')"] --> Argument1["argument('key')"] Argument1 --> Argument2["argument('value')"] Argument2 --> Option["option('--ttl seconds')"] Option --> Description["description('Set a memory key')"] Description --> Action["action(setMemory)"] end Commander_Setup --- Command_Definition classDef setup fill:#f0f7ff,stroke:#3b82f6 classDef definition fill:#f0fdf4,stroke:#22c55e class Commander_Setup setup class Command_Definition definition

Development Workflow

sequenceDiagram participant Developer participant Git as Git Repository participant NPM as npm participant TypeScript as TypeScript Compiler participant CLI as CLI Binary Developer->>Git: Clone Repository Developer->>NPM: npm install NPM->>Developer: Dependencies Installed Developer->>Developer: Make Code Changes Developer->>TypeScript: npm run build TypeScript->>Developer: Compiled JavaScript Developer->>NPM: npm link NPM->>CLI: Create Global Link Developer->>CLI: Test Commands Developer->>Git: Commit Changes Developer->>NPM: npm publish

Future Enhancements

flowchart TD subgraph Planned_Features["Planned Features"] Interactive[Interactive Mode] --> REPL[REPL Interface] Interactive --> Autocomplete[Command Autocomplete] Output[Enhanced Output] --> ColorOutput[Colorized Output] Output --> TableOutput[Tabular Data Display] Output --> Formatting[Advanced Formatting] Config[Configuration] --> Profiles[Multiple Profiles] Config --> Endpoints[Custom Endpoints] Config --> DefaultOptions[Default Command Options] Scripting[Scripting Support] --> BatchCommands[Batch Command Execution] Scripting --> Pipelines[Command Pipelines] Scripting --> Automation[Automation Scripts] end classDef future fill:#f0f7ff,stroke:#3b82f6 class Planned_Features future

Getting Started

To use the ContextBase CLI:

Install the CLI:
- Run npm install -g contextbase-cli to install globally
- Or use with npx: npx contextbase-cli <command>
Authenticate:
- Sign up: contextbase signup <email> <password>
- Or log in: contextbase login <email> <password>
Perform operations:
- Set a memory: contextbase set <key> <value> [--ttl <seconds>]
- Get a memory: contextbase get <key> [--json]
- List all memories: contextbase list [--json]
- Search memories: contextbase search <query> [--json]
- Delete a memory: contextbase delete <key>
- Log out: contextbase logout

Conclusion

The ContextBase CLI provides a powerful and efficient way to interact with the ContextBase MCP API directly from the terminal. With its intuitive command structure and straightforward implementation, it offers developers a convenient tool for managing memory storage without the need for a graphical interface or custom code.

The CLI's architecture leverages Commander.js for command parsing, Axios for API requests, and Conf for local configuration storage, creating a robust foundation for terminal-based interactions with the ContextBase service.