@inkeep/agents-cli 0.1.0

package/LICENSE.md

@@ -0,0 +1,51 @@
+<!--
+AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
+Source: ./LICENSE.md
+This file is automatically copied from the root LICENSE.md during build.
+Any changes should be made to the root LICENSE.md file.
+-->
+
+Elastic License
+Acceptance
+By using the software, you agree to all of the terms and conditions below.
+
+Copyright License
+The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license to use, copy, distribute, make available, and prepare derivative works of the software, in each case subject to the limitations and conditions below.
+
+Limitations
+You may not provide the software to third parties as a hosted or managed service, where the service provides users with access to any substantial set of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality in the software, and you may not remove or obscure any functionality in the software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices of the licensor in the software. Any use of the licensor’s trademarks is subject to applicable law.
+
+Patents
+The licensor grants you a license, under any patent claims the licensor can license, or becomes able to license, to make, have made, use, sell, offer for sale, import and have imported the software, in each case subject to the limitations and conditions in this license. This license does not cover any patent claims that you cause to be infringed by modifications or additions to the software. If you or your company make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+Notices
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the software prominent notices stating that you have modified the software.
+
+No Other Rights
+These terms do not imply any licenses other than those expressly granted in these terms.
+
+Termination
+If you use the software in violation of these terms, such use is not licensed, and your licenses will automatically terminate. If the licensor provides you with a notice of your violation, and you cease all violation of this license no later than 30 days after you receive that notice, your licenses will be reinstated retroactively. However, if you violate these terms after such reinstatement, any additional violation of these terms will cause your licenses to terminate automatically and permanently.
+
+No Liability
+As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.
+
+Definitions
+The licensor is the entity offering these terms, and the software is the software the licensor makes available under these terms, including any portion of it.
+
+you refers to the individual or entity agreeing to these terms.
+
+your company is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. control means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+your licenses are all the licenses granted to you for the software under these terms.
+
+use means anything you do with the software requiring one of your licenses.
+
+trademark means trademarks, service marks, and similar rights.
+

package/README.md

@@ -0,0 +1,512 @@
+# Inkeep CLI
+
+A command-line interface for managing and interacting with Inkeep Agent Framework graphs.
+
+## Installation & Setup
+
+### Prerequisites
+
+- Node.js >= 20.x
+- pnpm package manager
+- Inkeep Agent Framework backend running (default: http://localhost:3002)
+
+### Quick Start
+
+> **📖 For detailed setup instructions, see [SETUP.md](./SETUP.md)**
+
+1. **Install and build**
+   ```bash
+   # Navigate to the CLI directory
+   cd /path/to/agent-framework/agents-cli
+   
+   # Install dependencies
+   pnpm install
+   
+   # Build the CLI
+   pnpm build
+   ```
+
+2. **Install globally** (recommended)
+   
+   **Option A: Using npm link (for development)**
+   ```bash
+   # Create global symlink from the agents-cli directory
+   npm link
+   
+   # Verify installation
+   which inkeep  # Should show path to inkeep command
+   ```
+   
+   **Option B: Using pnpm/npm global install (after publishing)**
+   ```bash
+   # Install the scoped package globally
+   pnpm add -g @inkeep/agents-cli
+   # or
+   npm install -g @inkeep/agents-cli
+   
+   # Verify installation
+   inkeep --version
+   ```
+   
+   **Note:** 
+   - For local development, use `npm link` (more reliable than `pnpm link --global`)
+   - The command is still `inkeep` even though the package name is `@inkeep/agents-cli`
+   - If linking fails, try unlinking first: `npm unlink -g @inkeep/agents-cli`
+
+3. **Configure tenant**
+   ```bash
+   # Set your tenant ID (required for most commands)
+   inkeep tenant your-tenant-id
+   
+   # Verify configuration
+   inkeep tenant
+   ```
+
+## Configuration
+
+### Configuration Sources (priority order)
+
+1. **Command-line flags** - Highest priority (e.g., `--tenant-id`, `--api-url`)
+2. **Environment variables** - `INKEEP_TENANT_ID`, `INKEEP_API_URL`
+3. **`.env` file** - In current directory
+4. **Config file** - `inkeep.config.ts` or `.inkeeprc.ts/js`
+5. **Defaults** - Lowest priority (api-url defaults to `http://localhost:3002`)
+
+### Environment Variables
+
+Create a `.env` file in your project directory:
+
+```bash
+INKEEP_TENANT_ID=your-tenant-id
+INKEEP_API_URL=http://localhost:3002
+```
+
+Or export them in your shell:
+
+```bash
+export INKEEP_TENANT_ID=your-tenant-id
+export INKEEP_API_URL=http://localhost:3002
+```
+
+## Commands
+
+### `inkeep tenant [tenant-id]`
+
+Manage tenant configuration.
+
+```bash
+# Set tenant ID
+inkeep tenant my-tenant
+
+# View current tenant ID
+inkeep tenant
+```
+
+### `inkeep list-graphs`
+
+List all available graphs for the current tenant.
+
+```bash
+inkeep list-graphs
+
+# With custom API URL
+inkeep list-graphs --url http://api.example.com:3002
+```
+
+Output:
+```
+┌─────────────────────────┬────────────────────┬───────────────┬───────────┐
+│ Graph ID                │ Name               │ Default Agent │ Created   │
+├─────────────────────────┼────────────────────┼───────────────┼───────────┤
+│ customer-support-graph  │ Customer Support   │ router        │ 1/15/2025 │
+│ qa-assistant           │ QA Assistant       │ qa-agent      │ 1/14/2025 │
+└─────────────────────────┴────────────────────┴───────────────┴───────────┘
+```
+
+### `inkeep push <config-path>`
+
+Push a graph configuration to the backend.
+
+```bash
+# Push a graph configuration
+inkeep push ./my-graph.js
+
+# With custom API URL
+inkeep push ./graph.ts --url http://api.example.com:3002
+```
+
+**Features:**
+- Automatically injects tenant ID and API URL from `inkeep.config.ts`
+- Validates exactly one AgentGraph is exported
+- Warns about dangling resources (unreferenced agents/tools)
+- Shows graph summary after successful push
+- Handles graph initialization automatically
+
+**Graph naming convention:** Graph files should follow the `*.graph.ts` naming pattern (e.g., `customer-support.graph.ts`, `qa-assistant.graph.ts`)
+
+**Example graph configuration:**
+
+```javascript
+// customer-support.graph.ts
+import { agent, agentGraph, tool } from '@inkeep/agents-manage-api/builder';
+
+const assistantAgent = agent({
+    id: 'assistant',
+    name: 'Assistant',
+    instructions: 'Help users with their questions',
+    tools: {
+        search: searchTool
+    }
+    // No tenantId needed - injected by CLI
+});
+
+// Must export exactly one graph
+export const graph = agentGraph({
+    id: 'my-assistant',
+    name: 'My Assistant Graph',
+    defaultAgent: assistantAgent,
+    agents: {
+        assistant: assistantAgent
+    }
+    // No tenantId or apiUrl needed - CLI injects from config
+});
+// No graph.init() call - CLI handles initialization
+```
+
+### `inkeep chat [graph-id]`
+
+Start an interactive chat session with a graph.
+
+```bash
+# Chat with specific graph
+inkeep chat my-graph-id
+
+# Interactive graph selection (with search)
+inkeep chat
+
+# With custom API URL
+inkeep chat --url http://api.example.com:3002
+```
+
+**Interactive Features:**
+- **Graph selection**: If no graph ID provided, shows searchable list
+- **Chat commands**:
+  - `help` - Show available commands
+  - `clear` - Clear screen (preserves context)
+  - `history` - Show conversation history
+  - `reset` - Reset conversation context
+  - `exit` - End chat session
+
+### `inkeep mcp start <graph-file>`
+
+Start MCP (Model Context Protocol) servers defined in a graph file.
+
+```bash
+# Start MCP servers from a TypeScript graph file
+inkeep mcp start examples/agent-configurations/graph.graph.ts
+
+# Start from compiled JavaScript
+inkeep mcp start dist/examples/agent-configurations/graph.graph.js
+
+# Run in detached mode
+inkeep mcp start graph.graph.ts --detached
+
+# Show verbose output
+inkeep mcp start graph.graph.ts --verbose
+```
+
+**Features:**
+- Supports both TypeScript (`.ts`) and JavaScript (`.js`) files
+- Automatically allocates ports for local servers (3100-3200)
+- Shows server names, ports, and URLs
+- Distinguishes between local (🏠) and remote (☁️) servers
+
+### `inkeep mcp stop`
+
+Stop running MCP servers.
+
+```bash
+# Stop all servers
+inkeep mcp stop --all
+
+# Stop servers for a specific graph
+inkeep mcp stop --graph customer-support-graph
+```
+
+### `inkeep mcp status`
+
+Show status of all MCP servers.
+
+```bash
+inkeep mcp status
+```
+
+Output shows:
+- Process ID
+- Graph ID
+- Tool name
+- Port/URL
+- Running status
+- Uptime
+
+### `inkeep mcp list`
+
+List all MCP servers with detailed information.
+
+```bash
+# Default tree view
+inkeep mcp list
+
+# Table format
+inkeep mcp list --format table
+
+# Verbose output (includes descriptions)
+inkeep mcp list --verbose
+```
+
+
+
+## Complete Workflow Example
+
+### Basic Setup
+```bash
+# Install and link CLI
+cd agents-cli
+pnpm install
+pnpm build
+npm link
+
+# Configure tenant
+inkeep tenant test-tenant
+```
+
+### Working with Graphs and MCP Servers
+
+1. **Create a graph with MCP tools** (`my-graph.graph.ts`)
+```typescript
+import { agent, agentGraph, mcpServer } from '@inkeep/agents-manage-api/builder';
+
+// Define MCP servers (tools)
+const randomNumberServer = mcpServer({
+    name: 'random_number',
+    description: 'Generates a random number',
+    execute: async () => Math.random()
+});
+
+const weatherServer = mcpServer({
+    name: 'weather_api',
+    description: 'Get weather information',
+    serverUrl: 'https://api.weather.example.com/mcp'
+});
+
+// Define agents
+const assistantAgent = agent({
+    id: 'assistant',
+    name: 'Assistant',
+    instructions: 'Help users with various tasks',
+    tools: {
+        random: randomNumberServer,
+        weather: weatherServer
+    }
+});
+
+// Export the graph
+export const graph = agentGraph({
+    id: 'my-assistant',
+    name: 'My Assistant',
+    defaultAgent: assistantAgent,
+    agents: { assistant: assistantAgent }
+});
+
+// Export servers for MCP management
+export const servers = [randomNumberServer, weatherServer];
+```
+
+2. **Start MCP servers and chat**
+```bash
+# Start MCP servers (works with TypeScript directly!)
+inkeep mcp start my-graph.graph.ts
+
+# In another terminal, start chatting
+inkeep chat my-assistant
+
+# Try commands like:
+# > "Generate a random number"
+# > "What's the weather like?"
+```
+
+3. **Monitor and manage servers**
+```bash
+# Check server status
+inkeep mcp status
+
+# List all servers with details
+inkeep mcp list
+
+# Stop servers when done
+inkeep mcp stop --all
+```
+
+## Working with Different Environments
+
+### Development
+```bash
+# Using environment variable
+INKEEP_API_URL=http://localhost:3002 inkeep list-graphs
+
+# Using .env file
+echo "INKEEP_API_URL=http://localhost:3002" > .env
+inkeep chat my-graph
+```
+
+### Staging
+```bash
+# Using command flag
+inkeep push graph.js --url https://staging-api.example.com
+
+# Set in config file
+# Edit your inkeep.config.ts to set apiUrl: 'https://staging-api.example.com'
+```
+
+### Production
+```bash
+# Using environment variables
+export INKEEP_API_URL=https://api.example.com
+export INKEEP_TENANT_ID=prod-tenant
+inkeep list-graphs
+```
+
+## Development
+
+### Running from Source
+
+```bash
+# Without building (using tsx)
+pnpm tsx src/index.ts <command>
+
+# After building
+node dist/index.js <command>
+
+# Watch mode (auto-rebuild on changes)
+pnpm dev
+```
+
+### Testing
+
+```bash
+# Run tests
+pnpm test
+
+# Watch mode
+pnpm test:watch
+
+# Coverage report
+pnpm test:coverage
+```
+
+### Type Checking
+
+```bash
+pnpm typecheck
+```
+
+### Project Structure
+
+```
+agents-cli/
+├── src/
+│   ├── index.ts              # Main CLI entry point
+│   ├── config.ts             # Configuration management
+│   ├── api.ts                # API client for backend
+│   ├── commands/             # Command implementations
+│   │   ├── push.ts           # Push graph configurations
+│   │   ├── chat.ts           # Basic chat interface
+│   │   ├── chat-enhanced.ts  # Enhanced chat with autocomplete
+│   │   ├── tenant.ts         # Tenant management
+│   │   └── list-graphs.ts    # List graphs
+│   ├── types/                # TypeScript declarations
+│   └── __tests__/            # Test files
+├── dist/                     # Compiled JavaScript
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**"No tenant ID configured"**
+```bash
+# Set tenant ID
+inkeep tenant your-tenant-id
+
+# Or use environment variable
+export INKEEP_TENANT_ID=your-tenant-id
+```
+
+**"Failed to fetch graphs" or connection errors**
+```bash
+# Check if backend is running
+curl http://localhost:3002/health
+
+# Verify API URL
+echo $INKEEP_API_URL
+
+# Try with explicit URL
+inkeep list-graphs --url http://localhost:3002
+```
+
+
+**"Graph not found" when using chat**
+```bash
+# List available graphs first
+inkeep list-graphs
+
+# Use interactive selection
+inkeep chat
+# (Select from list)
+```
+
+**Command not found: inkeep**
+```bash
+# Ensure CLI is linked globally
+cd agents-cli
+npm link
+
+# Or if published, install globally
+pnpm add -g @inkeep/agents-cli
+# or
+npm install -g @inkeep/agents-cli
+
+# Or add to PATH manually (for development)
+export PATH="$PATH:/path/to/agents-cli/dist"
+```
+
+## Dependencies
+
+### Runtime Dependencies
+- **commander**: Command-line framework
+- **chalk**: Terminal styling
+- **dotenv**: Environment variable loading
+- **ora**: Loading spinners
+- **cli-table3**: Table formatting
+- **inquirer**: Interactive prompts
+- **inquirer-autocomplete-prompt**: Searchable selections
+
+### Development Dependencies
+- **typescript**: TypeScript compiler
+- **@types/node**: Node.js types
+- **vitest**: Testing framework
+- **@vitest/coverage-v8**: Coverage reporting
+
+## Requirements
+
+- Node.js >= 20.x
+- pnpm package manager
+- TypeScript 5.x
+- Inkeep Agent Framework backend
+
+## License
+
+MIT

package/dist/__tests__/api.test.d.ts

@@ -0,0 +1 @@
+export {};